JAXB Substitution XJC Plugin

A XJC plugin to fix eager generation of complicated fields when substitution head elements are referenced. The schema author will have to specifically target either the substitution head or the substitution head reference to enable this plugin.

License

License

GroupId

GroupId

io.fares.bind.xjc.plugins
ArtifactId

ArtifactId

jaxb-substitution-plugin
Last Version

Last Version

0.0.6
Release Date

Release Date

Type

Type

jar
Description

Description

JAXB Substitution XJC Plugin
A XJC plugin to fix eager generation of complicated fields when substitution head elements are referenced. The schema author will have to specifically target either the substitution head or the substitution head reference to enable this plugin.
Project URL

Project URL

https://github.com/bertramn/jaxb-substitution-plugin
Source Code Management

Source Code Management

https://github.com/bertramn/jaxb-substitution-plugin.git

Download jaxb-substitution-plugin

How to add to project

<!-- https://jarcasting.com/artifacts/io.fares.bind.xjc.plugins/jaxb-substitution-plugin/ -->
<dependency>
    <groupId>io.fares.bind.xjc.plugins</groupId>
    <artifactId>jaxb-substitution-plugin</artifactId>
    <version>0.0.6</version>
</dependency>
// https://jarcasting.com/artifacts/io.fares.bind.xjc.plugins/jaxb-substitution-plugin/
implementation 'io.fares.bind.xjc.plugins:jaxb-substitution-plugin:0.0.6'
// https://jarcasting.com/artifacts/io.fares.bind.xjc.plugins/jaxb-substitution-plugin/
implementation ("io.fares.bind.xjc.plugins:jaxb-substitution-plugin:0.0.6")
'io.fares.bind.xjc.plugins:jaxb-substitution-plugin:jar:0.0.6'
<dependency org="io.fares.bind.xjc.plugins" name="jaxb-substitution-plugin" rev="0.0.6">
  <artifact name="jaxb-substitution-plugin" type="jar" />
</dependency>
@Grapes(
@Grab(group='io.fares.bind.xjc.plugins', module='jaxb-substitution-plugin', version='0.0.6')
)
libraryDependencies += "io.fares.bind.xjc.plugins" % "jaxb-substitution-plugin" % "0.0.6"
[io.fares.bind.xjc.plugins/jaxb-substitution-plugin "0.0.6"]

Dependencies

compile (4)

Group / Artifact Type Version
org.jvnet.jaxb2_commons : jaxb2-basics-tools jar 0.12.0
org.slf4j : jcl-over-slf4j jar 1.7.26
ch.qos.logback : logback-classic jar 1.2.3
com.fasterxml.jackson.core : jackson-annotations jar 2.9.8

provided (3)

Group / Artifact Type Version
jakarta.xml.bind : jakarta.xml.bind-api jar 2.3.2
org.glassfish.jaxb : jaxb-xjc jar 2.3.2
org.glassfish.jaxb : codemodel jar 2.3.2

Project Modules

There are no modules declared in this project.

JAXB Substitution Group Plugin

XJC does some pretty strange stuff based on the assumption that someone will do weird things within the bounds of the XML schema specification. Unfortunately some of those assumptions result in generation of unusable JAXB binding classes. This plugin attempts to correct one of these subtle annoyances.

Usage

Configure the XJC compiler

The plugin can be used with any JAXB compiler that is capable of registering XJC plugins. The plugin jar needs to be made available to the XJC compiler classpath. In maven this is not the project classpath but the classpath of the plugin that generates code from one or more XML schema.

Example configuration for the JAXB2 commons compiler:

<plugin>
  <groupId>org.jvnet.jaxb2.maven2</groupId>
  <artifactId>maven-jaxb2-plugin</artifactId>
  <configuration>
    <plugins>
      <plugin>
        <groupId>io.fares.bind.xjc.plugins</groupId>
        <artifactId>jaxb-substitution-plugin</artifactId>
        <version>0.0.6</version>
      </plugin>
    </plugins>
    <extension>true</extension>
    <args>
      <arg>-Xsubstitution</arg>
    </args>
  </configuration>
</plugin>

Check out the unit tests and their respective schemata for all possible usage examples.

Why such a plugin?

Depending on whether the substitution group head is referenced in the same compilation multiple times or not, XJC compiler will create a JAXBElement<T> typed field. The following article on the java.net community goes into the details of this rather strange behaviour. In a nutshell, the compiler will make decisions on how to structure binding fields based on what substitution elements are available at design time rather than solving this problem at runtime. This design neglects the fact that one can build bindings in episodes which might introduce additional substitution candidates into the overall binding context.

This plugin will fix this XJC assumption and postpones the decision on what to do with additional substitution candidates to the binding runtime context.

Problem 1 - Using Element Ref with a Substitution Group Head

Lets say we have a schema where the Extension element is defined as a substitution head in at least 1 other XML element, XJC will create a ugly and unusable class with JaxbElement wrapped fields.

Schema:

<xsd:complexType name="Context">
  <xsd:sequence>
    <xsd:element ref="tns:Extension" minOccurs="0" maxOccurs="10"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:element name="Extension" type="tns:Extension" abstract="true"/>

<xsd:complexType name="Extension" abstract="true">
  <xsd:attribute name="type" type="xsd:string" use="required"/>
</xsd:complexType>

<xsd:element name="SomeExtension" type="tns:SomeExtension" substitutionGroup="tns:Extension"/>

<xsd:complexType name="SomeExtension">
  <xsd:complexContent>
    <xsd:extension base="tns:Extension"/>
  </xsd:complexContent>
</xsd:complexType>

Generated Class:

public class Context {

    @XmlElementRef(name = "Extension", namespace = "urn:test", type = JAXBElement.class, required = false)
    protected List<JAXBElement<? extends Extension>> extension;

}

Problem 2 - Using Inline Element based on a Substitution Group Head type

This variant will generate a properly formatted Java bean but when the JAXB marshaller tries to serialise the bean it will output xsi:type endcoded XML that is hard to work with in xml processing engines such as xquery.

Schema:

<xsd:complexType name="Context">
  <xsd:sequence>
    <xsd:element name="Extension" type="tns:Extension" minOccurs="0" maxOccurs="10"/>
  </xsd:sequence>
</xsd:complexType>

Generated Class:

public class Context {

  @XmlElement(name = "Extension")
  protected List<Extension> extension;

}

JAXB Output:

<Context xmlns="urn:test" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Extension xsi:type="SomeExtension"/>    
  <Extension xsi:type="OneExtension"/>
</Context>

Desired Behaviour

The ideal modelling state would be to just reference a xsd:element which is a substitution head.

  1. ensure the JAXBElement wrapper is not generated
  2. ensure any @XmlElement annotations at field or accessor level are replaced with the @XmlElementRef directive

Schema:

<xsd:complexType name="Context">
  <xsd:sequence>
    <xsd:element ref="tns:Extension" minOccurs="0" maxOccurs="10"/>
  </xsd:sequence>
</xsd:complexType>

Generated Class:

public class Context {

  @XmlElementRef(name = "Extension", required = false)
  protected List<Extension> extension;

}

JAXB Output:

<Context xmlns="urn:test">
  <SomeExtension/>
  <OneExtension/>
</Context>

Versions

Version
0.0.6
0.0.5
0.0.4
0.0.3
0.0.2
0.0.1