XML Document

Listing 12-1 shows an XML document representing a customer’s purchase order for the CD-BookStore application (see Chapter 1). Note that this document is easily readable as well as being structured and therefore can be understood by an external system. In this case it describes information about the purchase order, the customer who made the order, the items bought by the customer as well as the credit card information used to pay the order.

Listing 12-1.  An XML Document Representing a Purchase Order

<?xml version="1.0" encoding="UTF-8" ?>
<order id="1234" date="05/06/2013">
  <customer first_name="James" last_name="Rorrison">
    <email>[email protected]</email>
    <phoneNumber>+44 1234 1234</phoneNumber>
</customer>
<content>
    <order_line item="H2G2" quantity="1">
      <unit_price>23.5</unit_price>
    </order_line>
    <order_line item="Harry Potter" quantity="2">
      <unit_price>34.99</unit_price>
    </order_line>
  </content>
  <credit_card number="1357" expiry_date="10/13" control_number="234" type="Visa"/>
</order>

The document begins with an optional XML declaration (specifying which version of XML and character encoding is being used by the document) and then is composed of both markups and content. Markups, also referred to as tags, describe the structure of the document, allowing you to easily send and receive data, or transform data from one format to another.

As you can see in Table 12-1, the XML terminology is quite simple. Despite this simplicity and readability, XML can be used to describe any kind of document, data structure, or deployment descriptor when it comes to Java EE.

Validating with XML Schema

The XML terminology is so broad that it allows you to write anything you want with XML and declare your own language. In fact, you can write so many things that your XML structure can become meaningless if you don’t define a grammar. This grammar can be set using an XML Schema Definition (XSD). By having a grammar attached to your XML document, you can have any validating XML parser enforce the rules of a particular XML dialect. This removes a tremendous burden from your application’s code as the parser will automatically validate your XML document.

An XML Schema Definition (XSD) is an XML-based grammar declaration used to describe the structure and content of an XML document. For instance, the schema in Listing 12-2 can be used to specify the XML document described in Listing 12-1, giving it an extra meaning: “This is not just a text file, it’s a structured document representing an order with items and customer details.” During document interchange, the XSD describes the contract between the producer and consumer because it describes what constitutes a valid XML message between the two parties.

Listing 12-2.  XSD Describing the Purchase Order XML Document

<?xml version="1.0" encoding="UTF-8" ?>
<xs: schema version="1.0" xmlns: xs =" http://www.w3.org/2001/XMLSchema ">
 
  <xs:element name="order" type="order"/>
 
  <xs:complexType name="creditCard">
    <xs:sequence/>
    <xs:attribute name="number" type="xs:string"/>
    <xs:attribute name="expiry_date" type="xs:string"/>
    <xs:attribute name="control_number" type="xs:int"/>
    <xs:attribute name="type" type="xs:string"/>
  </xs:complexType>
 
  <xs:complexType name="customer">
    <xs:sequence>
      <xs:element name="email" type="xs:string" minOccurs="0"/>
      <xs:element name="phoneNumber" type="xs:string" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="first_name" type="xs:string"/>
    <xs:attribute name="last_name" type="xs:string"/>
  </xs:complexType>
 
  <xs: complexType name="order">
    <xs:sequence>
      <xs:element name="customer" type=" customer " minOccurs="0"/>
      <xs:element name="content" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="order_line" type="orderLine" minOccurs ="0" →
                        maxOccurs ="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="credit_card" type="creditCard" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="id" type=" xs:long "/>
    <xs:attribute name="date" type="xs:dateTime"/>
  </xs:complexType>
 
  <xs:complexType name="orderLine">
    <xs:sequence>
      <xs:element name="unit_price" type="xs:double" minOccurs="0"/>
    </xs:sequence>
    <xs: attribute name="item" type="xs:string"/>
    <xs: attribute name="quantity" type="xs:int"/>
  </xs:complexType>
</xs:schema>

As you can see in Listing 12-2, the XSD allows a very precise definition of both simple (<xs:attribute name="expiry_date" type="xs:string"/>) and complex data types (<xs:complexType name="creditCard">), and even allows types to inherit properties from other types. The purchase order schema consists of a variety of subelements, most notably elements, complex types, and attributes that determine the appearance of the content. Thanks to XSD, elements and attributes become strongly typed and have datatype information associated with them. Such strongly typed XML can now be mapped to objects using technologies such as JAXB, which you’ll see later in this chapter.

Table 12-2 only lists a subset of the XSD elements and attributes. XSD is a much richer language, but it’s not the goal of this book to be an exhaustive XSD resource. If you want to know more about XSD, its structure, and its datatypes, you should check the related W3C website.

Once you have an XML document and its associated XML Schema Definition you can use a parser to do the validation for you. Parsers come in two major flavors: DOM and SAX.

Parsing with SAX and DOM

Before a document can be used, it must be parsed and validated by an XML parser. The parser, a.k.a. processor, analyzes the markup and makes the data contained in the XML available to the application that needs to use it. Most XML parsers can be used in two distinct modes. One mode is the Document Object Model (DOM) that reads in an entire XML data source and constructs a treelike representation of it in memory. The other mode is an event-based model called the Simple API for XML (SAX) that reads in the XML data source and makes callbacks to the application whenever it encounters a distinct section (the end of an element).

Querying with XPath

