Using XML in Java

Section 1

About XML

By Masoud Kalali

XML is a general-purpose specification for creating custom mark-up languages. It is classified as an extensible language because it allows its users to define their own elements. Its primary purpose is to help information systems share structured data, particularly via the Internet, and it is used both to encode documents and to serialize data. In the latter context, it is comparable with other text-based serialization languages such as JSON and YAML.

As a diverse platform, Java has several solutions for working with XML. This refcard provides developers a concise overview of the different xml processing technologies in Java, and a use case of each technology.

Section 2

XML File Sample

<?xml version=”1.0” encoding=”UTF-8”?>
<!DOCTYPE publications SYSTEM “publications.dtd”>
<publications
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://xml.dzone.org/schema/publications
publications.xsd”
xmlns=”http://xml.dzone.org/schema/publications”
xmlns:extras=”http://xml.dzone.org/schema/publications”>
  <book id=”_001”>
    <title>Beginning XML, 4th Edition </title>
   <author>David Hunter</author>
   <copyright>2007</copyright>
   <publisher>Wrox</publisher>
   <isbn kind=”10”>0470114878</isbn>
 </book>
 <book id=”_002”>
   <title>XML in a Nutshell, Third Edition</title>
   <author>O’Reilly Media, Inc</author>
   <copyright>2004</copyright>
   <publisher>O’Reilly Media, Inc.</publisher>
   <isbn kind=”10”>0596007647</isbn>
 </book>
 <extras:book id=”_003” image=”erik_xml.jpg”>
   <title>Learning XML, Second Edition</title>
   <author>Erik Ray</author>
   <copyright>2003</copyright>
   <publisher>O’Reilly Media, Inc.</publisher>
   <isbn kind=”10”>0596004206</isbn>
 </extras:book>
</publications>
​

Line 1: An XML document always starts with a prolog which describes the XML file. This prolog can be minimal, e.g. <?xml version=”1.0”?> or can contain other information. For example, the encoding: <?xml version=”1.0” encoding=”UTF-8” standalone=”yes” ?>

Line 2: DOCTYPE : DTD definitions can either be embedded in the XML document or referenced from a DTD file. Using the System keyword means that the DTD file should be in the same folder our XML file resides.

Line 3: ROOT ELEMENT: Every well-formed document should have one and only one root element. All other elements reside inside the root element.

Lines 4 – 8: namespace declaration: Line 4 defines the XSI prefix, lines 5 & 6 defines the current URL and XSD file location, line 7 defines the current document default namespace, and line 8 defines a prefix for an XML schema.

Line 20: Element: An element is composed of its start tag, end tag and the possible content which can be text or other nested elements.

XML File Sample, Continued

Line 23: namespace prefixed tag: a start tag prefixed by a namespace. End tag must be namespace prefixed in order to get a document, the end tag is line 29.

Line 28: Attribute: an attribute is part of an element, consisting of an attribute name and its value.

Capabilities of Element and Attribute

Capability	Attribute	Element
Hierarchical	No – flat	Yes
Ordered	No – undefined	Yes
Complex types	No – string only	Yes
Verbose	Less – usually	More
Readability	Less	More – usually

XML Use Cases

