8 Using the JAXB Class Generator

Using the JAXB Class Generator Command-Line Utility: Example

To test orjaxb, change into the $ORACLE_HOME/xdk/demo/java/jaxb/Sample1 directory. If you have run make, then the directory should contain the following files:

SampleApp1.class
SampleApp1.java
generated/
sample1.out
sample1.xml
sample1.xsd

The sample.xsd file is the XML schema associated with sample1.xml. The generated/ subdirectory contains the classes generated from the input schema. You can test orajaxb by deleting the contents of generated/ and regenerating the classes as follows:

rm generated/* 
orajaxb -schema sample1.xsd -targetPkg generated -verbose

The terminal should display the following output:

generated/CType.java
generated/AComplexType.java
generated/AnElement.java
generated/RElemOfCTypeInSameNs.java
generated/RType.java
generated/RElemOfSTypeInSameNs.java

generated/CTypeImpl.java
generated/AComplexTypeImpl.java
generated/AnElementImpl.java
generated/RElemOfCTypeInSameNsImpl.java
generated/RTypeImpl.java
generated/RElemOfSTypeInSameNsImpl.java
generated/ObjectFactory.java

Defining the Schema

Example 8-1 illustrates the XML data document that provides the input to the sample application. The sample3.xml document describes the address of an employee.

<?xml version="1.0"?>
<myAddress xmlns = "http://www.oracle.com/sample3/"
           xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation = "http://www.oracle.com/sample3 sample3.xsd">
    <name>James Bond</name>
    <doorNumber>420</doorNumber>
    <street>Oracle parkway</street>
    <city>Redwood shores</city>
    <state>CA</state>
    <zip>94065</zip>
    <country>United States</country>
</myAddress>

The XML schema shown in Example 8-2 defines the structure that you use to validate sample3.xml. The schema defines two complex types and one element, which are defined as follows:

• The first complex type, which is named Address, is a sequence of elements. Each element in the sequence describes one part of the address: name, door number, and so forth.

• The second complex type, which is named USAddress, uses the <extension base="exp:Address"> element to extend Address by adding U.S.-specific elements to the Address sequence: state, zip, and so forth. The exp prefix specifies the http://www.oracle.com/sample3/ namespace.

• The element is named myAddress and is of type exp:USAddress. The exp prefix specifies the http://www.oracle.com/sample3/ namespace. In sample3.xml, the myAddress top-level element, which is in namespace http://www.oracle.com/sample3/, conforms to the schema definition.

<?xml version="1.0"?>
 
<!-- Binding a complex type definition to java content interface
 The complex type definition is derived by extension
-->
 
<schema xmlns = "http://www.w3.org/2001/XMLSchema"
        xmlns:exp="http://www.oracle.com/sample3/"
        targetNamespace="http://www.oracle.com/sample3/"
        elementFormDefault="qualified">
 
   <complexType name="Address">
      <sequence>
         <element name="name" type="string"/>
         <element name="doorNumber" type="short"/>
         <element name="street" type="string"/>
         <element name="city" type="string"/>
      </sequence>
   </complexType>
 
  <complexType name="USAddress">
    <complexContent>
     <extension base="exp:Address">
       <sequence>
          <element name="state" type="string"/>
          <element name="zip" type="integer"/>
          <element name="country" type="string"/>
       </sequence>
     </extension>
    </complexContent>
  </complexType>
 
  <element name="myAddress" type="exp:USAddress"/>
 
</schema>

Generating and Compiling the Java Classes

If you have an XML document and corresponding XML schema, then the next stage of processing is to generate the Java classes from the XML schema. You can use the JAXB command-line interface described in "Using the JAXB Class Generator Command-Line Utility" to perform this task.

Assuming that your environment is set up as described in "Setting Up the Java XDK Environment", you can create the source files in the generated package as follows:

cd $ORACLE_HOME/xdk/demo/java/jaxb/Sample3
orajaxb -schema sample1.xsd -targetPkg generated

The preceding orajaxb command should create the following source files in the ./generated/ subdirectory:

Address.java
AddressImpl.java
MyAddress.java
MyAddressImpl.java
ObjectFactory.java
USAddress.java
USAddressImpl.java

The complex types Address and USAddress each has two associated source files, as does the element MyAddress. The source file named after the element contains the interface; the file with the suffix Impl contains the class that implements the interface. For example, Address.java contains the interface Address, whereas AddressImpl.java contains the class that implements Address.

The content of the Address.java source file is shown in Example 8-3.

package generated; 
public interface Address
{
   public void setName(java.lang.String n);
   public java.lang.String getName(); 
   public void setDoorNumber(short d);
   public short getDoorNumber(); 
   public void setStreet(java.lang.String s);
   public java.lang.String getStreet(); 
   public void setCity(java.lang.String c);
   public java.lang.String getCity(); 
}

The Address complex type defined a sequence of elements: name, doorNumber, street, and city. Consequently, the Address interface includes a get and set method signature for each of the four elements. For example, the interface includes getName() for retrieving data in the <name> element and setName() for modifying data in this element.

You can compile the Java source files with javac as follows:

cd $ORACLE_HOME/xdk/demo/java/jaxb/Sample3/generated
javac *.java

Processing the XML Data

Sample3.java shows how you can process the sample3.xml document by using the Java class files that you generated in "Generating and Compiling the Java Classes". The sample program unmarshals the XML data document, marshals it, and uses the generated classes to print and modify the address data.

The Sample3.java program processes the data as follows:

1. Create strings for the XML data document file name and the name of the directory that contains the generated classes. This name is the package name. For example:

   String fileName = "sample3.xml";
   String instancePath = "generated";
   

2. Instantiate a JAXB context by invoking JAXBContext.newInstance(). A client application obtains a new instance of this class by initializing it with a context path. The path contains a list of Java package names that contain the interfaces available to the marshaller. The following statement illustrates this technique:

   JAXBContext jc = JAXBContext.newInstance(instancePath);
   

3. Instantiate the unmarshaller. The Unmarshaller class governs the process of deserializing XML data into newly created objects, optionally validating the XML data as it is unmarshalled. The following statement illustrates this technique:

   Unmarshaller u = jc.createUnmarshaller();
   

4. Unmarshal the XML document. Invoke the Unmarshaller.unmarshal() method to deserialize the sample3.xml document and return the content trees as an Object. You can create a URL from the XML filename by invoking the fileToUrl() helper method. The following statement illustrates this technique:

   Object obj = u.unmarshal(fileToURL(fileName));
   

5. Instantiate a marshaller. The Marshaller class governs the process of serializing Java content trees back into XML data. The following statement illustrates this technique:

   Marshaller m = jc.createMarshaller();
   

6. Marshal the content tree. Invoke the Marshaller.marshal() method to marshal the content tree Object returned by the unmarshaller. You can serialize the data to a DOM tree, SAX content handler, transformation result, or output stream. The following statement serializes the XML data, including markup, as an output stream:

   m.marshal(obj, System.out);
   

   By default, the marshaller uses UTF-8 encoding when writing XML data to an output stream.

7. Print the contents of the XML document. The program implements a process() method that accepts the content tree and marshaller as parameters.

   The first stage of processing prints the data in the XML document without the XML markup. The method casts the Object generated by the marshaller into type MyAddress. It proceeds to invoke a series of methods whose method names are constructed by prefixing get to the name of an XML element. For example, to obtain the data in the <city> element in Example 8-1, the program invokes getCity(). The following code fragment illustrates this technique:

   public static void process(Object obj, Marshaller m) throws Throwable
   {
      generated.MyAddress elem = (generated.MyAddress)obj;
      System.out.println();
      System.out.println(" My address is: ");
      System.out.println("  name:  "  + elem.getName() + "\n"  +
                         "  doorNumber " + elem.getDoorNumber() + "\n" +
                         "  street: " + elem.getStreet() + "\n" +
                         "  city:   " + elem.getCity() + "\n"  +
                         "  state:  " + elem.getState() + "\n" +
                         "  zip:  " + elem.getZip() + "\n" +
                         "  country:  " + elem.getCountry() + "\n" +
                         "\n" );
   ...
   

8. Change the XML data and print it. The process() method continues by invoking set methods that are analogous to the preceding get methods. The name of each set method is constructed by prefixing set to the name of an XML element. For example, setCountry() changes the value in the <country> element. The following statements illustrate this technique:

   short num = 550;
   elem.setDoorNumber(num);
   elem.setCountry("India");
   num = 10100;
   elem.setZip(new java.math.BigInteger("100100"));
   elem.setCity("Noida");
   elem.setState("Delhi");
   

   After changing the data, the program prints the data by invoking the same get methods as in the previous step.

Defining the Schema

Example 8-4 shows the XML data document that provides the input to the sample application. The sample10.xml document describes a business.

<?xml version="1.0"?>
<business xmlns="http://jaxbcustomized/sample10/">
   <title>Software Development</title>
   <owner>Larry Peterson</owner>
   <id>45123</id>
</business>

Example 8-5 shows the XML schema that defines the structure of sample10.xml. The schema defines one complex type and one element as follows:

• The complex type, which is named businessType, is a sequence of elements. Each element in the sequence describes a part of the business: title, owner, and id.

• The element, which is named business, is of type biz:businessType. The biz prefix specifies the http://jaxbcustomized/sample10/ namespace. In sample10.xml, the business top-level element, which is in namespace http://jaxbcustomized/sample10/, conforms to the schema definition.

<?xml version="1.0"?>
 
<!-- Customization of class name in top level element -->

<schema xmlns="http://www.w3.org/2001/XMLSchema"
        targetNamespace="http://jaxbcustomized/sample10/"
        xmlns:biz="http://jaxbcustomized/sample10/"
        xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
        jaxb:version="1.0"
        elementFormDefault="qualified">
 
   <element name="business" type="biz:businessType">
      <annotation>
         <appinfo>
            <jaxb:class name="myBusiness"/>
         </appinfo>
      </annotation>
   </element>
 
   <complexType name="businessType">
      <sequence>
         <element name="title" type="string"/>
         <element name="owner" type="string"/>
         <element name="id" type="integer"/>
      </sequence>
   </complexType>
 
</schema>

<xs:annotation>
   <xs:appinfo>
      .
      .
      binding declarations
      .
      .
   </xs:appinfo>
</xs:annotation>

<class [ name = "className"] >

<jaxb:class name="myBusiness"/>

Generating and Compiling the Java Classes

After you have an XML document and corresponding XML schema, the next stage is to generate the Java classes from the XML schema. You can use the JAXB command-line interface to perform this task.

If your environment is set up as described in "Setting Up the Java XDK Environment", then you can create the source files in the generated package as follows:

cd $ORACLE_HOME/xdk/demo/java/jaxb/Sample10
orajaxb -schema sample10.xsd

Because the preceding command does not specify a target package, the package name is constructed from the target namespace of the schema, which is http://jaxbcustomized/sample10/ . Consequently, the utility generates the following source files in the ./jaxbcustomized/sample10/ subdirectory:

BusinessType.java
BusinessTypeImpl.java
MyBusiness.java
MyBusinessImpl.java
ObjectFactory.java

Note that the complex type businessType has two source files, BusinessType.java and BusinessTypeImpl.java. Because of the JAXB customization, the business element is bound to interface MyBusiness and implementing class MyBusinessImpl.

The content of the BusinessType.java source file is shown in Example 8-6.

package jaxbcustomized.sample10;

public interface BusinessType
{
   public void setTitle(java.lang.String t);
   public java.lang.String getTitle();
   public void setOwner(java.lang.String o);
   public java.lang.String getOwner();
   public void setId(java.math.BigInteger i);
   public java.math.BigInteger getId();
} 

The BusinessType complex type defined a sequence of elements: title, owner, and id. Consequently, the Address interface includes a get and set method signature for each of the elements. For example, the interface includes getTitle() for retrieving data in the <title> element and setTitle() for modifying data in this element.

You can compile the Java source files with javac as follows:

cd $ORACLE_HOME/xdk/demo/java/jaxb/Sample10/jaxbcustomized/sample10
javac *.java

Processing the XML Data

The Sample10.java source file shows how you can process the data in the sample10.xml document by using the class files that you generated in "Generating and Compiling the Java Classes". The sample program unmarshals the XML document, prints its content, and marshals the XML to standard output.

The Sample10.java program processes the XML data as follows:

1. Create strings for the XML data document file name and the name of the directory that contains the generated classes. This name is the package name. For example:

   String fileName = "sample10.xml";
   String instancePath = "jaxbcustomized.sample10";
   

2. Instantiate a JAXB context by invoking the JAXBContext.newInstance() method. The following statement illustrates this technique:

   JAXBContext jc = JAXBContext.newInstance(instancePath);
   

3. Create the unmarshaller. The following statement illustrates this technique:

   Unmarshaller u = jc.createUnmarshaller();
   

4. Unmarshal the XML document. The program unmarshals the document twice: it first returns an Object and then uses a cast to return a MyBusiness object. The following statement illustrates this technique:

   Object obj = u.unmarshal(fileToURL(fileName));
   jaxbcustomized.sample10.MyBusiness bus =
            (jaxbcustomized.sample10.MyBusiness) u.unmarshal(fileToURL(fileName));
   

5. Print the contents of the XML document. The program invokes the get methods on the MyBusiness object. The following code fragment illustrates this technique:

   System.out.println("My business details are: ");
   System.out.println("    title: " + bus.getTitle());
   System.out.println("    owner: " + bus.getOwner());
   System.out.println("    id:    " + bus.getId().toString());
   System.out.println();
   

6. Create a marshaller. The following statement illustrates this technique:

   Marshaller m = jc.createMarshaller();
   

7. Configure the marshaller. You can invoke setProperty() to configure various properties the marshaller. The JAXB_FORMATTED_OUTPUT constant specifies that the marshaller should format the resulting XML data with line breaks and indentation. The following statements illustrate this technique:

   m.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, new Boolean(true));
   

8. Marshal the content tree. The following statement serializes the XML data, including markup, as an output stream:

   m.marshal(bus, System.out);
   

   By default, the marshaller uses UTF-8 encoding when writing XML data to an output stream.