XPath is a query language designed to query XML structures that is used by a variety of other XML standards, including XSLT, XPointer, and XQuery. It defines the syntax for creating expressions, which are evaluated against an XML document.

XPath expressions can represent a node, a boolean, a number, or a string. The most common type of XPath expression is a location path, which represents a node. For example, the XPath expression / is an expression that represents all nodes in the XML document from the root. Below is an XPath expression representing all the unit_price nodes whose value is greater than 20 (see the purchase order XML in Listing 12-1):

//content/order_line[unit_price>=20]/unit_price

Also, XPath has a set of built-in functions that enable you to develop very complex expressions. The following expression returns the children text node of unit_price elements:

//content/order_line[unit_price>=20]/unit_price/text()

XQuery is another query language that is designed to query collections of XML data using XPath expressions. XQuery is syntactically similar to SQL, with a set of keywords including FOR, LET, WHERE, ORDER BY or RETURN. The following is a simple XQuery expression that is using the doc() function (that reads the order.xml document) to return all order_line children nodes which have a quantity greater than 1 and unit_price less than 50;

for $orderLine in doc("order.xml")//content/order_line[@quantity>1]
where $orderLine/unit_price < 50
return $orderLine/unit_price/text()

There are more complex queries you can do with XQuery like joining XML documents, making complex conditions or ordering the result on an element.

In some cases, extracting information from an XML document using an API may be too cumbersome mostly because the criteria for finding the data are complex and a bunch of code is needed to iterate through the nodes. XML query languages such as XPath 1.0 and XQuery provide rich mechanisms for extracting information from XML documents.

Transforming with XSLT

A key advantage of XML over other data formats is the ability to transform an XML document from one vocabulary to another, in a generic manner. For example you can render an XML document into a print-friendly format or into a web page. The technology that enables this translation is the eXtensible Stylesheet Language Transformations (XSLT).

Simply stated, XSLT provides a framework for transforming the structure of an XML document by combining it with an XSL stylesheet to produce an output document. All you have to do is to create an XSL stylesheet that contains a set of transformation instructions for transforming a source tree into a result tree. Then an XSLT processor will transform the source document by associating patterns within the source XML tree with XSL stylesheet templates that are to be applied to them.

A pattern is an XPath expression that is matched against elements in the source tree. On a successful match, a template is instantiated to create part of the result tree. In constructing the result tree, elements from the source can be filtered and reordered, and arbitrary structure can be added.

The XSLT stylesheet in Listing 12-3 converts the order.xml document shown in Listing 12-1 into an XHTML Web page showing a table of sold items whose price is greater than 30.

Listing 12-3.  XSLT Stylesheet for Purchase Order XML Document

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="2.0" xmlns:xsl=" http://www.w3.org/1999/XSL/Transform ">
  <xsl:template match="/">
    <html>
      <body>
        <h2>Sold Items</h2>
        <table border="1">
          <tr>
            <th>Title</th>
            <th>Quantity</th>
            <th>Unit Price</th>
          </tr>
 
          <xsl:for-each select=" order/content/order_line ">
            <tr>
              <td>
                <xsl:value-of select="@item"/>
              </td>
              <td>
                <xsl:value-of select="@quantity"/>
              </td>
 
              <xsl:choose>
                <xsl:when test=" unit_price > 30 ">
                  <td bgcolor="#FF0000">
                    <xsl:value-of select="unit_price"/>
                  </td>
                </xsl:when>
                <xsl:otherwise>
                  <td>
                    <xsl:value-of select="unit_price"/>
                  </td>
                </xsl:otherwise>
              </xsl:choose>
            </tr>
          </xsl:for-each>
 
        </table>
      </body>
    </html>
  </xsl:template>
</xsl:stylesheet>

The generic XSLT APIs in the javax.xml.transform package are used for compiling stylesheet instructions, and performing a transformation from XML source to a XML result. XSLT can also be used with the SAX APIs to convert data to XML.

A Brief History of XML Specifications

The W3C is a consortium that is known for developing and maintaining web technologies like HTML, XHTML, RDF, or CSS. But, W3C is also the central organ for XML and all the related XML technologies like XML Schema, XSLT, XPATH, and DOM.

Development of XML (Extensible Markup Language) started in 1996 by the XML Working Group of the W3C and led to a W3C recommendation in February 1998. However, the technology was not entirely new. It was based on SGML (Standard Generalized Markup Language), which had been developed in the early 1980s and became an ISO standard in 1986.

XSD (XML Schema) offers the facilities to describe the structure of XML documents in an .xsd file. This structure constrains the contents of XML documents and therefore, can be used to validate XML documents. XSD is one of several XML schema languages and it was the first separate schema language for XML, published as a W3C recommendation in 2001.

XSLT (EXtensible Stylesheet) is one of the first XML specifications, influenced by functional languages and by text-based pattern matching languages, to transform XML documents. Its most direct predecessor is DSSSL (Document Style Semantics and Specification Language), which did for SGML what XSLT does for XML. XSLT 1.0 became part of W3C in 1999 and the project led to the creation of XPath. Xalan, Saxon, and AltovaXML are some of several XSLT processors available for XML transformation.

XPath 1.0 is a query language for addressing nodes in an XML document. It was introduced and accepted as a W3C Recommendation in 1999. It was originally motivated by a desire to provide a common syntax between XPointer and XSLT. It can be directly used inside Java or it can be embedded in languages such as XSLT, XQuery or XML Schema.

