Chapter 2. XML

1.  Property files have a single flat hierarchy. You can often see work around as:

title.fontname=Helvetica
title.fontsize=36
body.fontname=Times Roman
body.fontsize=12

 

2.  Another shortcoming of the property file format is the requirement that keys must be unique. To store a sequence of values, you need another workaround:

menu.item.1=Times Roman
menu.item.2=Helvetica
menu.item.3=Goudy Old Style

 

3.  The XML format allows you to express the hierarchy and record repeated elements without contortions. You can find a very nice version of the XML standard, with annotations: http://www.xml.com/axml/axml.html

 

4.  Even though XML and HTML have common roots(SGML), there are important differences between the two:

    1)  Unlike HTML, XML is case-sensitive. For example, <H1> and <h1> are different XML tags.

    2)  In HTML, you can omit end tags, such as </p> or</li>, if it is clear from the context where a paragraph or list item ends. In XML, you can never omit an end tag.

    3)  In XML, elements that have a single tag without a matching end tag must end in a /, as in <img src="coffeecup.png"/> That way, the parser knows not to look for a </img> tag.

    4)  In XML, attribute values must be enclosed in quotation marks. In HTML, quotation marks are optional. For example, <applet code="MyApplet.class" width=300 height=300> is legal HTML but not legal XML. In XML, you have to use quotation marks: width="300".

    5)  In HTML, you can have attribute names without values, such as <input type="radio" name="language" value="Java" checked>. In XML, all attributes must have values, such as checked="true" or checked="checked".

 

5.  An XML document should start with a header such as

<?xml version="1.0"?>

or

<?xml version="1.0" encoding="UTF-8"?>

Strictly speaking, a header is optional, but it is highly recommended.

 

6.  The header can be followed by a document type definition (DTD):

 

<!DOCTYPE web-app PUBLIC
   "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
   "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

 

 

DTDs are an important mechanism to ensure the correctness of a document, but they are not required.

 

7.  The body of the XML document contains the root element, which can contain other elements. An element can contain child elements, text, or both.

 

8.  XML elements can contain attributes. There is some disagreement among XML designers about when to use elements and when to use attributes. A commonly used rule of thumb is that attributes should be used only to modify the interpretation of a value, not to specify values. If you find yourself engaged in metaphysical discussions about whether a particular setting is a modification of the interpretation of a value or not, just say “no” to attributes and use elements throughout. Many useful XML documents don’t use attributes at all. In HTML, the rule for attribute usage is simple: If it isn’t displayed on the web page, it’s an attribute.

 

9.  Here are a few other markup instructions that you might encounter:

    1)  Character references have the form &#decimalValueOfUnicode; or &#xhexValueOfUnicode;. For example, the character é can be denoted with either of the following: &#233; &#xE9;

    2)  Entity references have the form &name;. The entity references &lt; &gt; &amp; &quot; &apos; &nbsp; have predefined meanings: the less-than, greater-than, ampersand, quotation mark, apostrophe and whitespace characters. You can define other entity references in a DTD.

    3)  CDATA sections are delimited by <![CDATA[ and ]]>. They are a special form of character data. You can use them to include strings that contain characters such as < > & without having them interpreted as markup, for example: <![CDATA[< & > are my favorite delimiters]]> 

CDATA sections cannot contain the string ]]>. 

    4)  Processing instructions are instructions for applications that process XML documents. They are delimited by <? and ?>, for example, every XML document starts with a processing instruction

<?xml version="1.0"?>

    5)  Comments are delimited by <!-- and -->, for example <!-- This is a comment. -->

Comments should not contain the string --. Comments should only be information for human readers. They should never contain hidden commands; use processing instructions for commands.

 

10.  An XML parser is a program that reads a file, confirms that the file has the correct format, breaks it up into the constituent elements, and lets a programmer access those elements. The Java library supplies two kinds of XML parsers:

    1)  Tree parsers, such as the Document Object Model (DOM) parser, that read an XML document into a tree structure.

    2)  Streaming parsers, such as the Simple API for XML (SAX) parser, that generate events as they read an XML document.

