Using JAXB xjc tooling to generate JAXB classes from an XML schema file

Use Java Architecture for XML Binding (JAXB) xjc tooling to compile an XML schema file into fully annotated Java classes.

Before you begin

Develop or obtain an XML schema file.

About this task

Use JAXB APIs and tools to establish mappings between an XML schema and Java classes. XML schemas describe the data elements and relationships in an XML document. After a data mapping or binding exists, you can convert XML documents to and from Java objects. You can now access data stored in an XML document without the need to understand the data structure.

To develop web services using a top-down development approach starting with an existing Web Services Description Language (WSDL) file, use the wsimport tool to generate the artifacts for your Java API for XML-Based Web Services (JAX-WS) applications when starting with a WSDL file. After the Java artifacts for your application are generated, you can generate fully annotated Java classes from an XML schema file by using the JAXB schema compiler, xjc command-line tool. The resulting annotated Java classes contain all the necessary information that the JAXB runtime requires to parse the XML for marshaling and unmarshaling. You can use the resulting JAXB classes within Java API for XML Web Services (JAX-WS) applications or other Java applications for processing XML data.

Best practice Best practice: WebSphere® Application Server provides Java API for XML-Based Web Services (JAX-WS) and Java Architecture for XML Binding (JAXB) tooling. The wsimport, wsgen, schemagen and xjc command-line tools are located in the app_server_root\bin\ directory. Similar tooling is provided by the Java SE Development Kit (JDK) 6. On some occasions, the artifacts generated by both the tooling provided by WebSphere Application Server and the JDK support the same levels of the specifications. In general, the artifacts generated by the JDK tools are portable across other compliant runtime environments. However, it is a best practice to use the tools provided with this product to achieve seamless integration within the WebSphere Application Server environment and to take advantage of the features that may be only supported in WebSphere Application Server. To take advantage of JAX-WS and JAXB V2.2 tooling, use the tools provided with the application server that are located in the app_server_root\bin\ directory.bprac
Supported configurations Supported configurations: This product supports the JAXB 2.2 specification. JAX-WS 2.2 requires JAXB 2.2 for data binding. sptcfg

In addition to using the xjc tool from the command-line, you can invoke this JAXB tool from within the Ant build environments. Use the com.sun.tools.xjc.XJCTask Ant task from within the Ant build environment to invoke the xjc schema compiler tool. To function properly, this Ant task requires that you invoke Ant using the ws_ant script.

Avoid trouble Avoid trouble: If you are using the xjc Ant task, you must use the destdir parameter to specify the destination directory instead of the target option. Specifying the target option when using the xjc Ant task causes an error. gotcha

Procedure

  1. Use the JAXB schema compiler, xjc command to generate JAXB-annotated Java classes. The schema compiler is located in the app_server_root\bin\ directory. The schema compiler produces a set of packages containing Java source files and JAXB property files depending on the binding options used for compilation.
  2. (Optional) Use custom binding declarations to change the default JAXB mappings. Define binding declarations either in the XML schema file or in a separate bindings file. You can pass custom binding files by using the -b option with the xjc command.
  3. Compile the generated JAXB objects. To compile generated artifacts, add the Thin Client for JAX-WS with WebSphere Application Server to the classpath.

Results

Now that you have generated JAXB objects, you can write Java applications using the generated JAXB objects and manipulate the XML content through the generated JAXB classes.

Example

The following example illustrates how JAXB tooling can generate Java classes when starting with an existing XML schema file.
  1. Copy the following bookSchema.xsd schema file to a temporary directory.
      <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
         <xsd:element name="CatalogData">
           <xsd:complexType>
             <xsd:sequence>
               <xsd:element name="books" type="bookdata" minOccurs="0"
    						maxOccurs="unbounded"/>
             </xsd:sequence>
           </xsd:complexType>
         </xsd:element>
         <xsd:complexType name="bookdata">
           <xsd:sequence>
             <xsd:element name="author" type="xsd:string"/>
             <xsd:element name="title" type="xsd:string"/>
             <xsd:element name="genre" type="xsd:string"/>
             <xsd:element name="price" type="xsd:float"/>
             <xsd:element name="publish_date" type="xsd:dateTime"/>
             <xsd:element name="description" type="xsd:string"/>
           </xsd:sequence>
           <xsd:attribute name="id" type="xsd:string"/>
         </xsd:complexType>
       </xsd:schema>
    
  2. Open a command prompt.
  3. Run the JAXB schema compiler, xjc command from the directory where the schema file is located. The xjc schema compiler tool is located in the app_server_root\bin\ directory.
    app_server_root\bin\xjc.bat bookSchema.xsd
    app_server_root/bin/xjc.sh bookSchema.xsd
    Running the xjc command generates the following JAXB Java files:
    generated\Bookdata.java
    generated\CatalogdData.java
    generated\ObjectFactory.java
    
  4. Use the generated JAXB objects within a Java application to manipulate XML content through the generated JAXB classes.

Refer to the JAXB Reference implementation documentation for additional information about the xjc command.

Avoid trouble Avoid trouble: An existing JAXB application might fail to compile when the JAXB classes are regenerated from the schema using the JAXB 2.2 tools in Version 8. Incorrect package names are generated for XML namespaces containing the # character. The JAXB tools are required to replace the # character with an underscore _ character, but are instead removing the character completely.
For example with the following schema:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://example.com/abc#"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:complexType name="exampleType">
    <xs:sequence>
      <xs:element name="aString" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>
The JAXB 2.1 tools from Version 7 produce:
D:\schemas\example>xjc example.xsd
parsing a schema...
compiling a schema...
com\example\abc_\ExampleType.java
The JAXB 2.2 tools from Version 8 produce:
D:\schemas\example>xjc example.xsd
parsing a schema...
compiling a schema...
com\example\abc\ExampleType.java
This behavior causes a compilation failure for existing code which references the package names generated by Version 7.
To work around this migration issue, you can provide a binding file to the tools along with their XML schema which explicitly declares the package for each namespace. Through this customization, you can avoid the defect in the default binding. For example, with this binding file, the JAXB 2.2 tools produce classes in the com.example.abc_ package.
<?xml version="1.0" encoding="UTF-8"?>
<jaxb:bindings version="1.0"
               xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
               xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <jaxb:bindings schemaLocation="example.xsd">
    <jaxb:schemaBindings>
      <jaxb:package name="com.example.abc_" />
    </jaxb:schemaBindings>
  </jaxb:bindings>
</jaxb:bindings>
gotcha



In this information ...


Related concepts

IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Feb 6, 2014 8:11:25 PM CST
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=matt&product=was-nd-mp&topic=twbs_jaxbschema2java
File name: twbs_jaxbschema2java.html