The mission of the XML Query project is to provide flexible query facilities to extract data from documents. The development of XQuery 1.0 by the XML Query Working Group was closely coordinated with the development of XSLT 2.0 by the XSL Working Group; the two groups shared responsibility for XPath 2.0, which is a subset of XQuery 1.0. XQuery 1.0 became a W3C Recommendation on January 23, 2007.

The Document Object Model (DOM) is a tree-based interface for representing and interacting with contents, structures and styles in HTML, XHTML, and XML documents. At the beginning, DOM was an effort to develop a standard for scripting languages used in browsers. The current release of the DOM specification, DOM Level 3, supports XPath as well as an interface for serializing documents into XML.

The Simple API for XML (SAX ) is the first widely adopted API for XML in Java. It is a streaming, event-based interface to parse XML data. SAX was originally implemented in Java, but is now supported by nearly all major programming languages.

From the start, the development of XML specifications has been intertwined with a focus to improve the usability of XML.

Table 12-3 contains some of the specifications for XML technologies.

XML Specifications in Java

The XML ecosystem was created by the W3C. But because it works hand in hand with Java, there are several XML-related specifications that were created within the JCP. Examples include from processing XML to binding documents into Java objects.

JAXP (Java Architecture for XML Processing) is a low-level specification (JSR 206) that gives you the possibility to process XML in a very flexible manner; allowing you to use SAX, DOM, or XSLT. It is the API used under the hood for JAXB or StAX.

The JAXB (Java Architecture for XML Binding) specification provides a set of APIs and annotations for representing XML documents as Java artifacts, allowing developers to work with Java objects representing XML documents. JAXB (JSR 222) facilitates unmarshalling XML documents into objects and marshalling objects back into XML documents. Even if JAXB can be used for any XML purpose, it is tightly integrated with JAX-WS (see Chapter 14).

StAX (Streaming API for XML) version 1.0 (JSR 173) is an API to read and write XML documents. Its main focus is to gather the benefits of tree-based APIs (DOM parsers) and event-based APIs (SAX parsers). DOM parsers allow random, unlimited access to the document, while SAX parsers provide a smaller memory footprint and have reduced processor requirements.

Table 12-4 lists all the Java specifications related to XML.

Reference Implementations

The primary goal of a Reference Implementation (RI) is to support the development of the specification and to validate it. StAX RI is the reference implementation for the JSR-173 specification which is based on a standard pull parser streaming model. StAX has been included in JDK since version 1.6 and can be downloaded separately for JDK 1.4 and 1.5. The RI for the JAXP specification is also integrated into Java SE as well as Metro, which is the reference implementation for JAXB. Metro is a production-quality implementation of JAXB that is used directly in a number of Oracle products.

Configuring JAXP

As JAXP is flexible, you can configure it to use any processing implementation you need. But you can always use the defaults as the JAXP reference implementation uses Xerces as the default XML parser and Xalan as the default XSLT processor to transform XML documents.

Imagine a scenario in which there are more than one JAXP-compliant implementations in your classpath. In this case, you have to tell JAXP which API to use. Depending if your application either runs in a standalone client mode or an application server mode, you can provide your application with an XML parser or transformer through a property file. For example, putting a jaxp.properties file (a standard file following the java.util.Properties format) in lib subdirectory of the JRE directory causes the JAXP implementation to use the specified factories. The following is the content of a jaxp.properties file that defines which DOM builder, SAX parser, and XSLT transformer is to be used:

javax.xml.parsers. DocumentBuilderFactory =org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
javax.xml.parsers. SAXParserFactory =org.apache.xerces.jaxp.SAXParserFactoryImpl
javax.xml.transform. TransformerFactory =org.apache.xalan.processor.TransformerFactoryImpl

The other way is to configure Java system properties before running the application. For example, the following system property informs the JVM to use Xerces as XML parser:

-Djavax.xml.parsers. DocumentBuilderFactory =org.apache.xerces.jaxp.DocumentBuilderFactoryImpl

The main system properties that can be modified to introduce new parsers or transformers are listed in Table 12-6.

JAXP with SAX

SAX is known for its low memory requirements and fast processing functionality. SAX is an event-driven, serial access mechanism to parse XML documents. You have to provide the parser with callback methods that are invoked by the parser as it reads the XML document. For example, the SAX parser calls a method in your application each time an element is reached and calls a different method when a text node is encountered.

The way in which you process the current element in an XML document without maintaining any state from previously parsed elements is called state-independent processing. This is the most suited model for processing XML resources with SAX parsers. The other model is state-dependent parsing, which is handled with pull parsers like StAX parsers.

Listing 12-4 shows a class that parses the order.xml document using the SAX event-model. The SaxParsing class extends DefaultHandler which is required for different parsing needs and implements four different handlers (ContentHandler, ErrorHandler, DTDHandler, and EntityResolver). The SAXParserFactory configures and creates a SAX parser instance. As mentioned earlier, it is possible to manually configure the system property javax.xml.parsers.SAXParserFactory to use a third-party SAX parser. The SAXParser wraps a SAXReader object which can be referenced by getXMLReader(). Therefore, when the SAX parser’s parse() method is invoked, the reader invokes one of several handler methods implemented by the application (e.g. the startElement method).

