JavaTM Architecture for XML Binding
JAXB RI Vendor Extensions
Customizations

Specification Version: 1.0
Reference Implementation (RI) Version: 1.0.2

Customizations

The JAXB RI provides additional customizations that are not defined by the JAXB specification. Note the following:

Index of Customizations

Generating Serializable Classes

Please Note: Given the experimental nature of serialization in this implementation's release, the serialization capability produced by JAXB RI v1.0 is not guaranteed to be serializable compatible with future releases. Subsequent versions of the JAXB specification hope to identify a portable binding framework runtime environment that would make it impossible to guarantee serialization capabilities with future releases.

Placing an <xjc:serializable> customization within your <jaxb:globalBindings> will cause the XJC binding compiler to generate classes that implement java.io.Serializable. This customization will not affect the generated interfaces, only the implementation classes contained in the impl subpackages. The following example illustrates how to place the <xjc:serializable> customization within the <jaxb:globalBindings> customization on the <xs:schema> element:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
           xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
           jaxb:extensionBindingPrefixes="xjc"
           jaxb:version="1.0">
         
    <xs:annotation>
       <xs:appinfo>
          <jaxb:globalBindings generateIsSetMethod="true">
              <xjc:serializable uid="12343"/>
          </jaxb:globalBindings>
       </xs:appinfo>
    </xs:annotation>
.
.
.
</xs:schema>
		

In the sample above, you can see the use of the optional @uid attribute which allows you to specify the serial version uid that is placed in each class. At this time, it is not possible to generate different uids in each class - you may only specify a single uid that is placed in all of the generated classes. For more information about using serial version uids, please read the Versioning of Serializable Objects section of the serialization documentation.

Please refer to the examples/vendor-extensions sample app for an example of how to use this feature.

Extending a Common Super Class

It is also possible to specify a common superclass that all generated implementation classes will extend. Again, this customization has no effect on the generated interfaces, only the implementation classes contained in the implementation subpackages.

The <xjc:superClass> customization allows you to specify the fully qualified name of the Java class that is to be used as the superclass. Like the <xjc:serializable> customization, the <xjc:superClass> customization can only occur within your <jaxb:globalBindings> customization on the <xs:schema> element and will only be allowed when xjc is run with the "-extension" switch:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
           xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
           jaxb:extensionBindingPrefixes="xjc"
           jaxb:version="1.0">

    <xs:annotation>
       <xs:appinfo>
          <jaxb:globalBindings generateIsSetMethod="true">
           <xjc:superClass name="org.acme.RocketBooster"/>
          </jaxb:globalBindings>
       </xs:appinfo>
    </xs:annotation>
.
.
.
</xs:schema>
		

In the sample above, the <xjc:superClass> customization will cause all of the generated implementation classes to extend the named class, org.acme.RocketBooster in this case.

The org.acme.RocketBooster class must be compiled and available on your classpath prior to using the XJC binding compiler to compile your schema (use the -classpath option of the xjc command). The examples/vendor-extensions sample application shows how to use this feature.

Mapping to DOM

The <xjc:dom> customization allows you to map a certain part of the schema into a DOM tree. This customization can be attached to the following schema components:

For example, in the following example, a wildcard is mapped to a DOM node. Each element that matches to the wildcard will be turned into a DOM tree.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
           xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
           jaxb:extensionBindingPrefixes="xjc"
           jaxb:version="1.0">

    <xs:element>
       <xs:complexType>
          <xs:sequence>
             <xs:any maxOccurs="unbounded" processContents="skip">
                <xs:annotation><xs:appinfo>
                  <xjc:dom />
                </xs:appinfo></xs:annotation>
             </xs:any>
          </xs:sequence>
       </xs:complexType>
    </xs:element>
.
.
.
</xs:schema>
		

This extension can be used to implement better wildcard support or can be used to process a part of a document by using other technologies that require "raw" XML.

You can use the optional type attribute to specify the type of DOM. By default, it is W3C DOM, but you can write <xjc:dom type="dom4j" /> to map it to dom4j.

Unfortunately, due to the lack of JDOM's functionality to write a single element to SAX events, at this moment JDOM is not supported.

Enabling Type Substitution

The <xjc:typeSubstitution> customization generates bindings that let you compose instances (in memory) using subclasses of a particular type wherever that type is expected, as specified by the schema. When you marshal the content tree, those elements are decorated with the appropriate value of xsi:type. In addition, the <xjc:typeSubstitution> customization lets you unmarshal elements decorated with xsi:type attributes as a subclass of the particular type, as specified by the schema.

The <xjc:typeSubstitution> customization requires the single attribute xjc:type, whose value must always be complex:

<xs:schema
   xmlns:xs  ="http://www.w3.org/2001/XMLSchema"
   xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
   xmlns:xjc ="http://java.sun.com/xml/ns/jaxb/xjc"
   jaxb:extensionBindingPrefixes="xjc"
   jaxb:version="1.0">
  
  <xs:annotation>
    <xs:appinfo>
      <jaxb:globalBindings>
       <xjc:typeSubstitution type="complex"/>
      </jaxb:globalBindings>
    </xs:appinfo>
  </xs:annotation>
.
.
.  
</xs:schema>
	  

See Type Substitution Support for a more detailed description of the support this customization enables. See Implications of Type Substitution for Subclassing if using type substitution with application-specific implementation classes.


$Revision: 1.18 $
$Date: 2003/09/26 18:58:23 $