The DOM parser is easier to use for most purposes. You may consider a streaming parser if you process very long documents whose tree structures would use up a lot of memory, or if you are only interested in a few elements and don’t care about their context. 

 

11.  The DOM parser interface is standardized by the World Wide Web Consortium (W3C). The org.w3c.dom package contains the definitions of interface types such as Document and Element. Different suppliers have written DOM parsers whose classes implement these interfaces. The Java API for XML Processing (JAXP) library actually makes it possible to plug in any of these parsers. But the JDK also comes with a DOM parser.

 

12.  To read an XML document from a file:

 

DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
DocumentBuilder builder = factory.newDocumentBuilder();
File f = . . .
Document doc = builder.parse(f);

 

 

Alternatively, you can use a URL:

 

URL u = . . .
Document doc = builder.parse(u);

 

 

You can even specify an arbitrary input stream:

 

InputStream in = . . .
Document doc = builder.parse(in);

 

 

If you use an input stream as an input source, the parser will not be able to locate other files that are referenced relative to the location of the document, such as a DTD in the same directory. You can install an “entity resolver” to overcome that problem.

 

13.  The Document object is an in-memory representation of the tree structure of the XML document. It is composed of objects whose classes implement the Node interface and its various subinterfaces:

  

14.  Start analyzing the contents of a document by calling the Document.getDocumentElement method. It returns the root element. The Element.getTagName method returns the tag name of an element.

 

15.  To get the element’s children (which may be subelements, text, comments, or other nodes), use the getChildNodes method. That method returns a collection of type NodeList. The NodeList.item method gets the item with a given index, and the NodeList .getLength method gives the total count of the items.

 

16. Be careful when analyzing the children. The following document:

 

<font>
   <name>Helvetica</name>
   <size>36</size>
</font>

 

 

will be parsed to the following structure:

you can do even better if your document has a DTD. Then the parser knows which elements don’t have text nodes as children, and it can suppress the whitespace for you.

 

17.  Those text strings are themselves contained in child nodes of type Text. If you know that these Text nodes are the only children, so you can use the getFirstChild method without having to traverse another NodeList. Then, use the getData method to retrieve the string stored in the Text node. It is a good idea to call trim on the return value of the getData method. If the author of an XML file puts the beginning and the ending tags on separate lines then the parser includes all line breaks and spaces in the text node data. Calling the trim method removes the whitespace surrounding the actual data.

 

18.  You can also get the last child with the getLastChild method, and the next sibling of a node with getNextSibling.

 

19.  To enumerate the attributes of a node, call the getAttributes method. It returns a NamedNodeMap object that contains Node objects describing the attributes. You can traverse the nodes in a NamedNodeMap in the same way as a NodeList. Then, call the getNodeName and getNodeValue methods to get the attribute names and values. Alternatively, if you know the name of an attribute, you can retrieve the corresponding value directly by Element.getAttribute.

 

20.  One of the major benefits of an XML parser is that it can automatically verify that a document has the correct structure. Then, parsing becomes much simpler.

 

21.  To specify the document structure, you can supply a DTD or an XML Schema definition. A DTD or schema contains rules that explain how a document should be formed, by specifying the legal child elements and attributes for each element. XML Schema can express more sophisticated validation conditions than can DTDs. Unlike the DTD syntax, the XML Schema syntax uses XML, which is a benefit if you need to process schema files. Some XML users are so annoyed by the complexity of XML Schema that they use alternative validation languages. The most common choice is Relax NG (www.relaxng.org).

 

22.  You can include a DTD inline in an XML document like:

 

<?xml version="1.0"?>
<!DOCTYPE configuration [
   <!ELEMENT configuration . . .>
   more rules
   . . .
]>
<configuration>
    . . .
</configuration> 

 

 

The document type must match the name of the root element, such as configuration in above example.

 

23.  The SYSTEM declaration can be used to store the DTD externally:

 

<!DOCTYPE configuration SYSTEM "config.dtd">

 or

 

 

<!DOCTYPE configuration SYSTEM "http://myserver.com/config.dtd">

 

 

