Summa

The Problem

As a software developer or architect, you have many options available for working with XML files within your application. Say, for example, you only need to use a small subset of fields from an XML document, then using a SAX (Simple API for XML) is a good solution. If you need to generate XML documents, a DOM (Document Object Model) API will be a natural choice. An XML schema allows you to define very complex structures and include different XML Schema namespaces (fully qualified XML type names). Writing code to read and manipulate these can be very cumbersome and become difficult to maintain with traditional XML parsers.

The Solution

Wouldn’t it be great if you could easily map your application classes to XML schemas and vice versa? Well, XML binding frameworks are meant to provide that capability. Specifically in the Java world, the “Java Architecture for XML Binding” (JAXB) is a specification (JSR 222) that allows mapping XML types to Java types. The JAXB Reference Implementation is a very powerful and comprehensive framework that allows binding Java objects to XML Schemas (XSDs) back and forth. It also provides tools to generate, at design time, a Java class that maps to an XML schema.

How does JAXB work?

To illustrate how JAXB is used for Java to XML binding I created a very simple XML Schema that contains a CodeMetric type:

<xs:element name="CodeMetric">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="moduleName" type="xs:string" />
      <xs:element name="estimateDays" type="xs:int" />
      <xs:element minOccurs="0" name="actualDays" type="xs:int" />
      <xs:element name="numberOfDevelopers" nillable="true"
                  type="xs:int" />
      <xs:element minOccurs="0" name="repeatable" nillable="true"
                  type="xs:boolean" />
      <xs:element name="complexity" type="ns1:ComplexityEnum" />
      <xs:element name="size">
      <xs:simpleType>
        <xs:restriction base="xs:string">
        <xs:enumeration value="small" />
        <xs:enumeration value="medium" />
        <xs:enumeration value="large" />
        </xs:restriction>
      </xs:simpleType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:element>
<xs:simpleType name="ComplexityEnum">
  <xs:restriction base="xs:string">
  <xs:enumeration value="easy" />
  <xs:enumeration value="intermediate" />
  <xs:enumeration value="hard" />
  </xs:restriction>
</xs:simpleType>

The first step is to generate corresponding Java classes for the schema above. The JAXB distribution includes a binding compiler: the xjc.bat tool. To generate the classes simply provide the xsd file name or the path to the folder containing xsd files as follows:

xjc.bat schema\*.xsd

The following annotated Java class will be generated:

public class CodeMetric {
  @XmlElement(required = true)
  protected String moduleName;

  protected int estimateDays;

  protected Integer actualDays;

  @XmlElement(required = true, type = Integer.class, nillable = true)
  protected Integer numberOfDevelopers;

  @XmlElementRef(name = "repeatable", type = JAXBElement.class)
  protected JAXBElement<Boolean> repeatable;

  @XmlElement(required = true)
  protected ComplexityEnum complexity;

  @XmlElement(required = true)
  protected String size;
}

In the schema above, note that the “complexity enumeration” is defined differently than the “size enumeration”. The “size enumeration” is defined inline, where as the “complexity enumeration” is defined as a named complex type. This was done intentionally to illustrate that JAXB will generate a Java enumeration class only for the enumerations that are named. This is the generated Java enumeration class for the ComplexityEnum XML type:

@XmlEnum
public enumComplexityEnum {
  @XmlEnumValue("easy")
  EASY("easy"), 

  @XmlEnumValue("intermediate")
  INTERMEDIATE("intermediate"),

  @XmlEnumValue("hard")
  HARD("hard");

  private final String value;

Next you will need to create code to unmarshall (turn an XML document into a Java object) and marshall (turn Java code into an XML document).  The key class to use is the JAXBContext. This class requires specifying the Java package names of the classes to be marshalled or unmarshalled. If there are multiple packages used, they can be separated using the ‘:’ character.

public CodeMetricsHandler() throws JAXBException {
  JAXBContext jc = JAXBContext.newInstance("com.summa.metrics");
  this.marshaller = jc.createMarshaller();
  this.unmarshaller = jc.createUnmarshaller();
}

For convenience you can create a method to unmarshall XML into a Java instance. In most cases the most convenient type to use is a string, but it can also be a file name for instance, or an input stream. The return type is the corresponding Java type. The method below will unmarshall a string which contains a valid CodeMetric XML document into a CodeMetric Java instance.

public CodeMetric unmarshallCodeMetric(String xmlString)
  throws JAXBException {
  CodeMetric cm = null;
  cm = (CodeMetric)this.unmarshaller.unmarshal(
  new StreamSource(new StringReader(xmlString)));
  return cm;
}

Similarly, you can create a method that will marshall a java object into an XML document.

public String marshallCodeMetric(CodeMetric update) throwsJAXBException {
  String xml = null;
  StringWriter writer = new StringWriter();
  this.marshaller.marshal(update, writer);
  xml = writer.toString();
  return xml;
}

What if the default binding does not work for me?

JAXB is a very powerful XML binding framework. The steps outlined above only touch on the basics of marshalling and unmarshalling. On a greenfield project, using the default bindings without any customizations may work, but in many cases existing XML schemas cannot be tweaked or existing Java types need to be reused.  You may also want to use a different java package than the one mapped from the schema. JAXB allows very granular customizations of the binding. This can be accomplished either through the use of XML annotations in the schema or specified through separate (.xjb) files.

Conclusion

JAXB and similar XML binding frameworks can significantly reduce development and testing time by abstracting a lot of the cumbersome details when dealing with XML schemas. It reduces the room for error and maintenance time. If the schema changes, the JAXB classes need to be regenerated. An IDE will quickly point out which types changed at compilation time. JAXB is not a “one size fits all” solution. If your project uses XML schemas and your application classes closely resemble the types defined in the schemas, JAXB is likely a good solution for your needs.