Listing 12-4.  SAX Parser Parsing the Purchase Order Document

public class SaxParsing extends DefaultHandler {
 
  private List<OrderLine> orderLines = new ArrayList<>();
  private OrderLine orderLine;
  private Boolean dealingWithUnitPrice = false;
  private StringBuffer unitPriceBuffer;
 
  public List<OrderLine> parseOrderLines() {
 
    try {
      File xmlDocument = Paths.get("src/main/resources/ order.xml ").toFile();
 
      // SAX Factory
      SAXParserFactory factory = SAXParserFactory.newInstance();
      SAXParser saxParser = factory.newSAXParser();
 
      // Parsing the document
      saxParser. parse (xmlDocument, this);
    } catch (SAXException | IOException | ParserConfigurationException e) {
      e.printStackTrace();
    }
    return orderLines;
  }
 
  @Override
  public void startElement (String namespaceURI, String localName, String qualifiedName, →
                                                Attributes attrs) throws SAXException {
 
    switch (qualifiedName) {
      // Getting the order_line node
      case "order_line":
        orderLine = new OrderLine();
        for (int i = 0; i < attrs.getLength(); i++) {
          switch (attrs.getLocalName(i)) {
            case "item":
              orderLine.setItem(attrs.getValue(i));
              break;
            case "quantity":
              orderLine.setQuantity(Integer.valueOf(attrs.getValue(i)));
              break;
          }
        }
        break;
      case "unit_price":
        dealingWithUnitPrice = true;
        unitPriceBuffer = new StringBuffer();
        break;
    }
  }
 
  @Override
  public void characters (char[] ch, int start, int length) throws SAXException {
      if (dealingWithUnitPrice)
        unitPriceBuffer.append(ch, start, length);
  }
 
  @Override
  public void endElement (String namespaceURI, String localName, String qualifiedName) →
                                                                       throws SAXException {
 
    switch (qualifiedName) {
      case "order_line":
        orderLines.add(orderLine);
        break;
      case "unit_price":
        orderLine.setUnitPrice(Double.valueOf(unitPriceBuffer.toString()));
        dealingWithUnitPrice = false;
        break;
    }
  }
}

The ContentHandler interface handles the basic document-related events like the start and end of elements with startDocument, endDocument, startElement, and endElement methods. These methods are called when the starting or ending of XML document or tags occur. In Listing 12-4 the startElement method checks that the element is either order_line or unit_price to either create an OrderLine object or get the unit price value. The ContentHandler interface also defines the method characters(), which is invoked when the parser encounters a chunk of characters in an XML element (in Listing 12-4 the characters() method buffers the unit price of each item).

To ensure error handling while parsing an XML document, an ErrorHandler can be registered to the SAXReader. The ErrorHandler interface methods (warning, error, and fatalError) are invoked in response to various types of parsing errors.

The DTDHandler interface defines methods to handle DTD-related events. The parser uses the DTDHandler to report notation and unparsed entity declarations to the application. This is useful when processing a DTD to recognize and act on declarations for an unparsed entity.

JAXP with DOM

JAXP provides interfaces to parse and modify the XML data using DOM APIs. The entry point is the javax.xml.parsers.DocumentBuilderFactory class. It is used to produce a DocumentBuilder instance as shown in Listing 12-5. Using one of the parse methods in DocumentBuilder, you can create a tree structure of the XML data in an org.w3c.dom.Document instance. This tree contains tree nodes (such as elements and text nodes), which are implementations of the org.w3c.dom.Node interface. Alternatively, to create an empty Document object, you can use the newDocument() method on the DocumentBuilder instance.

Listing 12-5.  DOM Parser Parsing the Purchase Order Document

public class DomParsing {
 
  public List<OrderLine> parseOrderLines() {
 
    List<OrderLine> orderLines = new ArrayList<>();
 
    try {
      File xmlDocument = Paths.get("src/main/resources/order.xml").toFile();
 
      // DOM Factory
      DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
 
      // Parsing the document
      DocumentBuilder documentBuilder = factory.newDocumentBuilder();
      Document document = documentBuilder. parse (xmlDocument);
 
      // Getting the order_line node
      NodeList orderLinesNode = document.getElementsByTagName(" order_line ");
      for (int i = 0; i < orderLinesNode.getLength(); i++) {
        Element orderLineNode = (Element) orderLinesNode.item(i);
        OrderLine orderLine = new OrderLine();
        orderLine.setItem(orderLineNode.getAttribute(" item "));
        orderLine.setQuantity(Integer.valueOf(orderLineNode.getAttribute(" quantity ")));
 
        Node unitPriceNode = orderLineNode.getChildNodes().item(1);
        orderLine.setUnitPrice(Double.valueOf(unitPriceNode.getFirstChild().getNodeValue()));
 
          orderLines.add(orderLine);
      }
 
    } catch (SAXException | IOException | ParserConfigurationException e) {
      e.printStackTrace();
    }
    return orderLines;
  }
}

Listing 12-5 parses the order.xml document, which results in a tree representation in memory. Thanks to the numerous Document methods, you can then get the list of order_line nodes or the quantity attribute (e.g., getAttribute("quantity")) to create an OrderLine object.