24.  DTD also provides the mechanism for identifying well-known DTDs:

<!DOCTYPE web-app
  PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
  "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

 

If an XML processor knows how to locate the DTD with the PUBLIC identifier, it need not go to the URL.

 

25.  If you use a DOM parser and would like to support a PUBLIC identifier, call the setEntityResolver method of the DocumentBuilder class to install an object of a class that implements the EntityResolver interface. That interface has a single method, resolveEntity：

class MyEntityResolver implements EntityResolver
{
   public InputSource resolveEntity(String publicID,
      String systemID)
   {
      if (publicID.equals(a known ID))
         return new InputSource(DTD data);
      else
          return null; // use default behavior
   }
}

You can construct the input source from an InputStream, a Reader, or a string.

 

26. The ELEMENT rule specifies what children an element can have. Specify a regular expression, made up of the components shown in below table:

 

For example, the following set of rules state that a font is described by a name followed by a size, each of which contain text:

<!ELEMENT font (name,size)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT size (#PCDATA)>

 

27.  Whenever an element can contain text, there are only two valid cases. Either the element contains nothing but text, or the element contains any combination of text and tags in any order. This restriction simplifies the job of the XML parser when parsing mixed content (a mixture of tags and text). Since you lose some control by allowing mixed content, it is best to design DTDs so that all elements contain either other elements or nothing but text.

 

28.  You can also specify rules to describe the legal attributes of elements. The general syntax is

<!ATTLIST element attribute type default>

The following table shows the legal attribute types:

 

The following table shows the syntax for the defaults:

 

An NMTOKEN (or name token) is similar to CDATA, but most nonalphanumeric characters and internal whitespace are disallowed, and the parser removes leading and trailing whitespace. NMTOKENS is a whitespace-separated list of name tokens. An ID is a name token that must be unique in the document—the parser checks the uniqueness. An IDREF is a reference to an ID that exists in the same document, which the parser also checks. IDREFS is a whitespace-separated list of ID references. An ENTITY attribute value refers to an “unparsed external entity.” That is a holdover from SGML that is rarely used in practice. The annotated XML specification at www.xml.com/axml/axml.html has an example.

 

29.  A DTD can also define entities, or abbreviations that are replaced during parsing:

<!ENTITY back.label "Back">

Elsewhere, text can contain an entity reference, for example:

<menuitem label="&back.label;"/>

The parser replaces the entity reference with the replacement string.

 

30.  You can tell the document builder factory to turn on validation by factory.setValidating(true); All builders produced by this factory validate their input against a DTD.

 

31.  The most useful benefit of validation is ignoring whitespace in element content.

 

32.  You should install an error handler whenever you use validation. Supply an object that implements the ErrorHandler interface. That interface has three methods:

void warning(SAXParseException exception)
void error(SAXParseException exception)
void fatalError(SAXParseException exception)

 

Install the error handler with the setErrorHandler method of the DocumentBuilder class.

 

33.  For more information of XML Schema: www.w3.org/TR/xmlschema-0.

 

34.  To reference a XML Schema file in a document, add attributes to the root element:

<?xml version="1.0"?>
<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="config.xsd">
   . . .
</configuration>

 

If your document uses namespaces, the syntax is a bit more complex.

 

35.  Enclose element and type definitions of your schema inside an xsd:schema element (We use the prefix xsd: to denote the XML Schema Definition namespace. ) :

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   . . .
</xsd:schema>

 

 

36.  When you define an element, you specify its type:

<xsd:element name="name" type="xsd:string"/>

 The type constrains the element content.

 

37.  Some simple types are built into XML Schema, including

xsd:string
xsd:int
xsd:boolean

 

38.  You can define your own simple types:

<xsd:simpleType name="StyleType">
   <xsd:restriction base="xsd:string">
      <xsd:enumeration value="PLAIN" />
      <xsd:enumeration value="BOLD" />
      <xsd:enumeration value="ITALIC" />
      <xsd:enumeration value="BOLD_ITALIC" />
   </xsd:restriction>
</xsd:simpleType>

 

39.  You can compose types into complex types:

<xsd:complexType name="FontType">
   <xsd:sequence>
      <xsd:element ref="name"/>
      <xsd:element ref="size"/>
      <xsd:element ref="style"/>
   </xsd:sequence>
</xsd:complexType>

 

A FontType is a sequence of name, size, and style elements. In this type definition, we use the ref  attribute and refer to definitions that are located elsewhere in the schema.

 

40.  You can also nest definitions:

<xsd:complexType name="FontType">
   <xsd:sequence>
      <xsd:element name="name" type="xsd:string"/>
      <xsd:element name="size" type="xsd:int"/>
      <xsd:element name="style" type="StyleType">
         <xsd:simpleType>
            <xsd:restriction base="xsd:string">
               <xsd:enumeration value="PLAIN" />
               <xsd:enumeration value="BOLD" />
               <xsd:enumeration value="ITALIC" />
               <xsd:enumeration value="BOLD_ITALIC" />
            </xsd:restriction>
         </xsd:simpleType>
      </xsd:element>
   </xsd:sequence>
</xsd:complexType>

 

41.  The xsd:sequence construct is the equivalent of the concatenation notation in DTDs. The xsd:choice construct is the equivalent of the | operator.

 

42.  To allow repeated elements, use the minoccurs and maxoccurs attributes:

<xsd:element name="item" type=". . ." minoccurs="0" maxoccurs="unbounded">

 

43.  To specify attributes:

<xsd:element name="size">
   <xsd:complexType>
      . . .
      <xsd:attribute name="unit" type="xsd:string" use="optional" default="cm"/>
   </xsd:complexType>
</xsd:element>

This is the equivalent of the DTD statement

<!ATTLIST size unit CDATA #IMPLIED "cm">

 

44.  Parsing an XML file with a schema is similar to parsing a file with a DTD, but with three differences:

    1)  You need to turn on support for namespaces, even if you don’t use them in your XML files: factory.setNamespaceAware(true);

    2)  You need to prepare the factory for handling schemas, with the following magic incantation:

