JAXB2 Simplify Plugin

This plugin allows simplifying "complex" properties (ex. fooOrBarOrBaz generated from repeatable choices) into several "simple" properties (ex. foo, bar, baz).

Usage

• Add JAXB2 Basics to your build
• The plugin is activated by the -Xsimplify command line option.
• Declare http://jaxb2-commons.dev.java.net/basic/simplify as an extension namespace.
• Optionally add -Xsimplify-usePluralForm=true if you want collection property names to be pluralized (foo -> foos). Please see the pluralization option for more information.

In the schema directly:

<xs:schema ...
  xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
  xmlns:simplify="http://jaxb2-commons.dev.java.net/basic/simplify"
  jaxb:extensionBindingPrefixes="... simplify">

...
</xs:schema>

Or in the bindings file:

<jaxb:bindings ...
  xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:simplify="http://jaxb2-commons.dev.java.net/basic/simplify"
  jaxb:extensionBindingPrefixes="... simplify">

</jaxb:bindings>

• Use simplify:as-element-property or simplify:as-reference-property customization elements to specify, which properties you want to simplify. You can configure this elements directly in schema or in the bindings file.
• If you have trouble placing these customizations on the property, you may place them inside simplify:property customization with @name='myProperty' attribute on the class.

Reference

This plugin allows simplifying "complex" properties. Thes properties are often generated from repeatable choices like this one:

  <xs:complexType name="typeWithReferencesProperty">
    <xs:choice maxOccurs="unbounded">
      <xs:element name="foo" type="someType"/>
      <xs:element name="bar" type="someType"/>
    </xs:choice> 
  </xs:complexType>

  <xs:complexType name="typeWithElementsProperty">
    <xs:choice maxOccurs="unbounded">
      <xs:element name="foo" type="xs:string"/>
      <xs:element name="bar" type="xs:int"/>
    </xs:choice> 
  </xs:complexType>

By default, XJC will generate complex properties modelling several references or elements in one.

    @XmlElementRefs({
        @XmlElementRef(name = "foo", type = JAXBElement.class),
        @XmlElementRef(name = "bar", type = JAXBElement.class)
    })
    protected List<JAXBElement<SomeType>> fooOrBar;

    @XmlElements({
        @XmlElement(name = "foo", type = String.class)
        @XmlElement(name = "bar", type = Integer.class),
    })
    protected List<Serializable> fooOrBar;

These complex properties are required to model complex content of the XML schema adequately, i.e. to maintain the order of the elements in the repeatable choice.

Unfortunately, they are not idiomatic as bean properties. These properties are "heterogeneous" (in a sense that they store different types), which makes it hard to work with them.

However, if the order of the elements is not significant - that is, you can live with the fact that it will change afte re-marshalling, the structures of these properties can be simplified: complex properties can be split into several simple properties.

The JAXB2 Simplify Plugin implements this task. It allows you to simplify your complex properties. The plugin will remove the complex property and insert several simpler properties instead of the original (complex) property.

The JAXB2 Simplify Plugin works with two kinds of properties: elements property and references property.

Simplifying elements property

Consider the following choice:

  <xs:complexType name="typeWithElementsProperty">
    <xs:choice maxOccurs="unbounded">
      <xs:element name="foo" type="xs:string"/>
      <xs:element name="bar" type="xs:int"/>
    </xs:choice> 
  </xs:complexType>

Normally this would generate a complex elements property:

    @XmlElements({
        @XmlElement(name = "foo", type = String.class)
        @XmlElement(name = "bar", type = Integer.class),
    })
    protected List<Serializable> fooOrBar;

Note that it models two elements with different names and types in one property. if you want to avoid this, you can use the simplify:as-element-property customization:

• In the bindings file:

<jaxb:bindings node="xs:complexType[@name='typeWithElementsProperty']/xs:choice">
  <simplify:as-element-property/>
</jaxb:bindings>

Alternatively place your customization on the type:

<jaxb:bindings node="xs:complexType[@name='typeWithElementsProperty']">
  <simplify:property name="fooOrBar">
    <simplify:as-element-property/>
  </simplify:property>
</jaxb:bindings>

• Directly in the schema:

  <xs:complexType name="typeWithElementsProperty">
    <xs:choice maxOccurs="unbounded">
      <xs:annotation>
        <xs:appinfo>
          <simplify:as-element-property/>
        </xs:appinfo>
      </xs:annotation>
      <xs:element name="foo" type="xs:string"/>
      <xs:element name="bar" type="xs:int"/>
    </xs:choice> 
  </xs:complexType>

Alternatively:

  <xs:complexType name="typeWithElementsProperty">
    <xs:annotation>
      <xs:appinfo>
        <simplify:property name="fooOrBar">
          <simplify:as-element-property/>
        </simplify:property>
      </xs:appinfo>
    </xs:annotation>
    <xs:choice maxOccurs="unbounded">
      <xs:element name="foo" type="xs:string"/>
      <xs:element name="bar" type="xs:int"/>
    </xs:choice> 
  </xs:complexType>

