The JAXB API

JAXBContext context = JAXBContext.newInstance( "com.flutebank.schema" );

JAXBContext context = JAXBContext.newInstance( "com.flutebank.schema", myclassloader );

 JAXBContext context = JAXBContext.newInstance( "com.flutebank.schema" );
// create an Unmarshaller
 Unmarshaller unmars = context.createUnmarshaller();

The Java object representations that the XML is Unmarshalled into and Marshalled from are collectively called content trees. The tree represents a collection of object references defined by JAXB binding-compiler-generated interfaces.

Once created, the Unmarshaller can be applied to many different XML sources using convenient methods, as Table 13.3 shows.

Table 13.3: Unmarshalling from Different Sources

Unmarshalling method	Unmarshall from
public void Object umarshall(java.io.File f)	XML data from a file
public void Object unmarshall (org.xml.sax.InputSource source)	From the specified SAX InputSource (See )
public void Object unmarshall (java.io.InputStream is)	From any InputStream
public Object unmarshall (org.w3c.dom.Node node)	From a W3C DOM tree (See )
public void Object unmarshall (javax.xml.transform.Source source)	From the XML Source object. (See )
public void Object unmarshall(java.net.URL url)	From a network URL

The Unmarshaller has two other important functions:

• Performing validation during unmarshalling, to verify that the XML conforms to the schema. Upon invoking the setValidating(true), the Marshaller instance will be marked as a validating unmarshaller, and the JAXB provider performs XML validation against the schema used to generate the binding information:

  JAXBContext context = JAXBContext.newInstance("com.flutebank.schema");
  // create an Unmarshaller
   Unmarshaller unmars = context.createUnmarshaller();
   unmars.setValidating(true);
  // Any XML instance unmarshalled will now be validated against the schema used by the
  // binding compiler
  

• Registering app-defined event handlers that are notified of validation events. Developers write the event handlers by implementing the javax.xml .bind.ValidationEventHandler method and registering this handler with the Unmarshaller, using the setEventHandler method:

  JAXBContext context = JAXBContext.newInstance( "com.flutebank.schema" );
   // create an Unmarshaller
   Unmarshaller unmars = context.createUnmarshaller();
   MyValidator validr=new MyValidator():
   unmars.setEventHandler(validr);
  

The default validation handler in JAXB will terminate processing upon encountering the first fatal error. So if your app must recover gracefully or conditionally process the XML, consider overriding the default handler. This is analogous to the SAX handlers in .

Marshaller

The javax.xml.bind.Marshaller can be used to marshall object representations into XML format. The XML is based on the schema passed to the binding compiler and used to generate the initial Java bindings.

The marshaller is also created from the context:

JAXBContext context = JAXBContext.newInstance( "com.flutebank.schema" );
 // Other code here
 Marshaller mars = context.createMarshaller();
 mars.setProperty( Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE );
 mars.setProperty (Marshaller.JAXB_SCHEMA_LOCATION,
 "http://www.flutebank.com/schema purchaseorder.xsd");
mars.marshall( po, new FileOutputStream("modifiedpurchaseorder.xml"));

Much like the Unmarshaller, the Marshaller can marshal the Java object and its referenced objects (the content tree) into different destinations-files, DOM trees, and so on-summarized in Table 13.4.

Table 13.4: Marshalling Object Trees into Different Destinations

Marshalling method	Marshall the object and referenced objects therein into
public void marshall(Object obj, org.xml.sax.ContentHandler handler)	SAX2 events
public void marshall(Object obj, org.w3c.dom.Node node)	A DOM tree
public void marshall(Object obj, java.io.OutputStream os)	An output stream
public void marshall(Object obj, javax.xml.transform.Result result)	A javax.xml.transform.Result
Public void marshall(Object obj, java.io.Writer writer)	A Writer stream.

JAXB does not require that the Java content tree be valid or validated against the schema during the marshalling process to give the JAXB implementation the ability to support use cases where partial XML is generated. The provider may choose to disallow marshalling of invalid content and throw a MarshallException. As with the Unmarshaller, event handlers can be registered with the Marshaller using the setEventHandler(ValidationEventHandler handler) method. Even though there is no way to programmatically enable validation during the marshall operation, it is possible for validation events to be received by the handler. The default handler will stop the marshalling when the first fatal error is encountered.

Configuring the Marshaller

The Marshaller can be configured using four standard properties, described in Table 13.5, that affect the XML formatting and output. The properties are passed as name-value pairs using the setProperty method, as shown below.

Table 13.5: Marshaller Properties

Property	Description
jaxb.encoding	The Marshaller will use "UTF-8" by default. If needed the encoding can be changed using this property.
jaxb.formatted.output	By default the Marshaller will not format the output with line breaks and indentations. If this property is set to true the XML generated will be formatted for human readability.
jaxb.schemaLocation	Used to set the xsi:schemaLocation attribute in the generated XML. (See for details on this property.)
jaxb.noNamespaceSchemaLocation	Used to set the xsi:noNamespaceSchemaLocation property in the generated XML. (See for details on this property.)

Marshaller mars = context.createMarshaller();
Mars.setProperty( Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE );
 mars.setProperty (Marshaller.JAXB_SCHEMA_LOCATION,
 "http://www.flutebank.com/schema purchaseorder.xsd");

The Element Interface

JAXB defines the javax.xml.bind.Element interface used by the runtime as a marker for identifying the JAXB-generated binding interfaces. It has no methods. In some situations, app developers would need to write code implementing this interface. JAXB users always work with the generated Java binding interface and its methods, which encapsulate the name and value of the corresponding XML element. For example, the billingaddress element is mapped to the Billingaddress interface, which has methods to get/set the relevant types, which themselves are generated bindings. This was shown in Listing 13.2. In XML schemas, the xsd:any element can be used to refer to elements not specified in the schema. For example, in the following fragment, the occupation element can be extended to include other content with the any element:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault=
 "qualified">
 <xsd:element >
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element type="xsd:string"/>
 <xsd:element type="xsd:string"/>
 <xsd:element type="xsd:string"/>
<xsd:any minOccurs="0"/>
 </xsd:sequence>
 </xsd:complexType>
 </xsd:element>
</xsd:schema>

This schema results in the generated binding shown below, which must cater to the potential of arbitary XML elements being specified whose name or value is not known at compile time.

public interface OccupationType {
 String getEngineer();
 void setEngineer(String value);
 javax.xml.bind.Element getAny();
 void setAny(javax.xml.bind.Element value);
 String getTechnicalWriter();
 void setTechnicalWriter(String value);
 String getSeniorEngineer();
 void setSeniorEngineer(String value);
}

When using this interface in app code, the code is responsible for passing an instance that implements the javax.bind.xml.Element interface, as opposed to the procedure with other Java data types.