final String JAXP_SCHEMA_LANGUAGE = "http://java.sun.com/xml/jaxp/properties/schemaLanguage";
final String W3C_XML_SCHEMA = "http://www.w3.org/2001/XMLSchema";
factory.setAttribute(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA);

    3)  The parser does not discard element content whitespace. This is a definite annoyance, and there is disagreement whether or not it is an actual bug.

 

45.  The XPath language makes it simple to access tree nodes.

 

46.  An XPath can describe a set of nodes in an XML document: /gridbag/row describes the set of all row elements that are children of the gridbag root element. You can select a particular element with the [] operator: /gridbag/row[1] is the first row. (The index values start at 1.)

 

47.  Use the @ operator to get attribute values. The XPath expression /gridbag/row[1]/cell[1]/@anchor describes the anchor attribute of the first cell in the first row. The XPath expression /gridbag/row/cell/@anchor describes all anchor attribute nodes of cell elements within row elements that are children of the gridbag root node.

 

48.  For more information about XPath, see the specification at www.w3c.org/TR/xpath or the nifty online tutorial at www.zvon.org/xxl/XPathTutorial/General/examples.html.

 

49.  To evaluate XPath expressions in Java:

XPathFactory xpfactory = XPathFactory.newInstance();
XPath path = xpfactory.newXPath();
String username = path.evaluate("/configuration/database/username", doc);

You can use the same XPath object to evaluate multiple expressions.

 

50.  If an XPath expression yields a node set, make a call such as the following:

NodeList nodes = (NodeList) path.evaluate("/gridbag/row", doc, XPathConstants.NODESET);

If the result is a single node, use XPathConstants.NODE instead:

Node node = (Node) path.evaluate("/gridbag/row[1]", doc, XPathConstants.NODE);

If the result is a number, use XPathConstants.NUMBER:

int count = ((Number) path.evaluate("count(/gridbag/row)", doc, XPathConstants.NUMBER)).intValue();

 

51.  You don’t have to start the search at the document root; you can start at any node or node list.

 

