Simplify Plugin
 | Since 0.6.3. |
Simlify plugin
This plugin allows simplifying "complex" properties (ex. aOrBOrC generated from repeatable choices) into several "simple" properties (ex. a, b, c).
Activation
The plugin is activated by the -Xsimplify command line option.
Usage
- Declare http://jaxb2-commons.dev.java.net/basic/simplify as extension namespace:
<xs:schema ... xmlns:simplify="http://jaxb2-commons.dev.java.net/basic/simplify" jaxb:extensionBindingPrefixes="... simplify"
- Use simplify:as-element-property or simplify:as-reference-property customization elements to specify, which properties you want to simplify
| You can do all the customizations in the *.xjb files as well. |
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="a" type="someType"/> <xs:element name="b" type="someType"/> </xs:choice> </xs:complexType>
<xs:complexType name="typeWithElementsProperty"> <xs:choice maxOccurs="unbounded"> <xs:element name="a" type="xs:string"/> <xs:element name="b" type="xs:int"/> </xs:choice> </xs:complexType>
By default, XJC will complex properties modelling several references or elements in one.
@XmlElementRefs({
@XmlElementRef(name = "a", type = JAXBElement.class),
@XmlElementRef(name = "b", type = JAXBElement.class)
})
protected List<JAXBElement<SomeType>> aOrB;
@XmlElements({
@XmlElement(name = "a", type = String.class)
@XmlElement(name = "b", type = Integer.class),
})
protected List<Serializable> aOrB;
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 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 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="a" type="xs:string"/> <xs:element name="b" type="xs:int"/> </xs:choice> </xs:complexType>
Normally this would generate a complex elements property:
@XmlElements({
@XmlElement(name = "a", type = String.class)
@XmlElement(name = "b", type = Integer.class),
})
protected List<Serializable> aOrB;
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:
<xs:complexType name="typeWithElementsProperty"> <xs:choice maxOccurs="unbounded"> <xs:annotation> <xs:appinfo> <simplify:as-element-property/> </xs:appinfo> </xs:annotation> <xs:element name="a" type="xs:string"/> <xs:element name="b" type="xs:int"/> </xs:choice> </xs:complexType>
This will split one complex property into two simple ones:
@XmlElement(name = "a", type = String.class)
protected List<String> a;
@XmlElement(name = "b", type = Integer.class)
protected List<Integer> b;
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="a" type="someType"/> <xs:element name="b" type="someType"/> </xs:choice> </xs:complexType>
This will normally generate a property like:
@XmlElementRefs({
@XmlElementRef(name = "a", type = JAXBElement.class),
@XmlElementRef(name = "b", type = JAXBElement.class)
})
protected List<JAXBElement<SomeType>> aOrB;
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:element and not the xs:choice. |
As element properties
<xs:complexType name="typeWithReferencesProperty"> <xs:choice maxOccurs="unbounded"> <xs:element name="a" type="someType"> <xs:annotation> <xs:appinfo> <simplify:as-element-property/> </xs:appinfo> </xs:annotation> </xs:element> <xs:element name="b" type="someType"/> </xs:choice> </xs:complexType>
@XmlElement(name = "a")
protected List<SomeType> a;
@XmlElement(name = "b")
protected List<SomeType> b;
As reference properties
<xs:complexType name="typeWithReferencesProperty"> <xs:choice maxOccurs="unbounded"> <xs:element name="a" type="someType"> <xs:annotation> <xs:appinfo> <simplify:as-reference-property/> </xs:appinfo> </xs:annotation> </xs:element> <xs:element name="b" type="someType"/> </xs:choice> </xs:complexType>
@XmlElementRef(name = "a", type = JAXBElement.class)
protected List<JAXBElement<SomeType>> a;
@XmlElementRef(name = "b", type = JAXBElement.class)
protected List<JAXBElement<SomeType>> b;
| 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. |
Limitations
- The plugin does not support class references:
<xs:element name="issueJIIB44DummyClassRef" type="issueJIIB44DummyType"> <xs:annotation> <xs:appinfo> <jaxb:class ref="org.jvnet.jaxb2_commons.tests.issues.IssueJIIB44DummyClassRef"/> </xs:appinfo> </xs:annotation> </xs:element>
- There is currently no way to customize generated properties