As previously mentioned, it is possible to override the platform's default DOM parser by setting the system property javax.xml.parsers.DocumentBuilderFactory for a different DOM API to be used.

JAXP with XSLT

JAXP is also used to transform XML documents using the XSLT API. XSLT interacts with XML resources to transform an XML source to an XML result using a transformation stylesheet (see Listing 12-3).

Listing 12-6 takes the order.xml document (Listing 12-1) and transforms it into an HTML page using the XSLT defined in Listing 12-3. The code first uses the newInstance() method of the javax.xml.transform.TransformerFactory class, to instantiate a transformer factory. Then, it calls the newTransformer() method to create a new XSLT Transformer. Then it transforms the order.xml document to a stream resulting in an HTML page.

Listing 12-6.  Transforming an XML Document with XSLT

public class XsltTransforming {
 
  public String transformOrder() {
 
    StringWriter writer = new StringWriter();
 
    try {
      File xmlDocument = Paths.get("src/main/resources/ order.xml ").toFile();
      File stylesheet = Paths.get("src/main/resources/ order.xsl ").toFile();
 
      TransformerFactory factory = →
        TransformerFactory.newInstance("net.sf.saxon.TransformerFactoryImpl", null);
 
      // Transforming the document
      Transformer transformer = factory.newTransformer(new StreamSource( stylesheet ));
      transformer.transform(new StreamSource( xmlDocument ), new StreamResult( writer ));
 
    } catch (TransformerException e) {
      e.printStackTrace();
    }
 
    return writer .toString();
  }
}

Binding

The JAXB API, defined in the javax.xml.bind package, provides a set of interfaces and classes to produce XML documents and to generate Java classes. In other words, it binds the two models. The JAXB runtime framework implements the marshall and unmarshall operations. Table 12-7 contains the main JAXB packages for marshalling and unmarshalling operations.

As shown in Figure 12-2, marshalling is the process of converting instances of JAXB-annotated classes to XML representations. Likewise, unmarshalling is the process of converting an XML representation to a tree of objects. During the process of marshalling/unmarshalling, JAXB can also validate the XML against an XSD (Listing 12-9). JAXB can also work at the class level and is able to automatically generate a schema from a set of classes and vice versa.

The center of the JAXB API is the javax.xml.bind.JAXBContext class. This abstract class manages the binding between XML documents and Java objects as it provides:

• An Unmarshaller class that transforms an XML document into an object graph and optionally validates the XML
• A Marshaller class that takes an object graph and transforms it into an XML document

For example, to transform our CreditCard object into an XML document (see Listing 12-10), the Marshaller.marshal() method must be used. This method takes an object as a parameter and marshalls it into several supports (StringWriter to have a string representation of the XML document or FileOutputStream to store it in a file).

Listing 12-10.  A Main Class Marshalling a CreditCard Object

public class Main {
 
  public static void main(String[] args) throws JAXBException {
 
    CreditCard creditCard = new CreditCard("1234", "12/09", 6398, "Visa");
    StringWriter writer = new StringWriter();
 
    JAXBContext context = JAXBContext.newInstance(CreditCard.class);
    Marshaller m = context.createMarshaller();
    m.marshal(creditCard, writer);
 
    System.out.println(writer.toString());
  }
}

The code in Listing 12-10 creates an instance of JAXBContext by using the static method newInstance(), to which it passes the root class that needs to be marshalled (CreditCard.class). From the created Marshaller object, it then calls the marshal() method that generates the XML representation (shown previously in Listing 12-8) of the credit card object into a StringWriter and displays it. The same approach could be used to unmarshall an XML document into objects using the Unmarshaller.unmarshal() method.

Metro the JAXB reference implementation, has other tools, specifically the schema compiler (xjc) and the schema generator (schemaGen). While marshalling/unmarshalling deals with objects and XML documents, the schema compiler and the schema generator deal with classes and XML Schemas. These tools can be used in the command line (they are bundled with Java SE 7) or as Maven goals.

Annotations

JAXB is similar to JPA in many ways. However, instead of mapping objects to a database, JAXB does the mapping to an XML document. Also, like JPA, JAXB defines a set of annotations (in the javax.xml.bind.annotation package) to customize this mapping, and relies on configuration by exception to minimize the work of the developer. If persistent objects have to be annotated with @Entity, the correspondent in JAXB is @XmlRootElement (see Listing 12-11).

Listing 12-11.  A Customized CreditCard Class

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class CreditCard {
 
  @XmlAttribute(required = true)
  private String number;
  @XmlElement(name = "expiry-date", defaultValue = "01/10")
  private String expiryDate;
  private String type;
  @XmlElement(name = "control-number")
  private Integer controlNumber;
 
  // Constructors, getters, setters
}

In Listing 12-11 the @XmlRootElement annotation notifies JAXB that the CreditCard class is the root element of the XML document. If this annotation is missing, JAXB will throw an exception when trying to marshall it. This class is then mapped to the schema shown in Listing 12-12 using all the JAXB default mapping rules (each attribute is mapped to an element and has the same name).

Listing 12-12.  The Credit Card Schema with Attributes and Default Values

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs=" http://www.w3.org/2001/XMLSchema ">
 
  <xs:element name="creditCard" type="creditCard"/>
 
  <xs:complexType name="creditCard">
    <xs:sequence>
      <xs:element name=" expiry-date " type="xs:string" default="01/10" minOccurs="0"/>
      <xs:element name="type" type="xs:string" minOccurs="0"/>
      <xs:element name=" control-number " type="xs:int" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="number" type="xs:string" use="required"/>
  </xs:complexType>