52.  A namespace is identified by a Uniform Resource Identifier (URI). The HTTP URL form is the most common. Note that the URL is just used as an identifier string, not as a locator for a document. There need not be any document at a namespace URL—the XML parser doesn’t attempt to find anything at that location. However, as a help to programmers who encounter a possibly unfamiliar namespace, it is customary to place a document explaining the purpose of the namespace at the URL location.

 

53.  If you need only a single namespace or if the namespaces are naturally nested. You can use namespaces as following:

<element xmlns="namespaceURI1">
  <child xmlns="namespaceURI2">
     grandchildren
  </child>
  more children
</element>

Then the first child and the grandchildren are part of the second namespace.

 

54.  You can have a prefix for a namespace—a short identifier that you choose for a particular document:

< xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <xsd:element name="gridbag" type="GridBagType"/>
   . . .
</xsd:schema>

 

The attribute xmlns:prefix="namespaceURI" defines a namespace and a prefix. In above example, xsd:schema really means schema in the namespace http://www.w3.org/2001/XMLSchema.

 

55.  Only child elements inherit the namespace of their parent. Attributes without an explicit prefix are never part of a namespace.

 

56.  By default, the Sun DOM parser is not namespace-aware. To turn on namespace handling, call the setNamespaceAware method of the DocumentBuilderFactory. Then all builders the factory produces support namespaces.

 

57.  Each parsed node has three properties:

    1)  The qualified name, with a prefix, returned by getNodeName, getTagName, and so on

    2)  The namespace URI, returned by the getNamespaceURI method

    3)  The local name, without a prefix or a namespace, returned by the getLocalName method.

If namespace awareness is turned off, getNamespaceURI and getLocalName return null.

 

58.  The SAX parser uses event callbacks, and the StAX (added to Java SE 6) parser provides an iterator through the parsing events. The latter is usually a bit more convenient.

 

59.  The SAX parser reports events as it parses the components of the XML input, but it does not store the document in any way—it is up to the event handlers to build a data structure. In fact, the DOM parser is built on top of the SAX parser. It builds the DOM tree as it receives the parser events.

 

60.  The ContentHandler interface defines several callback methods that the parser executes as it parses the document:

    1)  startElement and endElement are called each time a start tag or end tag is encountered.

    2)  characters is called whenever character data are encountered.

    3)  startDocument and endDocument are called once each, at the start and the end of the document.

 

61.  For example, when parsing the fragment:

<font>
   <name>Helvetica</name>
   <size units="pt">36</size>
</font>

the parser makes the following callbacks:

    1)  startElement, element name: font

    2)  startElement, element name: name

    3)  characters, content: Helvetica

    4)  endElement, element name: name

    5)  startElement, element name: size, attributes: units="pt"

    6)  characters, content: 36

    7)  endElement, element name: size

    8)  endElement, element name: font

 

62.  Here is how you get a SAX parser to parse an XML document:

SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser parser = factory.newSAXParser();
parser.parse(source, handler);

Here, source can be a file, URL string, or input stream. The handler belongs to a subclass of DefaultHandler. The DefaultHandler class defines do-nothing methods for the four interfaces: ContentHandler, DTDHandler, EntityResolver and ErrorHandler.

 

63.  The startElement method has three parameters that describe the element name:

public void startElement(String namespaceURI, String lname, String qname, Attributes attrs)throws SAXException;

The qname parameter reports the qualified name of the form prefix:localname. If namespace processing is turned on, then the namespaceURI and lname parameters provide the namespace and local (unqualified) name. As with the DOM parser, namespace processing is turned off by default. To activate namespace processing, call the setNamespaceAware method of the factory class.

 

64.  If you don’t need to validate the document with DTD, just call

factory.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false);

 

65.  The StAX parser is a “pull parser”, you simply iterate through the events, using this basic loop:

InputStream in = url.openStream();
XMLInputFactory factory = XMLInputFactory.newInstance();
XMLStreamReader parser = factory.createXMLStreamReader(in);
while (parser.hasNext())
{
   int event = parser.next();
   Call parser methods to obtain event details
}

