SCDJWS Study Guide: JAXB


Printer-friendly version Printer-friendly version | Send this 
article to a friend Mail this to a friend


Previous Next vertical dots separating previous/next from contents/index/pdf Contents

Binding Can Be Customized


The binding language is an XML based language which defines constructs referred to as binding declarations. A binding declaration can be used to customize the default binding between an XML schema component and its Java representation.

The schema for binding declarations is defined in the namespace http://java.sun.com/xml/ns/jaxb. This specification uses the namespace prefix "jaxb" to refer to the namespace of binding declarations. For example:

<jaxb: binding declaration >

A binding compiler interprets the binding declaration relative to the source schema and a set of default bindings for that schema. Therefore a source schema need not contain a binding declaration for every schema component. This makes the job of a JAXB application developer easier.

There are two ways to associate a binding declaration with a schema element:

  • As part of the source schema (inline annotated schema).
  • External to the source schema in an external binding declaration.

The syntax and semantics of the binding declaration is the same regardless of which of the above two methods is used for customization.

Custom JAXB binding declarations also allow you to customize your generated JAXB classes beyond the XML-specific constraints in an XML schema to include Java-specific refinements such as class and package name mappings.

You do not need to provide a binding instruction for every declaration in your schema to generate Java classes. For example, the binding compiler uses a general name-mapping algorithm to bind XML names to names that are acceptable in the Java programming language. However, if you want to use a different naming scheme for your classes, you can specify custom binding declarations to make the binding compiler generate different names. There are many other customizations you can make with the binding declaration, including:

  • Name the package, derived classes, and methods
  • Assign types to the methods within the derived classes
  • Choose which elements to bind to classes
  • Decide how to bind each attribute and element declaration to a property in the appropriate content class
  • Choose the type of each attribute-value or content specification

Why Customize?


In most cases, the default bindings generated by the JAXB binding compiler will be sufficient to meet your needs. There are cases, however, in which you may want to modify the default bindings. Some of these include:

  • Creating javadoc for the schema-derived JAXB package, class, methods and constants; by adding custom javadoc annotations to your schema, you can explain concepts, guidelines, and rules specific to your implementation.
  • Providing semantically meaningful customized names for cases that the default XML name-to-Java identifier mapping cannot handle automatically; for example:
    • To resolve name collisions (as described in Appendix C.2.1 of the JAXB Specification). Note that the JAXB binding compiler detects and reports all name conflicts.
    • To provide names for typesafe enumeration constants that are not legal Java identifiers; for example, enumeration over integer values.
    • To provide better names for the Java representation of unnamed model groups when they are bound to a Java property or class.
    • To provide more meaningful package names than can be derived by default from the target namespace URI.
  • Overriding default bindings; for example:
  • Specify that a model group should be bound to a class rather than a list.
  • Specify that a fixed attribute can be bound to a Java constant.
  • Override the specified default binding of XML Schema built-in datatypes to Java datatypes. In some cases, you might want to introduce an alternative Java class that can represent additional characteristics of the builtin XML Schema datatype.

Inline Annotated Schema

This method of customization utilizes on the appinfo element specified by the XML Schema. A binding declaration is embedded within the appinfo element as illustrated below:

<xs:annotation>
  <xs:appinfo>
    <binding declaration>
  </xs:appinfo>
</xs:annotation>

The inline annotation where the binding declaration is used identifies the schema component.

Here are the changes you must make to the schema to make JAXB generate java.util.Vector rather than java.util.ArrayList, its default collection (the collecionType value must be either "indexed" or any fully qualified class name that implements java.util.List). Note that the top-level schema tag needs to be changed too:

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

     ...

    <xs:annotation>
      <xs:appinfo>
        <jxb:globalBindings collectionType="java.util.Vector" />
      </xs:appinfo>
    </xs:annotation>
     ...

The annotation tag introduces a part of the schema that is usually intended for schema processing software. The appinfo tag introduces instructions for a particular processing application (in this case, JAXB's xjc code-generation tool). Usually, each application uses its own namespace, as JAXB has done here.

Before customization:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="todolist">
   <xs:complexType>
     <xs:sequence>
       <xs:element maxOccurs="unbounded" minOccurs="0" name="item" type="entry"/>
     </xs:sequence>
   </xs:complexType>
  </xs:element>
  ...
</xs:schema>   


public class TodolistTypeImpl implements ... {
 
    protected com.sun.xml.bind.util.ListImpl _Item = new
    com.sun.xml.bind.util.ListImpl(new java.util.ArrayList());
     ...
}   

                                                           

After customization:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
   jxb:version="1.0">
  <xs:annotation>
   <xs:appinfo>
     <jxb:globalBindings collectionType="java.util.Vector" />
   </xs:appinfo>
  </xs:annotation>
   

  <xs:element name="todolist">
   <xs:complexType>
     <xs:sequence>
       <xs:element maxOccurs="unbounded" minOccurs="0" name="item" type="entry"/>
     </xs:sequence>
   </xs:complexType>

  </xs:element>
    ...
</xs:schema>   


public class TodolistTypeImpl implements ... {
   
protected com.sun.xml.bind.util.ListImpl _Item = new
com.sun.xml.bind.util.ListImpl(new java.util.Vector());
         ...
}   


External Binding Declaration


The external binding declaration format enables customized binding without requiring modification of the source schema. Unlike inline annotation, the remote schema component to which the binding declaration applies must be identified explicitly. The jaxb:bindings element enables the specification of a remote schema context to associate its binding declaration(s) with. Minimally, an external binding declaration follows the following format:


<jaxb:bindings schemaLocation = "xs:anyURI">
 
<jaxb:bindings node = "xs:string">*
   
<binding declaration>
 
<jaxb:bindings>
</jaxb:bindings>

The attributes schemaLocation and node are used to construct a reference to a node in a remote schema. The binding declaration is applied to this node by the binding compiler as if the binding declaration was embedded in the node’s xs:appinfo element. The attribute values are interpreted as follows:

  • schemaLocation - It is a URI reference to a remote schema.
  • node - It is an XPath 1.0 expression that identifies the schema node within schemaLocation to associate binding declarations with.

Previous Next vertical dots separating previous/next from contents/index/pdf Contents

  |   |