:::: MENU ::::
Browsing posts in: JAXB

More About Marshalling

The Marshaller class in the javax.xml.bind package provides the client application the ability to convert a Java content tree back into XML data. There is no difference between marshalling a content tree that is created manually using the factory methods and marshalling a content tree that is the result an unmarshal operation. Clients can marshal a Java content tree back to XML data to a java.io.OutputStream or a java.io.Writer. The marshalling process can alternatively produce SAX2 event streams to a registered ContentHandler or produce a DOM Node object.

A simple example that unmarshals an XML document and then marshals it back out is a follows:

JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );

// unmarshal from foo.xml
Unmarshaller u = jc.createUnmarshaller();
FooObject fooObj =
  (FooObject)u.unmarshal( new File( "foo.xml" ) );

// marshal to System.out
Marshaller m = jc.createMarshaller();
m.marshal( fooObj, System.out );

By default, the Marshaller uses UTF-8 encoding when generating XML data to a java.io.OutputStream or a java.io.Writer. Use the setProperty API to change the output encoding used during these marshal operations. Client applications are expected to supply a valid character encoding name as defined in the W3C XML 1.0 Recommendation (http://www.w3.org/TR/2000/REC-xml-20001006#charencoding) and supported by your Java Platform.

Client applications are not required to validate the Java content tree prior to calling one of the marshal APIs. There is also no requirement that the Java content tree be valid with respect to its original schema in order to marshal it back into XML data. Different JAXB Providers can support marshalling invalid Java content trees at varying levels, however all JAXB providers must be able to marshal a valid content tree back to XML data. A JAXB provider must throw a MarshalException when it is unable to complete the marshal operation due to invalid content. Some JAXB providers will fully allow marshalling invalid content, others will fail on the first validation error.

Table 1-2 shows the properties that the Marshaller class supports.

Table 1-2 Marshaller Properties

Property

Description

jaxb.encoding

Value must be a java.lang.String; the output encoding to use when marshalling the XML data. The Marshaller will use “UTF-8” by default if this property is not specified.

jaxb.formatted.output

Value must be a java.lang.Boolean; controls whether or not the Marshaller will format the resulting XML data with line breaks and indentation. A true value for this property indicates human readable indented XML data, while a false value indicates unformatted XML data. The Marshaller defaults to false (unformatted) if this property is not specified.

jaxb.schemaLocation

Value must be a java.lang.String; allows the client application to specify an xsi:schemaLocation attribute in the generated XML data. The format of the schemaLocation attribute value is discussed in an easy to understand, non-normative form in Section 5.6 of the W3C XML Schema Part 0: Primer and specified in Section 2.6 of the W3C XML Schema Part 1: Structures.

jaxb.noNamespaceSchemaLocation

Value must be a java.lang.String; allows the client application to specify an xsi:noNamespaceSchemaLocation attribute in the generated XML data.

More About Unmarshalling

The Unmarshaller class in the javax.xml.bind package provides the client application the ability to convert XML data into a tree of Java content objects. The unmarshal method for a schema (within a namespace) allows for any global XML element declared in the schema to be unmarshalled as the root of an instance document. The JAXBContext object allows the merging of global elements across a set of schemas (listed in the contextPath). Since each schema in the schema set can belong to distinct namespaces, the unification of schemas to an unmarshalling context should be namespace-independent. This means that a client application is able to unmarshal XML documents that are instances of any of the schemas listed in the contextPath; for example:

JAXBContext jc = JAXBContext.newInstance(
  "com.acme.foo:com.acme.bar" );

Unmarshaller u = jc.createUnmarshaller();

FooObject fooObj = 
  (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok

BarObject barObj = 
  (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok

BazObject bazObj = 
  (BazObject)u.unmarshal( new File( "baz.xml" ) ); 
  // error, "com.acme.baz" not in contextPath

A client application may also generate Java content trees explicitly rather than unmarshalling existing XML data. To do so, the application needs to have access and knowledge about each of the schema-derived ObjectFactory classes that exist in each of Java packages contained in the contextPath. For each schema-derived Java class, there will be a static factory method that produces objects of that type. For example, assume that after compiling a schema, you have a package com.acme.foo that contains a schema-derived interface named PurchaseOrder. To create objects of that type, the client application would use the following factory method:

ObjectFactory objFactory = new ObjectFactory();

com.acme.foo.PurchaseOrder po =
  objFactory.createPurchaseOrder();

JAXB Binding Framework

The JAXB binding framework is implemented in three Java packages:

  • The javax.xml.bind package defines abstract classes and interfaces that are used directly with content classes.

The javax.xml.bind package defines the Unmarshaller, Validator, and Marshaller classes, which are auxiliary objects for providing their respective operations.

The JAXBContext class is the entry point for a Java application into the JAXB framework. A JAXBContext instance manages the binding relationship between XML element names to Java content interfaces for a JAXB implementation to be used by the unmarshal, marshal and validation operations.

The javax.xml.bind package also defines a rich hierarchy of validation event and exception classes for use when marshalling or unmarshalling errors occur, when constraints are violated, and when other types of errors are detected.

  • The javax.xml.bind.util package contains utility classes that may be used by client applications to manage marshalling, unmarshalling, and validation events.

  • The javax.xml.bind.helper package provides partial default implementations for some of the javax.xml.bind interfaces. Implementations of JAXB can extend these classes and implement the abstract methods. These APIs are not intended to be directly used by applications using JAXB architecture.

Steps in the JAXB Binding Process

The general steps in the JAXB data binding process are:

  • Generate classes. An XML schema is used as input to the JAXB binding compiler to generate JAXB classes based on that schema.

  • Compile classes. All of the generated classes, source files, and application code must be compiled.

  • Unmarshal. XML documents written according to the constraints in the source schema are unmarshalled by the JAXB binding framework. Note that JAXB also supports unmarshalling XML data from sources other than files/documents, such as DOM nodes, string buffers, SAX Sources, and so forth.

  • Generate content tree. The unmarshalling process generates a content tree of data objects instantiated from the generated JAXB classes; this content tree represents the structure and content of the source XML documents.

  • Validate (optional). The unmarshalling process optionally involves validation of the source XML documents before generating the content tree. Note that if you modify the content tree in Step 6, below, you can also use the JAXB Validate operation to validate the changes before marshalling the content back to an XML document.

  • Process content. The client application can modify the XML data represented by the Java content tree by means of interfaces generated by the binding compiler.

  • Marshal. The processed content tree is marshalled out to one or more XML output documents. The content may be validated before marshalling.

To summarize, using JAXB involves two discrete sets of activities:

  • Generate and compile JAXB classes from a source schema, and build an application that implements these classes

  • Run the application to unmarshal, process, validate, and marshal XML content through the JAXB binding framework

These two steps are usually performed at separate times in two distinct phases. Typically, for example, there is an application development phase in which JAXB classes are generated and compiled, and a binding implementation is built, followed by a deployment phase in which the generated JAXB classes are used to process XML content in an ongoing “live” production setting.