Chapter 11. Using XML Elements

XML Schema elements are used to define an instance of an element in an XML document. Elements are defined either in the global scope of an XML Schema document, or they are defined as a member of a complex type. When they are defined in the global scope, FUSE Services Framework maps them to a JAXB element class that makes manipulating them easier.

Overview

An element instance in an XML document is defined by an XML Schema element element in the global scope of an XML Schema document To make it easier for Java developers to work with elements, FUSE Services Framework maps globally scoped elements to either a special JAXB element class or to a Java class that is generated to match its content type.

How the element is mapped depends on if the element is defined using a named type referenced by the type attribute or if the element is defined using an in-line type definition. Elements defined with in-line type definitions are mapped to Java classes.

	Tip
	It is recommended that elements are defined using a named type because in-line types are not reusable by other elements in the schema.

XML Schema mapping

In XML Schema elements are defined using element elements. element elements has one required attribute. The name specifies the name of the element as it appears in an XML document.

In addition to the name attribute element elements have the optional attributes listed in Table 11.1.

Table 11.1. Attributes Used to Define an Element

Attribute	Description
`type`	Specifies the type of the element. The type can be any XML Schema primitive type or any named complex type defined in the contract. If this attribute is not specified, you will need to include an in-line type definition.
`nillable`	Specifies if an element can be left out of a document entirely. If `nillable` is set to `true`, the element can be omitted from any document generated using the schema.
`abstract`	Specifies if an element can be used in an instance document. `true` indicates that the element cannot appear in the instance document. Instead, another element whose `substitutionGroup` attribute contains the QName of this element must appear in this element's place. For information on how this attribute effects code generation see Java mapping of abstract elements.
`substitutionGroup`	Specifies the name of an element that can be substituted with this element. For more information on using type substitution see Element Substitution.
`default`	Specifies a default value for an element. For information on how this attribute effects code generation see Java mapping of elements with a default value.
`fixed`	Specifies a fixed value for the element.

Example 11.1 shows a simple element definition.

Example 11.1. Simple XML Schema Element Definition

<element name="joeFred" type="xsd:string" />

An element can also define its own type using an in-line type definition. In-line types are specified using either a complexType element or a simpleType element. Once you specify whether the type of data is complex or simple, you can define any type of data needed using the tools available for each type of data.

Example 11.2 shows an element definition with an in-line type definition.

Example 11.2. XML Schema Element Definition with an In-Line Type

<element name="skate">
  <complexType>
    <sequence>
      <element name="numWheels" type="xsd:int" />
      <element name="brand" type="xsd:string" />
    </sequence>
  </complexType>
</element>

Java mapping of elements with a named type

By default, globally defined elements are mapped to JAXBElement<T> objects where the template class is determined by the value of the element element's type attribute. For primitive types, the template class is derived using the wrapper class mapping described in Wrapper classes. For complex types, the Java class generated to support the complex type is used as the template class.

To support the mapping and to relieve the developer of unnecessary worry about an element's QName, an object factory method is generated for each globally defined element, as shown in Example 11.3.

Example 11.3. Object Factory Method for a Globally Scoped Element

public class ObjectFactory {

    private final static QName _name_QNAME = new QName("targetNamespace", "localName");

  ...
 
   @XmlElementDecl(namespace = "targetNamespace", name = "localName")
    public JAXBElement<type> createname(type value);

}

For example, the element defined in Example 11.1 results in the object factory method shown in Example 11.4.

Example 11.4. Object Factory for a Simple Element

public class ObjectFactory {

    private final static QName _JoeFred_QNAME = new QName("...", "joeFred");

  ...
 
   @XmlElementDecl(namespace = "...", name = "joeFred")
    public JAXBElement<String> createJoeFred(String value);

}

Example 11.5 shows an example of using a globally scoped element in Java.

Example 11.5. Using a Globally Scoped Element

JAXBElement<String> element = createJoeFred("Green");
String color = element.getValue();

Using elements with named types in WSDL

If a globally scoped element is used to define a message part, the generated Java parameter is not an instance of JAXBElement<T>. Instead it is mapped to a regular Java type or class.

Given the WSDL fragment shown in Example 11.6, the resulting method has a parameter of type String.

Example 11.6. WSDL Using an Element as a Message Part

<?xml version="1.0" encoding=";UTF-8"?>
<wsdl:definitions name="HelloWorld"
                  targetNamespace="http://apache.org/hello_world_soap_http"
                  xmlns="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="http://apache.org/hello_world_soap_http"
                  xmlns:x1="http://apache.org/hello_world_soap_http/types"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <wsdl:types>
    <schema targetNamespace="http://apache.org/hello_world_soap_http/types"
            xmlns="http://www.w3.org/2001/XMLSchema"
            elementFormDefault="qualified"><element name="sayHi">
      <element name="sayHi" type="string"/>
      <element name="sayHiResponse" type="string"/>
    </schema>
  </wsdl:types>

  <wsdl:message name="sayHiRequest">
    <wsdl:part element="x1:sayHi" name="in"/>
  </wsdl:message>
  <wsdl:message name="sayHiResponse">
    <wsdl:part element="x1:sayHiResponse" name="out"/>
  </wsdl:message>

  <wsdl:portType name="Greeter">
    <wsdl:operation name="sayHi">
      <wsdl:input message="tns:sayHiRequest" name="sayHiRequest"/>
      <wsdl:output message="tns:sayHiResponse" name="sayHiResponse"/>
    </wsdl:operation>
  </wsdl:portType>
  ...
</wsdl:definitions>

Example 11.7 shows the generated method signature for the sayHi operation.

Example 11.7. Java Method Using a Global Element as a Part

String sayHi(String in);

Java mapping of elements with an in-line type

When an element is defined using an in-line type, it is mapped to Java following the same rules used for mapping other types to Java. The rules for simple types are described in Using Simple Types. The rules for complex types are described in Using Complex Types.

When a Java class is generated for an element with an in-line type definition, the generated class is decorated with the @XmlRootElement annotation. The @XmlRootElement annotation has two useful properties: name and namespace. These attributes are described in Table 11.2.

Table 11.2. Properties for the @XmlRootElement Annotation

Property	Description
name	Specifies the value of the XML Schema `element` element's `name` attribute.
namespace	Specifies the namespace in which the element is defined. If this element is defined in the target namespace, the property is not specified.

The @XmlRootElement annotation is not used if the element meets one or more of the following conditions:

The element's nillable attribute is set to true

The element is the head element of a substitution group
For more information on substitution groups see Element Substitution.

Java mapping of abstract elements

When the element's abstract attribute is set to true the object factory method for instantiating instances of the type is not generated. If the element is defined using an in-line type, the Java class supporting the in-line type is generated.

Java mapping of elements with a default value

When the element's default attribute is used the defaultValue property is added to the generated @XmlElementDecl annotation. For example, the element defined in Example 11.8 results in the object factory method shown in Example 11.9.

Example 11.8. XML Schema Element with a Default Value

<element name="size" type="xsd:int" default="7"/>

Example 11.9. Object Factory Method for an Element with a Default Value

@XmlElementDecl(namespace = "...", name = "size", defaultValue = "7")
    public JAXBElement<Integer> createUnionJoe(Integer value) {
        return new JAXBElement<Integer>(_Size_QNAME, Integer.class, null, value);
    }