</xs:schema>

With a Marshaller object, you can easily get an XML representation of a CreditCard object (shown earlier in Listing 12-10). The root element <creditCard> represents the CreditCard object, and it includes the value of each attribute.

JAXB provides a way to customize and control this XML structure. An XML document is made of elements (<element>value</element>) and attributes (<element attribute="value"/>). JAXB uses two annotations to differentiate them: @XmlAttribute and @XmlElement. Each annotation has a set of parameters that allows you to rename an attribute, allow null values or not, give default values, and so forth. The class properties are mapped to XML elements by default if they are not annotated with @XmlAttribute annotation.

Listing 12-11 uses these annotations to turn the credit card number into an attribute (instead of an element) and to rename the expiry date and control number. This class will get mapped to a different schema in which the credit card number is represented as a required <xs:attribute>, and the expiry date is renamed and has a default value set to 01/10, as shown in Listing 12-12.

The XML representation of the CreditCard will also change as you can see Listing 12-13 (compared with the one in Listing 12-8).

Listing 12-13.  An XML Document Representing a Customized CreditCard Object

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<creditCard number ="1234">
  < expiry-date >12/09</expiry-date>
  <type>Visa</type>
  < control-number >6398</control-number>
</creditCard>

Table 12-8 lists the main JAXB annotations. Some can annotate attributes (or getters), others classes, and some can be used on an entire package (such as @XmlSchema).

When using these annotations, you can map objects to a specific XML Schema. And sometimes you need this flexibility with legacy web services, as you will see in the coming chapters. Referring to JPA, when you need to map entities to a legacy database, there is a set of annotations that allows the customization of every part of the mapping (columns, table, foreign keys, etc.). With web services, it’s similar: web services are described in a WSDL file written in XML. If it’s a legacy web service, its WSDL cannot change. Instead, a mechanism to map it to objects must be used, which is why JAXB is used with web services.

JSON Document

JSON is a text-based language-independent format that uses a set of conventions to represent simple data structures. Many languages have implemented APIs to parse JSON documents. Data structures in JSON are human-readable and are much like data structures in Java. JSON can represent four primitive types (number, string, booleans, and null) and two structured types (objects and arrays). Table 12-9 lists the JSON conventions to represent data.

Colon (:) is used as the name-separator and comma as the value-separator in JSON. Valid JSON data is a serialized object or array of data structures that can be nested. For example, a JSON object can contain a JSON array. In Listing 12-14, content is an object that contains an array of order_line.

JSON-P

Java API for JSON Processing (JSR 353) known as JSON-P, is a specification that allows JSON processing in Java. The processing includes mechanisms to parse, generate, transform, and query JSON data. JSON-P provides a standard to build a Java object in JSON using an API similar to DOM for XML. At the same time, it provides a mechanism to produce and consume JSON by streaming in a manner similar to StAX for XML.

Although it is not a strict requirement in the original JSR, some JSON-P implementations may also provide binding of JSON data to Java objects and vice versa (but this will be specified in a future JSR, which could be called JSON-B, ‘B’ for Binding). Table 12-10 lists the important JSON-P packages.

Reference Implementation

There are several JSON processors implemented in Java, but the open source reference implementation for JSON-P (JSR 353) is JSON RI.

Building JSON

The object and array structures in JSON are represented by the javax.json.JsonObject and javax.json.JsonArray classes. The API lets you navigate and query the tree structure of data.

JsonObject provides a Map view to access the unordered collection of zero or more name/value pairs. Similarly, JsonArray provides a List view to access the ordered sequence of zero or more values. The API uses the builder patterns to create the tree representation of JsonObject and JsonArray through the javax.json.JsonObjectBuilder and javax.json.JsonArrayBuilder interfaces.

Listing 12-15 shows how to build the purchase order in JSON described in Listing 12-14. As you can see, the Json class is used to create JsonObjectBuilder and JsonArrayBuilder objects that will end up building a JsonObject (using the final build() method). JsonObject provides a map view to the JSON object name/value mappings.

Listing 12-15.  The OrderJsonBuilder Class Building a Purchase Order in JSON

public class OrderJsonBuilder {
 
  public JsonObject buildPurchaseOrder() {
 
    return Json.createObjectBuilder ().add("order", Json. createObjectBuilder ()
            .add("id", "1234")
            .add("date", "05/06/2013")
            .add("customer", Json. createObjectBuilder ()
                .add("first_name", "James")
                .add("last_name", "Rorrison")
                .add("email", " [email protected] ")
                .add("phoneNumber", "+44 1234 1234"))
            .add("content", Json. createObjectBuilder ()
                .add("order_line", Json. createArrayBuilder ()
                            .add(Json. createObjectBuilder ()
                                    .add("item", "H2G2")
                                    .add("quantity", "1")
                                    .add("unit_price", "23.5"))
                            .add(Json. createObjectBuilder ()
                                    .add("item", "Harry Potter")
                                    .add("quantity", "2")
                                    .add("unit_price", "34.99"))))
            .add("credit_card", Json. createObjectBuilder ()
                    .add("number", "1357")
                    .add("expiry_date", "10/13")
                    .add("control_number", "234")
                    .add("type", "Visa"))). build ();
  }
}

