Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
JAXB
The Java Architecture for XML Binding (JAXB) is a Java technology that enables you to generate Java classes from XML schemas. As part of this process, the JAXB technology also provides methods for unmarshalling an XML instance document into a content tree of Java objects, and then marshalling the content tree back into an XML document. JAXB provides a fast and convenient way to bind an XML schemas to a representation in Java code, making it easy for Java developers to incorporate XML data and processing functions in Java applications without having to know much about XML itself.
One benefit of the JAXB technology is that it hides the details and gets rid of the extraneous relationships in SAX and DOM--generated JAXB classes describe only the relationships actually defined in the source schemas. The result is highly portable XML data joined with highly portable Java code that can be used to create flexible, lightweight applications and Web services.
See Chapter 10 for a description of the JAXB architecture, functions, and core concepts and then see Chapter 11, which provides sample code and step-by-step procedures for using the JAXB technology.
JAXB Binding Process
Figure 1-1 shows the JAXB data binding process.
![]()
Figure 1-1 Data Binding Process
The JAXB data binding process involves the following steps:
- Generate classes from a source XML schema, and then compile the generated classes.
- Unmarshal XML documents conforming to the schema. Unmarshalling generates a content tree of data objects instantiated from the schema-derived JAXB classes; this content tree represents the structure and content of the source XML documents.
- Unmarshalling optionally involves validation of the source XML documents before generating the content tree. If your application modifies the content tree, you can also use the validate operation to validate the changes before marshalling the content back to an XML document.
- The client application can modify the XML data represented by a content tree by means of interfaces generated by the binding compiler.
- The processed content tree is marshalled out to one or more XML output documents.
Validation
There are two types of validation that a JAXB client can perform:
- Unmarshal-Time - Enables a client application to receive information about validation errors and warnings detected while unmarshalling XML data into a content tree, and is completely orthogonal to the other types of validation.
- On-Demand - Enables a client application to receive information about validation errors and warnings detected in the content tree. At any point, client applications can call the
Validator.validate
method on the content tree (or any sub-tree of it).Representing XML Content
Representing XML content as Java objects involves two kinds of mappings: binding XML names to Java identifiers, and representing XML schemas as sets of Java classes.
XML schema languages use XML names to label schema components, however this set of strings is much larger than the set of valid Java class, method, and constant identifiers. To resolve this discrepancy, the JAXB technology uses several name-mapping algorithms. Specifically, the name-mapping algorithm maps XML names to Java identifiers in a way that adheres to standard Java API design guidelines, generates identifiers that retain obvious connections to the corresponding schema, and is unlikely to result in many collisions.
Customizing JAXB Bindings
The default JAXB bindings can be overridden at a global scope or on a case-by-case basis as needed by using custom binding declarations. JAXB uses default binding rules that can be customized by means of binding declarations that can either be inlined or external to an XML Schema. 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.
Example
The following table illustrates some default XML Schema-to-JAXB bindings.
Schema-derived Class for USAddress.java
Only a portion of the schema-derived code is shown, for brevity. The following code shows the schema-derived class for the schema's complex type
USAddress
.public interface USAddress { String getName(); void setName(String); String getStreet(); void setStreet(String) ; String getCity(); void setCity(String); String getState(); void setState(String); int getZip(); void setZip(int); static final String COUNTRY="USA"; };Unmarshalling XML Content
To unmarshal XML content into a content tree of data objects, you first create a
JAXBContext
instance for handling schema-derived classes, then create anUnmarshaller
instance, and then finally unmarshal the XML content. For example, if the generated classes are in a package namedprimer.po
and the XML content is in a file namedpo.xml
:JAXBContext jc = JAXBContext.newInstance( "primer.po" ); Unmarshaller u = jc.createUnmarshaller(); PurchaseOrder po = (PurchaseOrder)u.unmarshal( new FileInputStream( "po.xml" ) );To enable unmarshal-time validation, you create the
Unmarshaller
instance normally, as shown above, and then enable theValidationEventHandler
:The default configuration causes the unmarshal operation to fail upon encountering the first validation error. The default validation event handler processes a validation error, generates output to
system.out
, and then throws an exception:} catch( UnmarshalException ue ) { System.out.println( "Caught UnmarshalException" ); } catch( JAXBException je ) { je.printStackTrace(); } catch( IOException ioe ) { ioe.printStackTrace();Modifying the Content Tree
Use the schema-derived JavaBeans component
set
and get methods to manipulate the data in the content tree.USAddress address = po.getBillTo(); address.setName( "John Bob" ); address.setStreet( "242 Main Street" ); address.setCity( "Beverly Hills" ); address.setState( "CA" ); address.setZip( 90210 );Validating the Content Tree
After the application modifies the content tree, it can verify that the content tree is still valid by calling the
Validator.validate
method on the content tree (or any subtree of it). This operation is called on-demand validation.try{ Validator v = jc.createValidator(); boolean valid = v.validateRoot( po ); ... } catch( ValidationException ue ) { System.out.println( "Caught ValidationException" ); ... }Marshalling XML Content
Finally, to marshal a content tree to XML format, create a
Marshaller
instance, and then marshal the XML content:
Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.