The event returned is one of the XMLStreamConstants. To analyze the attribute values, call the appropriate methods of the XMLStreamReader class:

String units = parser.getAttributeValue(null, "units");

 gets the units attribute of the current element.

 

66.  By default, namespace processing is enabled. You can deactivate it by 

factory.setProperty(XMLInputFactory.IS_NAMESPACE_AWARE, false);

 

67.  To build a DOM tree:

Document doc = builder.newDocument();

To create new element:

Element rootElement = doc.createElement(rootName);
Element childElement = doc.createElement(childName);

To construct text nodes:

Text textNode = doc.createTextNode(textContents);

To add the root element to the document, and add the child nodes to their parents:

doc.appendChild(rootElement);
rootElement.appendChild(childElement);
childElement.appendChild(textNode);

To set attribute for an element:

rootElement.setAttribute(name, value);

 

68.  To use namespaces when constructing DOM tree:

DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
factory.setNamespaceAware(true);
builder = factory.newDocumentBuilder();

To create any nodes with namespace:

String namespace = "http://www.w3.org/2000/svg";
Element rootElement = doc.createElementNS(namespace, "svg");

If your node has a qualified name, with a namespace prefix, then any necessary xmlns-prefixed attributes are created automatically. For example,

Element svgElement = doc.createElementNS(namespace, "svg:svg")

It turns into:

<svg:svg xmlns:svg="http://www.w3.org/2000/svg">

If you need to set element attributes whose names are in a namespace:

rootElement.setAttributeNS(namespace, qualifiedName, value);

 

69.  To output the DOM tree to a file:

// construct the do-nothing transformation
Transformer t = TransformerFactory.newInstance().newTransformer();
// set output properties to get a DOCTYPE node
t.setOutputProperty(OutputKeys.DOCTYPE_SYSTEM, systemIdentifier);
t.setOutputProperty(OutputKeys.DOCTYPE_PUBLIC, publicIdentifier);
// set indentation
t.setOutputProperty(OutputKeys.INDENT, "yes");
t.setOutputProperty(OutputKeys.METHOD, "xml");
t.setOutputProperty("{http://xml.apache.org/xslt}indent-amount", "2");
// apply the do-nothing transformation and send the output to a file
t.transform(new DOMSource(doc), new StreamResult(new FileOutputStream(file)));

 

70.  You can use LSSerializer to output DOM tree to a String:

DOMImplementation impl = doc.getImplementation();
DOMImplementationLS implLS = (DOMImplementationLS) impl.getFeature("LS", "3.0");
LSSerializer ser = implLS.createLSSerializer();
//If you want spaces and line breaks
ser.getDomConfig().setParameter("format-pretty-print", true);
String str = ser.writeToString(doc);

If you want to write the output directly to a file:

LSOutput out = implLS.createLSOutput();
out.setEncoding("UTF-8");
out.setByteStream(Files.newOutputStream(path));
ser.write(doc, out);

 

71.  The StAX API lets you write an XML tree directly:

XMLOutputFactory factory = XMLOutputFactory.newInstance();
// Construct anXMLStreamWriter from an OutputStream
XMLStreamWriter writer = factory.createXMLStreamWriter(out);
writer.writeStartDocument()
writer.writeStartElement(rootName);
//add attribute
writer.writeAttribute(attName, attValue);
//add child elements by calling writeStartElement again
writer.writeStartElement(child1Name);
// write characters
writer.writeCharacters(text);
// close the current element
writer.writeEndElement();
//write an element without children such as <img. . ./>
writer.writeEmptyElement(child2Name);
// This call closes any open elements.
writer.writeEndDocument();

 

72.  The XSL Transformations (XSLT) mechanism allows you to specify rules for transforming XML documents into other formats. XSLT is commonly used to translate from one machine-readable XML format to another, or to translate XML into a presentation format for human consumption. An XSLT processor reads an XML document and the stylesheet and produces the desired output:

 

73.  You can find more information about XSLT in the book Essential XML by Don Box et al. The XSLT specification is available at www.w3.org/TR/xslt.