The JsonObject can also be created from an input source (such as InputStream or Reader) using the interface javax.json.JsonReader. The following example shows how to read and create the JsonObject using the interface JsonReader. A JsonReader is created from an order.json file (Listing 12-14). Then, to access the order object, the getJsonObject() method is called and returns a JsonObject. If no object is found, null is returned:

JsonReader reader = Json.createReader(new FileReader("order.json"));
JsonObject jsonObject = reader.readObject();
jsonObject  = jsonObject.getJsonObject("order");

JsonReader also provides the general read() method to read any javax.json.JsonStructure subtype (JsonObject and JsonArray). Using the JsonStructure.getValueType() method returns the ValueType (ARRAY, OBJECT, STRING, NUMBER, TRUE, FALSE, NULL) and then you can read the value. The toString() method on JsonStructure returns the JSON representation of the object model.

Similarly, JsonObject and JsonArray can be written to an output source (such as OutputStream or Writer) using the class javax.json.JsonWriter. The builder method Json.createWriter()can create a JsonWriter for different outputs.

Parsing JSON

The Streaming API (package javax.json.stream) facilitates parsing JSON via streaming with forward and read-only access. It provides the javax.json.stream.JsonParser interface to parse a JSON document. The entry point is the javax.json.Json factory class, which provides a createParser() method that returns a javax.json.stream.JsonParser from a specified input source (such as a Reader or an InputStream). As an example, a JSON parser for parsing an empty JSON object could be created as follows:

StringReader reader = new StringReader("{}");
JsonParser parser = Json.createParser(reader);

You can configure the parser by passing a Map property to the createParserFactory() method. This factory creates a JsonParser specifically configured to parse your JSON data:

StringReader reader = new StringReader("{}");
JsonParserFactory factory = Json.createParserFactory(properties) ;
JsonParser parser = factory.createParser (reader);

The JsonParser is based on a pull parsing streaming model. Meaning that the parser generates events when a JSON name/value is reached or the beginning/end of an object/array is read. Table 12-11 lists all of the events triggered by the parser.

The class in Listing 12-16 parses the JSON in Listing 12-14 (saved in an order.json file) to extract the customer’s e-mail. The parser moves forward until it encounters an email property name. The next() method causes the parser to advance to the next parsing state. It returns the next javax.json.stream.JsonParser.Event enum (Table 12-11) of for the next parsing state. When the parser reaches the email property value, it returns it.

Listing 12-16.  The OrderJsonParser Class Parsing the JSON Representation of the Purchase Order

public class OrderJsonParser {
 
  public String parsePurchaseOrderAndReturnEmail() throws FileNotFoundException {
    String email = null;
 
    JsonParser parser = Json.createParser (new FileReader("src/main/resources/ order.json "));
    while ( parser.hasNext() ) {
      JsonParser.Event event = parser.next();
      while (parser.hasNext() && !( event.equals (JsonParser.Event. KEY_NAME ) && →
                                   parser.getString().matches(" email "))) {
        event = parser. next ();
      }
 
      if ( event.equals (JsonParser.Event. KEY_NAME ) && parser.getString().matches(" email ")) {
        parser.next();
        email = parser. getString ();
      }
    }
    return email;
  }
}

By using the Event.equals() method, you can determine the type of the event and process the JSON based on the event. While the JsonParser streams the JSON, you can use the getString() method to get a String representation for each name (key) and value depending on the state of the parser. The name is returned if the event is KEY_NAME, the String value is returned when the event is VALUE_STRING, and the number value when the event is VALUE_NUMBER. In addition to getString(), which returns a String value, you can use other methods such as getIntValue(), getLongValue(), and getBigDecimalValue(), depending on the type.

If an incorrect data format is encountered while parsing, the parser will throw runtime exceptions such as javax.json.stream.JsonParsingException and java.lang.IllegalStateException, depending on the source of the problem.

Generating JSON

The JSON builder APIs allow you to build a JSON tree structure in memory. The JsonParser parses a JSON object via streaming, whereas the javax.json.stream.JsonGenerator allows the writing of JSON to a stream by writing one event at a time.

The class in Listing 12-17 uses the createGenerator() method from the main javax.json.Json factory to get a JsonGenerator and generates the JSON document defined in Listing 12-14. The generator writes name/value pairs in JSON objects and JSON arrays.

Listing 12-17.  Generating a Purchase Order Object In JSON

public class OrderJsonGenerator {
 
  public StringWriter generatePurchaseOrder() throws IOException {
    StringWriter writer = new StringWriter();
    JsonGenerator generator = Json.createGenerator (writer);
    generator. writeStartObject ()
             .write("id", "1234")
             .write("date", "05/06/2013")
             . writeStartObject ("customer")
               .write("first_name", "James")
               .write("last_name", "Rorrison")
               .write("email", " [email protected] ")
               .write("phoneNumber", "+44 1234 1234")
             . writeEnd ()
             . writeStartArray ("content")
               . writeStartObject ()
                 .write("item", "H2G2")
                 .write("unit_price", "23.5")
                 .write("quantity", "1")
               .writeEnd()
               .writeStartObject()
                 .write("item", "Harry Potter")
                 .write("unit_price", "34.99")
                 .write("quantity", "2")
               .writeEnd()
             . writeEnd ()
             .writeStartObject("credit_card")
               .write("number", "123412341234")
               .write("expiry_date", "10/13")
               .write("control_number", "234")
               .write("type", "Visa")
             .writeEnd()
           .writeEnd()
           . close ();
    return writer;
  }
}

