JAXB2 Simplify Plugin (original) (raw)

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

Usage

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">

...

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">

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:complexType name="typeWithElementsProperty"> <xs:choice maxOccurs="unbounded"> <xs:element name="foo" type="xs:string"/> <xs:element name="bar" type="xs:int"/>

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"/>

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:

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

Alternatively place your customization on the type:

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

Alternatively:

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

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"/>

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

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

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/

Alternatively:

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

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:element name="bar" type="someType"/>

Alternatively:

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

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" />

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

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

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

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

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

Limitations