LibraryToggle FramesPrintFeedback

The object factory generated to support a package containing a substitution group has methods for each of the elements in the substitution group. For each of the members of the substitution group, except for the head element, the @XmlElementDecl annotation decorating the object factory method includes two additional properties, as described in Table 14.1.


The object factory method for the head element of the substitution group's @XmlElementDecl contains only the default namespace property and the default name property.

In addition to the element instantiation methods, the object factory contains a method for instantiating an object representing the head element. If the members of the substitution group are all of complex types, the object factory also contains methods for instantiating instances of each complex type used.

Example 14.5 shows the object factory method for the substitution group defined in Example 14.2.


If the head element of a substitution group is used as a message part in one of an operation's messages, the resulting method parameter will be an object of the class generated to support that element. It will not necessarily be an instance of the JAXBElement<? extends T> class. The runtime relies on Java's native type hierarchy to support the type substitution, and Java will catch any attempts to use unsupported types.

To ensure that the runtime knows all of the classes needed to support the element substitution, the SEI is decorated with the @XmlSeeAlso annotation. This annotation specifies a list of classes required by the runtime for marshalling. Fore more information on using the @XmlSeeAlso annotation see Adding Classes to the Runtime Marshaller.

Example 14.7 shows the SEI generated for the interface shown in Example 14.6. The interface uses the substitution group defined in Example 14.2.



[Tip]Tip

The SEI shown in Example 14.7 lists the object factory in the @XmlSeeAlso annotation. Listing the object factory for a namespace provides access to all of the generated classes for that namespace.

How you work with a substitution group depends on whether the code generator mapped the group to a straight Java class or to a JAXBElement<? extends T> class. When the element is simply mapped to an object of the generated value class, you work with the object the same way you work with other Java objects that are part of a type hierarchy. You can substitute any of the subclasses for the parent class. You can inspect the object to determine its exact class, and cast it appropriately.

[Tip]Tip

The JAXB specification recommends that you use the object factory methods for instantiating objects of the generated classes.

When the code generators create a JAXBElement<? extends T> object to hold instances of a substitution group, you must wrap the element's value in a JAXBElement<? extends T> object. The best method to do this is to use the element creation methods provided by the object factory. They provide an easy means for creating an element based on its value.

Example 14.10 shows code for setting an instance of a substitution group.

Example 14.10. Setting a Member of a Substitution Group

ObjectFactory of = new ObjectFactory(); 1
PlasticWidgetType pWidget = of.createPlasticWidgetType(); 2
pWidget.setShape = "round';
pWidget.setColor = "green";
pWidget.setMoldProcess = "injection";

JAXBElement<PlasticWidgetType> widget = of.createPlasticWidget(pWidget); 3

WidgetOrderInfo order = of.createWidgetOrderInfo(); 4
order.setWidget(widget); 5

The code in Example 14.10 does the following:

1

Instantiates an object factory.

2

Instantiates a PlasticWidgetType object.

3

Instantiates a JAXBElement<PlasticWidgetType> object to hold a plastic widget element.

4

Instantiates a WidgetOrderInfo object.

5

Sets the WidgetOrderInfo object's widget to the JAXBElement object holding the plastic widget element.

The object factory methods do not help when extracting the element's value from a JAXBElement<? extends T> object. You must to use the JAXBElement<? extends T> object's getValue() method. The following options determine the type of object returned by the getValue() method:

Example 14.11 shows code retrieving the value from a substitution group. To determine the proper class of the element's value object the example uses the element's getName() method.


Comments powered by Disqus
loading table of contents...