This will split one complex property into two simple ones:

    @XmlElement(name = "foo", type = String.class)
    protected List<String> foo;
    @XmlElement(name = "bar", type = Integer.class)
    protected List<Integer> bar;

As you can see, you will also get better typing.

Simplifying references property

Consider the following choice:

  <xs:complexType name="typeWithReferencesProperty">
    <xs:choice maxOccurs="unbounded">
      <xs:element name="foo" type="someType"/>
      <xs:element name="bar" type="someType"/>
    </xs:choice> 
  </xs:complexType>

This will normally generate a property like:

    @XmlElementRefs({
        @XmlElementRef(name = "foo", type = JAXBElement.class),
        @XmlElementRef(name = "bar", type = JAXBElement.class)
    })
    protected List<JAXBElement<SomeType>> fooOrBar;

You can use the simplify:as-element-property element to remodel this complex property as two element properties or simplify:as-reference-property as two reference properties.

Not that in the case of a reference property, you have to customize one of the xs:elements and not the xs:choice.

As element properties

• In the bindings file:

<jaxb:bindings node="xs:complexType [@name='typeWithReferencesProperty']/xs:choice/xs:element[@name='foo']">
  <simplify:as-element-property/>
</jaxb:bindings>

In some cases XJC does not attach customizations to these elements. Alternatively, you can customize your properties via the class:

<jaxb:bindings node="xs:complexType [@name='typeWithReferencesProperty']">
  <simplify:property name="fooOrBar">
    <simplify:as-element-property/>
  </simplify:property>
</jaxb:bindings>

• In the schema:

  <xs:complexType name="typeWithReferencesProperty">
    <xs:choice maxOccurs="unbounded">
      <xs:element name="foo" type="someType">
        <xs:annotation>
          <xs:appinfo>
            <simplify:as-element-property/>
          </xs:appinfo>
        </xs:annotation>
      </xs:element>
      <xs:element name="bar" type="someType"/>
    </xs:choice> 
  </xs:complexType>

Alternatively:

  <xs:complexType name="typeWithReferencesProperty">
    <xs:annotation>
      <xs:appinfo>
        <simplify:property name="fooOrBar">
          <simplify:as-element-property/>
        </simplify:property>
      </xs:appinfo>
    </xs:annotation>
    <xs:choice maxOccurs="unbounded">
      <xs:element name="foo" type="someType"/>
      <xs:element name="bar" type="someType"/>
    </xs:choice> 
  </xs:complexType>

Result:

    @XmlElement(name = "foo")
    protected List<SomeType> foo;
    @XmlElement(name = "bar")
    protected List<SomeType> bar;

As reference properties

  <xs:complexType name="typeWithReferencesProperty">
    <xs:choice maxOccurs="unbounded">
      <xs:element name="foo" type="someType">
        <xs:annotation>
          <xs:appinfo>
            <simplify:as-reference-property/>
          </xs:appinfo>
        </xs:annotation>
      </xs:element>
      <xs:element name="bar" type="someType"/>
    </xs:choice> 
  </xs:complexType>

Alternatively:

  <xs:complexType name="typeWithReferencesProperty">
    <xs:annotation>
      <xs:appinfo>
        <simplify:property name="fooOrBar">
          <simplify:as-reference-property/>
        </simplify:property>
      </xs:appinfo>
    </xs:annotation>
    <xs:choice maxOccurs="unbounded">
      <xs:element name="foo" type="someType"/>
      <xs:element name="bar" type="someType"/>
    </xs:choice> 
  </xs:complexType>

Result:

    @XmlElementRef(name = "foo", type = JAXBElement.class)
    protected List<JAXBElement<SomeType>> foo;
    @XmlElementRef(name = "bar", type = JAXBElement.class)
    protected List<JAXBElement<SomeType>> bar;

Element properties are simpler to work with than reference properties, but you may need to retain reference properties if you have substitution groups, for instance.

Options

Pluralization

The -Xsimplify-usePluralForm=true option turns on pluralization of the names of generated collection properties.

Consider the following schema fragment:

<xs:choice maxOccurs="unbounded">
  <xs:element name="child" type="xs:dateTime" maxOccurs="unbounded" />
  <xs:element name="foot" type="xs:string" maxOccurs="unbounded" />
  <xs:element name="foo" type="xs:int" maxOccurs="unbounded" />
</xs:choice> 

If pluralization is turned on, you'll get the following properties:

@XmlElement(name = "child", type = Date.class)
protected List<Date> children;

@XmlElement(name = "foot", type = String.class)
protected List<String> feet;

@XmlElement(name = "foo", type = Integer.class)
protected List<Integer> foos;

To retain backwards compatibility, pluralization is turned off by default.

Limitations

• The plugin does not support class references:

  <xs:element name="myElement" type="MyElementType">
    <xs:annotation>
      <xs:appinfo>
        <jaxb:class ref="com.acme.foo.MyClass"/>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>