# JavaTM Architecture for XML Binding
JAXB RI Vendor Extensions
Customizations

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

Main: Release Notes | XJC | Ant task | Sample Apps | Changelog
JAXB RI Extensions: Runtime Properties | XJC Customizations
JAXB RI Schema Languages: W3C XML Schema | RELAX NG | DTD
JAXB Community: Java.net Homepage | Developer interest list | FAQ

## Customizations

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

- These features may only be used when the JAXB XJC binding compiler is run in the `"-extension"` mode.
- All of the JAXB RI vendor extensions are defined in the `"http://java.sun.com/xml/ns/jaxb/xjc"` namespace.
- The namespaces containing extension binding declarations are specified to a JAXB processor by the occurrence of the global attribute `@jaxb:extensionBindingPrefixes` within an instance of `<xs:schema>` element. The value of this attribute is a whitespace-separated list of namespace prefixes. For more information, please refer to section 6.1.1 of the JAXB Specification.

### Index of Customizations

- <xjc:serializable> - Generating Serializable Classes
- <xjc:superClass> - Extending a Common Super Class
- <xjc:dom> - Mapping to DOM
- <xjc:typeSubstitution> - Enabling Type Substitution
- <xjc:noMarshaller> <xjc:noUnmarshaller> <xjc:noValidator> <xjc:noValidatingUnmarshaller> - Generating light-weight runtime

### 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:

- Wildcards (`<xs:any>`)
- Model groups (`<xs:choice>,<xs:all>,<xs:sequence>`)
- Model group declarations (`<xs:group>`)
- Particles
- Element declarations (`<xs:element`)

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 access wildcard content or can be used to process a part of a document by using other technologies that require "raw" XML. By default, JAXB generates a getObject() method for accessing wildcard content, but it only supports "lax" handling which means that unknown content is discarded. Since this probably isn't the expected behavior, you should use the `<xjc:dom />` customization which will preserve all of the wildcard content.

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.

### Generating Light-weight Runtime

Some of the features that the generated code provides (such as validating unmarshaller) require supporting runtime libraries. Similarly, some of the features (such as marshalling) require sizable amount of code to be generated.

When the application doesn't use all the features of the generated code, you can say so to XJC so that it can generate smaller code. These four customization controls this behavior.

<xjc:noMarshaller />
  XJC will not generate the marshaller.
<xjc:noValidator />
  XJC will not generate the on-demand validator.
<xjc:noUnmarshaller />
  XJC will not generate the unmarshaller.
<xjc:noValidatingUnmarshaller />
  XJC will not generate the validating unmarshaller.

Those elements must be specified inside <jaxb:globalBindings>

Here's the list of savings (as of 1.0.3) with respect to the combinations of those options:

- Not having the on-demand validator reduces the generated class size.
- Not having both the on-demand validator and the marshaller allows the compiler to generate smaller code.
- Not having both the on-demand validator and the validating unmarshaller allows the generated code to run without `jaxb-libs.jar`.
- Not having both the validating unmarshaller and the unmarshaller reduces the generated class size.

See the following example:

>     <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:noMarshaller />
>            <xjc:noValidator />
>           </jaxb:globalBindings>
>         </xs:appinfo>
>       </xs:annotation>
>     .
>     .
>     .
>     </xs:schema>

For DTD compilation, these customizations can be specified directly under the root `xml-java-binding-schema` element as follows:

>     <xml-java-binding-schema
>       xmlns:xjc ="http://java.sun.com/xml/ns/jaxb/xjc">
>       <xjc:noMarshaller />
>       <xjc:noValidator />
>       .
>       .
>       .
>     </xml-java-binding-schema>

For RELAX NG compilation, these customizations can be specified anywhere but the effect is global. So typically they should be specified under the root element as follows:

>     <grammar
>       xmlns="http://relaxng.org/ns/structure/1.0"
>       xmlns:xjc ="http://java.sun.com/xml/ns/jaxb/xjc">
>       <xjc:noMarshaller />
>       <xjc:noValidator />
>       .
>       .
>       .
>     </grammar>

$Revision: 1.1 $
$Date: 2008/11/03 06:51:11 $