Requirement/Characteristic	Suitable XML Features
Interoperability	XML can be used independent of the target language or platform or target device. Use XML when you need to support or interact with multiple platforms.
Multiple output format for multiple devices	XML Transformation can help you get a required format from plain XML files. Use XML as the preferred output format when multiple output formats are required.
Content size	Use XML when messaging and processing efficiency is less important than interoperability and availability of standard tools. Large content can create a big XML document. Use compression for XML documents or use other industry standards like ASN.1.
Project size	For Using XML you need at least XML parsing libraries and helper classes to measure the project size and XML related required man/ hour before using XML. For small projects with simple requirements, you might not want to incur the overhead of XML.
Searching	There are some technologies for searching in a XML document like XPath (www.w3schools.com/XPath/default. asp) and Xquery (http://www.xquery.com/) but they are relatively young and immature. Don’t use XML documents when searching is important. Instead, store the content in a traditional database, use XML databases or use XML-aware databases.

Section 3

Parsing Techniques

In order to use a XML file or a XML document inside an application, it will be required to read it and tokenize it. For the XML files, this is called XML Parsing and the piece of software which performs this task is called a Parser.

There are two general parsing techniques:

In Memory Tree: The entire document is read into memory as a tree structure which allows random access to any part of the document by the calling application.
Streaming (Event processing): A Parser reads the document and fires corresponding event when it encounters XML entities.

Two types of parsers use streaming techniques:

Push parsers: Parsers are in control of the parsing and the parser client has no control over the parsing flow.
Pull parsers: The Parser client is in control of the parsing and the parser goes forward to the next infoset element when it is asked to.

Following are parsers generally available in the industry:

DOM: DOM is a tree-based parsing technique that builds up an entire parse tree in memory. It allows complete dynamic access to a whole XML document.
SAX: SAX is an event-driven push model for processing XML. It is not a W3C standard, but it’s a very well recognized API that most SAX parsers implement in a compliant way. Rather than building a tree representation of an entire document as DOM does, a SAX parser fires off a series of events as it reads through the document.
StAX (JSR 173): StAX was designed as a median between DOM and SAX. In StAX, the application moves the cursor forward ‘pulling’ the information from the parser as it needs. So there is no event firing by the parser or huge memory consumption. You can use 3rd party libraries for Java SE 5 and older or bundled StAX parser of Java SE 6 and above.

Feature	StAX	SAX	DOM
API Type	Pull, streaming	Push, streaming	In memory tree
Ease of Use	High	Medium	High
XPath Capability	No	No	Yes
CPU and Memory Efficiency	Good	Good	Varies
Forward Only	Yes	Yes	No
Read XML	Yes	Yes	Yes
Write XML	Yes	No	Yes
Create, Read, Update or Delete Nodes	No	No	Yes

Parsing Techniques, Continued

Best for
Applications in
need of:

Streaming Model
Not modifying
the document
Memory efficiency
XML read and XML write
Parsing multiple
documents in the
same thread
Small devices
Looking certain tag

Read only manipulation
Not modifying the document
Memory efficiency
Small devices
Looking for a certain tag

Modifying the XML document
XPath, XSLT
XML tree traversing and
random access
to any section
Merging documents

All of these parsers fall under JAXP implementation. The following sample codes show how we can utilize Java SE 6 XML processing capabilities for XML parsing.

Section 4

Parsing XML Using DOM

​x
DocumentBuilderFactory factory = DocumentBuilderFactory.
newInstance();
factory.setValidating(true);
factory.setNamespaceAware(true);
factory.setAttribute(“http://java.sun.com/xml/jaxp/properties
/schemaLanguage”, “http://www.w3.org/2001/XMLSchema”);
DocumentBuilder builder = factory.newDocumentBuilder();
builder.setErrorHandler(new SimpleErrorHandler());
Document doc = builder.parse(“src/books.xml”);
NodeList list = doc.getElementsByTagName(“*”);
for (int i = 0; i < list.getLength(); i++) {
            Element element = (Element) list.item(i);
            System.out.println(element.getNodeName() + “ “ +
            element.getTextContent());
            if (element.getNodeName().equalsIgnoreCase(“book”)) {
                    System.out.println(“Book ID= “ + element
                    getAttribute(“id”));
             }
    if (element.getNodeName().equalsIgnoreCase(“isbn”)) {
                     System.out.println(“ISBN Kind=” + element
                    getAttribute(“kind”));
            }
​

Line 16: In order to validate the XML using internal DTD we need only to setValidation(true). To validate a document using DOM, ensure that there is no schema in the document, and no element prefix for our start and end tags.

Line 17: The created parser is namespace aware (the namespace prefix will be dealt with as a prefix, and not a part of the element).

Lines 18 – 19: The created parser uses internal XSD to validate the document Dom BuilderFactory instances accept several features which let developers enable or disable a functionality, one of them is validating against the internal XSD.

Line 21: Although DOM can use some default error handler, it’s usually better to set our own error handler to handle different levels of possible errors in the document. The default handler has different behaviors based on the implementation that we use. A simple error handler might be:

public class SimpleErrorHandler implements ErrorHandler {
12
     public void warning(SAXParseException e) throws SAXException
{
             System.out.println(e.getMessage());
     }
16
     public void error(SAXParseException e) throws SAXException {
       System.out.println(e.getMessage());
     }
20
     public void fatalError(SAXParseException e) throws SAXException {
            System.out.println(e.getMessage());
}
}
}

Section 5

Parsing XML Using SAX

For using SAX, we need the parser and an event handler that should respond to the parsing events. Events can be a start element event, end element event, and so forth.

A simple event handler might be:

public class SimpleHandler extends DefaultHandler {
​
public void startElement(String namespaceURI, String localName,
        String qName, Attributes atts)
        throws SAXException {
  if (“book”.equals(localName)) {
        System.out.print(“Book details: Book ID: “ + atts
        getValue(“id”));
  } else {
        System.out.print(localName + “: “);
        }
}
public void characters(char[] ch, int start, int length)
        throws SAXException {
  System.out.print(new String(ch, start, length));
}
  public void endElement(String namespaceURI, String localName,
  String qName)
        throws SAXException {
  if (“book”.equals(localName)) {
        System.out.println(“=================================”);
        }
  }
}
​

The parser code that uses the event handler to parse the book. xml document might be:

SAXParser saxParser;
SAXParserFactory factory = SAXParserFactory.newInstance();
factory.setNamespaceAware(true);
factory.setValidating(true);
saxParser = factory.newSAXParser();
saxParser.setProperty(
        “http://java.sun.com/xml/jaxp/properties/schemaLanguage”,
  “http://www.w3.org/2001/XMLSchema”);
XMLReader reader = saxParser.getXMLReader();
reader.setErrorHandler(new SimpleErrorHandler());
reader.setContentHandler(new SimpleHandler());
reader.parse(“src/books.xml”);
​

Section 6

Parsing XML Using StAX

StAX is a streaming pull parser. It means that the parser client can ask the parser to go forward in the document when it needs. StAX provides two sets of APIs:

The cursor API methods return XML information as strings, which minimizes object allocation requirements.
Iterator-based API which represents the current state of the parser as an Object. The parser client can get all the required information about the element underlying the event from the object.

Differences and features of StAX APIs

Cursor API: Best in frameworks and libraries	Iterator API: Best in applications
More memory efficient	XMLEvent subclasses are immutable(Direct use in other part of the application)
Better overall performance	New subclass of XMLEvent can be developed and used when required
Forward only	Applying event filters to reduce event processing costs

Section 7

A Sample Using StAX Parser

XMLInputFactory inputFactory = XMLInputFactory.newInstance();
InputStream in = new FileInputStream(“src/books.xml”);
XMLEventReader eventReader = inputFactory.createXMLEventReader(in);
while (eventReader.hasNext()) {
 XMLEvent event = eventReader.nextEvent();
 if (event.isEndElement()) {
   if (event.asEndElement().getName().getLocalPart()
   equals(“book”)) {
        event = eventReader.nextEvent();
        System.out.println(“=================================”);
        continue;
}
}
if (event.isStartElement()) {
if (event.asStartElement().getName().getLocalPart()
equals(“title”)) {
        event = eventReader.nextEvent();
        System.out.println(“title: “ + event.asCharacters()
        getData());
        continue;
}
if (event.asStartElement().getName().getLocalPart()
equals(“author”)) {
        event = eventReader.nextEvent();
        System.out.println(“author: “ + event.asCharacters()
        getData());
        continue;
}
if (event.asStartElement().getName().getLocalPart()
equals(“copyright”)) {
        event = eventReader.nextEvent();
        System.out.println(“copyright: “ + event
        asCharacters().getData());
        continue;
}
if (event.asStartElement().getName().getLocalPart()
equals(“publisher”)) {
        event = eventReader.nextEvent();
        System.out.println(“publisher: “ + event.asCharacters()
        getData());
        continue;
}
if (event.asStartElement().getName().getLocalPart()
equals(“isbn”)) {
        event = eventReader.nextEvent();
        System.out.println(“isbn: “ + event.asCharacters()
        getData());
        continue;
}
}
}
​

Section 8

XML Structure

There are two levels of correctness of an XML document:

Well-formed-ness. A well-formed document conforms to all of XML’s syntax rules. For example, if a start-tag appears without a corresponding end-tag, it is not well-formed. A document that is not well-formed is not considered to be XML.

Sample characteristics:

XML documents must have a root element
XML elements must have a closing tag
XML tags are case sensitive
XML elements must be properly nested
XML attribute values must always be quoted

Validity. A valid document conforms to semantic rules. The rules are included as XML schema, especially DTD. Examples of invalid documents include: if a required attribute or element is not present in the document; if the document contains an undefined element; if an element is meant to be repeated once, and appears more than once; or if the value of an attribute does not conform to the defined pattern or data type.

XML Structure, Continued

XML validation mechanisms include using DTD and XML schema like XML Schema and RelaxNG.

Document Type Definition (DTD)

A DTD defines the tags and attributes used in a XML or HTML document. Elements defined in a DTD can be used, along with the predefined tags and attributes of each markup language. DTD support is ubiquitous due to its inclusion in the XML 1.0 standard.

DTD Advantages:	DTD Disadvantages:
Easy to read and write (plain text file with a simple semi-xml format).	No type definition system.
Can be used as an in-line definition inside the XML documents.	No means of element and attribute content definition and validation.
Includes #define, #include, and #ifdef; the ability to define shorthand abbreviations, external content, and some conditional parsing.

A sample DTD document

 <?xml version=”1.0” encoding=”UTF-8”?>
<!ELEMENT publications (book*)>
<!ELEMENT book (title, author+, copyright, publisher, isbn,
description?)>
<!ELEMENT title (#PCDATA)>
<!ELEMENT author (#PCDATA)>
<!ELEMENT copyright (#PCDATA)>
<!ELEMENT publisher (#PCDATA)>
<!ELEMENT isbn (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ATTLIST book id ID #REQUIRED image CDATA #IMPLIED>
<!ATTLIST isbn kind (10|13) #REQUIRED >
​

Line 2: publications element has 0...unbounded number of book elements inside it.

Line 3: book element has one or more author elements, 0 or 1 description elements and
exactly one title, copyright, publisher and isbn elements inside it.

Line 11: book element has two attributes, one named id of type ID which is mandatory,
and an image attribute from type CDATA which is optional.

Line 12: isbn element has an attribute named kind which can have 10 or 13 as its value.

DTD Attribute Types

DTD Attribute Type	Description
CDATA	Any character string acceptable in XML
NMTOKEN	Close to being a XML name; first character is looser
NMTOKENS	One or more NMTOKEN tokens separated by white space Enumeration List of the only allowed values for an attribute
ENTITY	Associates a name with a macro-like replacement
ENTITIES	White-space-separated list of ENTITY names
ID	XML name unique within the entire document
IDREF	Reference to an ID attribute within the document
IDREFS	White-space-separated list of IDREF tokens
NOTATION	Associates a name with information used by the client

What a DTD can validate

Element nesting

Element occurrence

Permitted attributes of an element

Attribute types and default values

XML Schema Definition (XSD)

XSD provides the syntax and defines a way in which elements and attributes can be represented in a XML document. It also advocates the XML document should be of a specific format and specific data type. XSD is fully recommended by the W3C consortium as a standard for defining a XML Document. XSD documents are written in XML format.

XSD Advantages:	XSD Disadvantages:
XSD has a much richer language for describing what element or attribute content “looks like.” This is related to the type system.	Verbose language, hard to read and write
XSD Schema supports Inheritance, where one schema can inherit from another schema. This is a great feature because it provides the opportunity for re-usability.	Provides no mechanism for the user to add more data types.
It is namespace aware and provides the ability to define its own data type from the existing data type.

A sample XSD document

<?xml version=”1.0” encoding=”UTF-8”?>
<xs:schema xmlns:xs=”http://www.w3.org/2001/XMLSchema”
       xmlns:extras=”http://xml.dzone.org/schema/publications”
       attributeFormDefault=”unqualified” elementFormDefault=”unqualified”
       xmlns=”http://xml.dzone.org/schema/publications”
       targetNamespace=”http://xml.dzone.org/schema/publications”
       version=”4”>
     <xs:element name=”publications”>
       <xs:complexType>
     <xs:sequence>
                    <xs:element minOccurs=”0” maxOccurs=”unbounded”
                    ref=”book”/>
     </xs:sequence>
  </xs:complexType>
</xs:element>
<xs:element name=”book”>
  <xs:complexType>
             <xs:sequence>
       <xs:element ref=”title”/>
               <xs:element minOccurs=”1” maxOccurs=”unbounded”
               ref=”author”/>
               <xs:element ref=”copyright”/>
               <xs:element ref=”publisher”/>
               <xs:element ref=”isbn”/>
               <xs:element minOccurs=”0” ref=”description”/>
     </xs:sequence>
     <xs:attributeGroup ref=”attlist.book”/>
  </xs:complexType>
</xs:element>
<xs:element name=”title” type=”xs:string”/>
<xs:element name=”author” type=”xs:string”/>
<xs:element name=”copyright” type=”xs:string”/>
<xs:element name=”publisher” type=”xs:string”/>
<xs:element name=”isbn”>
  <xs:complexType mixed=”true”>
               <xs:attributeGroup ref=”attlist.isbn”/>
  </xs:complexType>
</xs:element>
<xs:element name=”description” type=”xs:string”/>
<xs:attributeGroup name=”attlist.book”>
      <xs:attribute name=”id” use=”required” type=”xs:ID”/>
  <xs:attribute name=”image”/>
</xs:attributeGroup>
<xs:attributeGroup name=”attlist.isbn”>
  <xs:attribute name=”kind” use=”required”>
       <xs:simpleType>
                      <xs:restriction base=”xs:token”>
                              <xs:enumeration value=”10”/>
                          <xs:enumeration value=”13”/>
          </xs:restriction>
       </xs:simpleType>
   </xs:attribute>
 </xs:attributeGroup>
</xs:schema>
​

Lines 2 – 7: Line 2 defines XML Schema namespace. Line 3 defines available schemas where it can use its vocabulary. Line 4 specifies whether locally declared elements and attributes are namespace qualified or not. A locally declared element is an element declared directly inside a complexType (not by reference), Line 5 declares the default namespace for this schema document. Lines 6 and 7 define the namespace that a XML document can use in order to make it possible to validate it with this schema.

XML Schema Definition (XSD), Continued

Lines 9 – 14: An element named publications has a sequence of an unbounded number of books inside it.

Line 20: the element named book has a sequence of multiple elements inside it including author which at least should appear as 1, and also an element named description with a minimum occurrence of 0. Its maximum occurrence is the default value which is 1.

Lines 34 – 38: the isbn element has a group of attributes referenced by a attlist.isbn. This attribute group includes one attribute named kind (Lines 46 – 51) with a simple value. The value has a restriction which requires it to be one of the enumerated values included in the definition.

The separation of an element type definition and its use. We declared our types separately from where we referenced them (use them). ref attributes point to a declaration with the same name. Using this technique we can have separate XSD files and each of them contains definition and declarations related to one specific package. We can also import or include them in other XSD documents, if needed.

Import and include. The import and include elements help to construct a schema from multiple documents and namespaces. The import element brings in a schema from a different namespace, while the include element brings in a schema from the same namespace. When include is used, the target namespace of the included schema must be the same as the target namespace of the including schema. In the case of import, the target namespace of the included schema must be different.

To validate XML files using external XSD, replace line 17 – 20 of the DOM sample with:

    Java
   
 
factory.setValidating(false);
factory.setNamespaceAware(true);
SchemaFactory schemaFactory = SchemaFactory.newInstance("http:/www.w3.org/2001/XMLSchema");
factory.setSchema(schemaFactory.newSchema(new Source[]{new StreamSource("src/publication.xsd"))});

XML Schema validation factors

Validation factor	Description
Length, minLength, maxLength, maxExclusive, maxInclusive, minExclusive, minInclusive	Enforces a length for the string derived value, either its maximum, minimum, maximum or minimum, inclusive and exclusive.
enumeration	Restricts values to a member of a defined list
TotalDigits, fractionDigits	Enforces total digits in a number; signs and decimal points skipped. Enforces total fractional digits in a fractional number
whiteSpace	Used to preserve, replace, or collapse document white space

XML Schema built-in types

Type	Description
anyURI	Uniform Resource Identifier
base64Binary	base64 encoded binary value
Boolean; byte; dateTime; integer; string	True, false or 0, 1; Signed quantity >= 128 and < 127; An absolute date and time; Signed integer; Unicode string
ID, IDREF, IDREFS,ENTITY, ENTITIES,	Used to preserve, replace, or collapse document white space
NOTATION, NMTOKEN,NMTOKENS	Same definitions as those in DTD
language	"xml:lang" values from XML 1.0 Recommendation.
name	An XML name

DTD and XSD validation capabilities

W3C XML Schema Features	DTD Features
Namespace-qualified element and attribute declarations	Element nesting
Simple and complex data types	Element occurrence
Type derivation and inheritance	Permitted attributes of an element
Element occurrence constraints	Attribute types and default values

Section 9

XPath

XPath is a declarative language used for referring to sections of XML documents. XPath expressions are used for locating a set of nodes in a given XML document. Many XML technologies, like XSLT and XQuery, use XPath extensively. To use these technologies, you’ll need to understand the basics of XPpath. All samples in this section assume we are working on a XML document similar to the XML document on page 1.

Sample XPath Expressions and Output

XPath Expression	Output
/publications/book[publisher="Wrox"]/copyright	2007
/publications//book[contains(title,"XML")]/author	David Hunter ’Reilly Media, Inc Erik Ray
/publications//book[contains(title,"XML") and position()=3]/@id	_003
/publications//book[contains(title,"XML") and position()=3 ]/copyright mod 7	1

As you can see, contains and positions functions are two widely used XPath functions.

Important XPath Functions

Operate On	Function	Description
Node set	count(node-set)	Returns the number of nodes that are in the node set.
Node set	last()	Returns the position of the last node in the node set.
Numbers	ceiling(number)	Returns an integer value equal to or greater than the specified number.
Numbers	sum(node-set)	Returns the sum of the numerical values in the specified node set.
Boolean	lang(language)	Checks to see if the given language matches the language specified by the xsl:lang element.
Boolean	boolean(argument)	Converts the argument to Boolean.
String	substringafter(string1, string2)	Returns the portion of string1 that comes after the occurrence of string2 (which is a subset of string1).
String	normalizespace(string)	Returns the given string with no leading or trailing whitespaces, and removes sequences of whitespaces by replacing them with a single whitespace.
String	concat(string1,string2, stringN)	Returns a string containing the concatenation of the specified string arguments.

Using XPath in a Java Application

Document xmlDocument;
DocumentBuilderFactory dbFactory = DocumentBuilderFactory.
newInstance();
DocumentBuilder builder = dbFactory.newDocumentBuilder();
xmlDocument = builder.parse(“src/books.xml”);
XPathFactory factory = XPathFactory.newInstance();
XPath xPath = factory.newXPath();
String copyright = xPath.evaluate
         (“/publications/book[publisher= ‘Wrox’]/copyright”, xmlDocument);
System.out.println(“Copyright: “ + copyright);
NodeList nodes = (NodeList) xPath.evaluate(“//book”, xmlDocument,
XPathConstants.NODESET);
String bookid = xPath.evaluate
   (“/publications//book[contains(title,’XML’) and position()=3]/@id”,
 xmlDocument);
System.out.println(“Book ID: “ + bookid);
​