Generate client object classes based on XML Schema ( .xsd files) (JAXB, Maven, Web Service)

To consume some xml based web services, sometimes we need to be able to generate java objects based on the schema that the service provider provides.

The JAXB is one tool that could help us do this and also JAXB is fully integrated with Maven.

Official Manual:
http://mojo.codehaus.org/jaxb2-maven-plugin/xjc-mojo.html

====================================================== ======================================================
Example:

pom.xml:

<dependencies>

 <dependency>
   <groupId>junit</groupId>
   <artifactId>junit</artifactId>
   <version>4.10</version>
   <scope>test</scope>
 </dependency>
 <dependency>
   <groupId>javax.xml.bind</groupId>
   <artifactId>jaxb-api</artifactId>
   <version>2.1</version>
 </dependency>
 <dependency>
   <groupId>com.sun.xml.bind</groupId>
   <artifactId>jaxb-impl</artifactId>
   <version>2.1</version>
 </dependency>
</dependencies>

<build>
 <pluginManagement>
   <plugins>
     <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-compiler-plugin</artifactId>
       <version>2.3.1</version>
       <configuration>
         <source>1.6</source>
         <target>1.6</target>
       </configuration>
     </plugin>
   </plugins>
 </pluginManagement>
 <plugins>
   <plugin>
     <groupId>org.codehaus.mojo</groupId>
     <artifactId>jaxb2-maven-plugin</artifactId>
     <version>1.5</version>
     <configuration>
       <outputDirectory>${project.basedir}/src/main/java</outputDirectory>
       <schemaDirectory>${project.basedir}/src/main/schemas/</schemaDirectory>
       <bindingDirectory>${project.basedir}/src/main/schemas/bindings/</bindingDirectory>
       <extension>true</extension>
       <forceRegenerate>true</forceRegenerate>
     </configuration>
     <executions>
       <execution>
         <id>xjc-xxx</id>
         <goals>
           <goal>xjc</goal>
         </goals>
         <configuration>
           <schemaFiles>XXXXXXX.xsd</schemaFiles>
         </configuration>
       </execution>
     </executions>
   </plugin>
 </plugins>
</build>

We can have multiple executions, and each execution parse one xsd file. Binding file example: binding.xjb

<jaxb:bindings version="1.0" 

   xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
   xmlns:xs="http://www.w3.org/2001/XMLSchema" 

   xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc">

   <jaxb:globalBindings>
       <xjc:simple />
   </jaxb:globalBindings>

   <jaxb:bindings schemaLocation="..\cda\C32_POCD_MT000040.xsd">
       <jaxb:bindings
           node="//xs:complexType[@name='POCD_MT000040.ObservationMedia']/xs:attribute[@name='ID']">
           <jaxb:property name="ID1"></jaxb:property>
       </jaxb:bindings>
       <jaxb:bindings
           node="//xs:complexType[@name='POCD_MT000040.RegionOfInterest']/xs:attribute[@name='ID']">
           <jaxb:property name="ID1"></jaxb:property>
       </jaxb:bindings>
       <jaxb:bindings
           node="//xs:complexType[@name='POCD_MT000040.Section']/xs:attribute[@name='ID']">
           <jaxb:property name="ID1"></jaxb:property>
       </jaxb:bindings>
   </jaxb:bindings>
</jaxb:bindings>

====================================================== ====================================================== The block:

   <jaxb:globalBindings>
       <xjc:simple />
   </jaxb:globalBindings>

The block is very useful. It could make the generated java code much clean, concise and easy to use.
For example (Get from Reference# 1):

1. Some content model definitoins, such as A,B,A, which used to cause an XJC compilation error and required manual intervention, now compile out of the box without any customization.
2. Some content model definitions that used to bind to a non-intuitive Java class now binds to a much better Java class:

   // schema
   <xs:complexType name="foo">
    <xs:choice>
     <xs:sequence>
      <xs:element name="a" type="xs:int" />
      <xs:element name="b" type="xs:int" />
     </xs:sequence>
     <xs:sequence>
      <xs:element name="b" type="xs:int" />
      <xs:element name="c" type="xs:int" />
     </xs:sequence>
    </xs:choice>
   </xs:complexType>
   
   // before
   class Foo {
       List<JAXBElement<Integer>> content;
   }
   
   // in <xjc:simple> binding
   class Foo {
       Integer a;
       int b; // notice that b is effectively mandatory, hence primitive
       Integer c;
   }
   

3. When repetable elements are bound, the method name will become plural.

   // schema
   <xs:complexType name="person">
    <xs:sequence>
     <xs:element name="child"  type="xs:string" maxOccurs="unbounded" />
     <xs:element name="parent" type="xs:string" maxOccurs="unbounded" />
    </xs:sequence>
   </xs:complexType>
   
   // before
   public class Person {
       protected List<String> child;
       protected List<String> parent;
   }
   
   // in <xjc:simple> binding
   public class Person {
       protected List<String> children;
       protected List<String> parents;
   }
   

(Once again, readers are warned that this is an experimental binding mode, and therefore the binding is subject to change in future versions of the JAXB RI without notice. Please send feedbacks on this binding to users@jaxb.dev.java.net) 4. It'll format the generated java class name, get rid of the suffix 'Type'. Sometimes, the provided xsd file may have definition like this:

<xs:element name="item" type="itemType"/>  
...   
<xs:complexType name="itemType">
    <xs:attribute name="id" type="xs:string" use="required">
    ...     
</xs:complexType>

Which is not a good practice. It will generate java object ItemType.java. But actually Item.java is what we want. Which should be defined like this :

<xs:element name="item">
    <xs:complexType>
    <xs:attribute name="id" type="xs:string" use="required">
        ...
    </xs:complexType>
</xs:element>

If it's this case, we may not want to update the schema file one by one. In stead, we can use the simple mode, then we can simply get what we want. NOTE: we must run the cmd with -extension. In the configuration of pom, we have to set <extension>true</extension>.
====================================================== ====================================================== This block:

   <jaxb:bindings schemaLocation="..\cda\C32_POCD_MT000040.xsd">
       <jaxb:bindings
           node="//xs:complexType[@name='POCD_MT000040.ObservationMedia']/xs:attribute[@name='ID']">
           <jaxb:property name="ID1"></jaxb:property>
       </jaxb:bindings>
       <jaxb:bindings
           node="//xs:complexType[@name='POCD_MT000040.RegionOfInterest']/xs:attribute[@name='ID']">
           <jaxb:property name="ID1"></jaxb:property>
       </jaxb:bindings>
       <jaxb:bindings
           node="//xs:complexType[@name='POCD_MT000040.Section']/xs:attribute[@name='ID']">
           <jaxb:property name="ID1"></jaxb:property>
       </jaxb:bindings>
   </jaxb:bindings>

It redefines the name of the target attribute.
In this case, in xs:complexType name='POCD_MT000040.ObservationMedia. There are one attribute with name 'id' and another attribute with name 'ID'. If we do not redefine the second attribute, when generating java class, it will throw exception:  "trying to create the same field twice: id"
At last, run maven to generate sources. This plug is run in phase 'generate-sources'. So we can run "mvn clean generate-sources"
Good tutorials and references about customization binding: 1. https://jaxb.java.net/nonav/2.1/docs/vendorCustomizations.html#simple 2. http://www.onjava.com/pub/a/onjava/2003/12/10/jaxb.html?page=2