Familiarity with object and array contexts is needed when generating JSON. JSON name/value pairs can be written to an object, whereas JSON values can be written to an array. While the writeStartObject() method writes a JSON start object character ({), the writeStartArray() method is used to write a JSON start array character ([). Each opened context must be terminated using the writeEnd() method. After writing the end of the current context, the parent context becomes the new current context.

The writeStartObject() method is used to start a new child object context and the writeStartArray() method starts a new child array context. Both methods can be used only in an array context or when a context is not yet started and both can only be called when no context is started. A context is started when one of these methods are used.

The JsonGenerator class provides other methods, such as write(), to write a JSON name/value pair in the current object context or to write a value in current array context.

Although the flush() method can be used to write any buffered output to the underlying stream, the close() method closes the generator and frees any associated resources.

Writing the CreditCard Class

The CreditCard class in Listing 12-18 is annotated with the JAXB @XmlRootElement annotation to be marshalled into XML. The other JAXB annotation @XmlAccessorType, with parameter XmlAccessType.FIELD, tells JAXB to bind the attributes rather than the getters.

Listing 12-18.  The CreditCard Class with a JAXB Annotation

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class CreditCard {
 
  @XmlAttribute
  private String number;
  @XmlElement(name = "expiry_date")
  private String expiryDate;
  @XmlElement(name = "control_number")
  private Integer controlNumber;
  private String type;
 
  // Constructors, getters, setters
}

The CreditCard object has some basic fields such as the credit card number, the expiry date (formatted as MM/YY), a credit card type (Visa, Master Card, American Express, etc.), and a control number. Some of these attributes are annotated with @XmlAttribute to be mapped to an XML attribute. The @XmlElement is used to override the XML element name.

Writing the CreditCardXMLTest Unit Test

The CreditCardXMLTest class shown in Listing 12-19 marshalls and unmarshalls a CreditCard object back and forth from XML to Java using the JAXB marshalling mechanism. The shouldMarshallACreditCard method creates an instance of the CreditCard class and checks it has the correct XML representation. The method shouldUnmarshallACreditCard does the opposite as it unmarshalls the XML document into a CreditCard instance and checks that the object is correctly set.

Listing 12-19.  The CreditCardXMLTest Unit Test Marshalls and Unmarshalls XML

public class CreditCardXMLTest {
 
  public static final String creditCardXML =
          "<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
" +
          "<creditCard number="12345678">
" +
          "    <expiry_date>10/14</expiry_date>
" +
          "    <control_number>566</control_number>
" +
          "    <type>Visa</type>
" +
          "</creditCard>";
 
  @Test
  public void shouldMarshallACreditCard () throws JAXBException {
 
    CreditCard creditCard = new CreditCard("12345678", "10/14", 566, "Visa");
 
    StringWriter writer = new StringWriter();
    JAXBContext context = JAXBContext.newInstance(CreditCard.class);
    Marshaller m = context.createMarshaller();
    m.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
    m. marshal (creditCard, writer);
 
    System.out.println(writer);
 
    assertEquals( creditCardXML , writer.toString().trim());
 
  }
 
  @Test
  public void shouldUnmarshallACreditCard () throws JAXBException {
    StringReader reader = new StringReader( creditCardXML );
    JAXBContext context = JAXBContext.newInstance(CreditCard.class);
    Unmarshaller u = context.createUnmarshaller();
    CreditCard creditCard = (CreditCard) u. unmarshal (reader);
 
    assertEquals("12345678", creditCard.getNumber());
    assertEquals("10/14", creditCard.getExpiryDate());
    assertEquals((Object) 566, creditCard.getControlNumber());
    assertEquals("Visa", creditCard.getType());
  }
}

Writing the CreditCardJSonTest Unit Test

The CreditCardJSonTest class shown in Listing 12-20 uses the JsonGenerator API to write a JSON object representation of a CreditCard. It then checks that the JSonObject has a valid syntax by comparing it to the creditCardJSon constant.

Listing 12-20.  The CreditCardJSonTest Unit Test Generates JSon

public class CreditCardJSonTest {
 
  public static final String creditCardJSon =
          "{"creditCard":" +
                  "{"number":"12345678"," +
                  ""expiryDate":"10/14"," +
                  ""controlNumber":566," +
                  ""type":"Visa"}" +
          "}";
 
  @Test
  public void shouldGenerateACreditCard(){
 
    CreditCard creditCard = new CreditCard("12345678", "10/14", 566, "Visa");
 
    StringWriter writer = new StringWriter();
    JsonGenerator generator = Json.createGenerator(writer);
    generator.writeStartObject()
             .writeStartObject("creditCard")
               .write("number", creditCard.getNumber())
               .write("expiryDate", creditCard.getExpiryDate())
               .write("controlNumber", creditCard.getControlNumber())
               .write("type", creditCard.getType())
             .writeEnd()
           .writeEnd()
           .close();
 
    assertEquals( creditCardJSon , writer.toString().trim());
 
  }
}