IN THIS CHAPTER

Understanding XML

Defining structure with DTD

Looking at DOM and SAX

Reading a document into memory

Navigating a document

Getting attribute and element values

In this chapter, you find out how to work with Extensible Markup Language (XML) — the best thing to happen to computing since the invention of the vacuum tube (at least, according to some overenthusiastic prognosticators).

This chapter focuses on the basics of reading an XML document into memory and extracting data from it. With the background in this chapter, you shouldn’t have much trouble studying the API documentation on your own to find out more about XML programming.

Defining XML

Most computer-industry pundits agree that XML will completely change the way you work with computers. Here are just some of the ways XML will revolutionize the world of computers:

• Unlock the vast warehouses of data that are locked up in the vaults of corporate mainframe computers
• Enable every electronic device on the planet, from the most complex supercomputers to desktop computers to cellphones to wristwatches, to communicate with one another
• Allow every computer program ever written to exchange data with every other computer program ever written
• Probably cure cancer and solve the budget deficit, too

Yawn.

So what is XML, really? Simply put, XML is a way to store and exchange information in a standardized way that’s easy to create, retrieve, and transfer between different types of computer systems or programs.

When XML is stored in a file, the file is usually given the extension .xml.

Using a DTD

An XML document can have a DTD, which spells out exactly what elements can appear in an XML document and in what order the elements can appear. DTD stands for Document Type Definition, but that won’t be on the test.

A DTD for an XML document about movies, for example, may specify that each Movie element must have Title and Price subelements and an attribute named year. It can also specify that the root element must be named Movies and consist of any number of Movie elements.

The main purpose of the DTD is to spell out the structure of an XML document so that users of the document know how to interpret it. Another, equally important use of the DTD is to validate the document to make sure that it doesn’t have any structural errors. If you create a Movies XML document that has two titles for a movie, for example, you can use the DTD to detect the error.

You can store the DTD for an XML document in the same file as the XML data, but more often, you store the DTD in a separate file. That way, you can use a DTD to govern the format of several XML documents of the same type. To indicate the name of the file that contains the DTD, you add a <!DOCTYPE> declaration to the XML document. Here’s an example:

<!DOCTYPE Movies SYSTEM "movies.dtd">

Here the XML file is identified as a Movies document, whose DTD you can find in the file movies.dtd. Add this tag near the beginning of the movies.xml file, right after the <?xml> tag.

Listing 5-2 shows a DTD file for the movies.xml file that was shown in Listing 5-1.

LISTING 5-2 A DTD File for the movies.xml File

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT Movies (Movie*)>
<!ELEMENT Movie (Title, Price)>
<!ATTLIST Movie year CDATA #REQUIRED>
<!ELEMENT Title (#PCDATA)>
<!ELEMENT Price (#PCDATA)>

Each of the ELEMENT tags in a DTD defines a type of element that can appear in the document and indicates what can appear as the content for that element type. The general form of the ELEMENT tag is this:

<!ELEMENT element (content)>

Use the rules listed in Table 5-1 to express the content.

The first ELEMENT tag in the DTD I show in Listing 5-2, for example, says that a Movies element consists of zero or more Movie elements. The second ELEMENT tag says that a Movie element consists of a Title element followed by a Price element. The third and fourth ELEMENT tags say that the Title and Price elements consist of text data.

If this notation looks vaguely familiar, that’s because it’s derived from regular expressions.

The ATTLIST tag provides the name of each attribute. Its general form is this:

<!ATTLIST element attribute type default-value>

Here’s a breakdown of this tag:

• element names the element whose tag the attribute can appear in.
• attribute provides the name of the attribute.
• type specifies what can appear as the attribute’s value. The type can be any of the items listed in Table 5-2.
• default provides a default value and indicates whether the attribute is required or optional. default can be any of the items listed in Table 5-3.

Here’s the ATTLIST tag declaration from movies.dtd:

<!ATTLIST Movie year CDATA #REQUIRED>

This declaration indicates that the attribute goes with the Movie element, is named year, can be any kind of data, and is required.

Here’s an ATTLIST tag that specifies a list of possible values along with a default:

<!ATTLIST Movie genre (SciFi|Action|Comedy|Drama) Comedy>

This form of the ATTLIST tag lets you create an attribute that’s similar to an enumeration, with a list of acceptable values.

Processing XML in Two Ways: DOM and SAX

In general, you can use either of two approaches to process XML documents in a Java program:

• DOM: Stands for Document Object Model. The basic idea of DOM is that you read an entire XML document from a file into memory, where the document is stored as a collection of objects that are structured as a tree. Then you can process the elements of the tree (called nodes) however you want. If you change any of the nodes, you can write the document back to a file.
• SAX: Stands for Simple API for XML. SAX is a read-only technique for processing XML that lets you read the elements of an XML document from a file and react to them as they come. Because SAX doesn’t require you to store an entire XML document in memory at one time, it’s often used for very large XML documents.

In this section, I cover the basics of using DOM to retrieve information from an XML document. DOM represents an XML document in memory as a tree of Node objects. Figure 5-1 shows a simplified DOM tree for an XML document that has two Movie elements. Notice that the root element (Movies) is a node, each Movie element is a node, and each Title and Price element is a node. In addition, text values are stored as child nodes of the elements they belong to. Thus, the Title and Price elements each have a child node that contains the text for these elements.

Reading a DOM Document

Before you can process a DOM document, you have to read the document into memory from an XML file. You’d think that this would be a fairly straightforward proposition, but unfortunately, it involves some pretty strange incantations. Rather than go through all the classes and methods you have to use, I just look at the finished code for a complete method that accepts a String containing a filename as a parameter and returns a document object as its return value. Along the way, you find out what each class and method does.

Here’s a method that reads an XML file into a DOM document:

private static Document getDocument(String name)
{
try
{
DocumentBuilderFactory factory =
DocumentBuilderFactory.newInstance();
factory.setIgnoringComments(true);
factory.setIgnoringElementContentWhitespace(true);
factory.setValidating(true);
DocumentBuilder builder =
factory.newDocumentBuilder();
return builder.parse(new InputSource(name));
}
catch (Exception e)
{
System.out.println(e.getMessage());
}
return null;
}

Reading DOM Nodes

After you have a DOM document in memory, you can easily retrieve data from the document’s nodes. The DOM API is based on interfaces rather than classes, so each node of the DOM document is represented by an object that implements one or more DOM interfaces. The following paragraphs give you an overview of the interfaces you need to work with:

• Document: The entire document is represented by an object that implements the Document interface. The method you use most from this interface is getDocumentElement, which returns an Element object that represents the document’s root node. After you have the root node, you can navigate to other nodes in the document to get the information you’re looking for.
• Node: The Node interface represents a node in the DOM document. This interface provides methods that are common to all nodes. Table 5-4 lists the most useful of these methods. This table also lists some of the field values that the getNodeType method can return.
• Element: The Element interface represents nodes that correspond to elements in the XML document. Element extends Node, so any object that implements Element is also a Node. Table 5-5 lists some of the most useful methods of this interface.
• Text: The text content of an element isn’t contained in the element itself, but in a Text node that’s stored as a child of the element. The Text interface has a few interesting methods you may want to look up, but for most applications, you just use the getNodeValue method inherited from the Node interface to retrieve the text stored by a text node.
• NodeList: A NodeList is a collection of nodes that’s returned by methods such as the getChildNodes method of the Node interface or the getElementsByTagName of the Element interface. NodeList has just two methods: item(int i), which returns the node at the specified index, and getLength(), which returns the number of items in the list. (As with almost every other index in Java, the first node is index 0, not 1.)

Putting It All Together: A Program That Lists Movies

Now that you’ve seen the various interfaces and classes you use to get data from an XML file, Listing 5-3 shows a complete program that reads the movies.xml file (shown in Listing 5-1 earlier in this chapter) and lists the title, year, and price of each movie on the console. When you run this program, the following appears on the console:

1946: It's a Wonderful Life ($14.95)
1974: Young Frankenstein ($16.95)
1977: Star Wars ($17.95)
1987: The Princess Bride ($16.95)
1989: Glory ($14.95)
1997: The Game ($14.95)
1998: Shakespeare in Love ($19.95)
2009: Zombieland ($18.95)
2010: The Kings Speech ($17.95)
2013: Star Trek Into Darkness ($19.95)

LISTING 5-3 Reading an XML Document

import javax.xml.parsers.*; →1
import org.xml.sax.*;
import org.w3c.dom.*;
import java.text.*;
public class ListMoviesXML
{
private static NumberFormat cf =
NumberFormat.getCurrencyInstance();
public static void main(String[] args) →11
{
Document doc = getDocument("movies.xml");
Element root = doc.getDocumentElement();
Element movieElement = (Element)root.getFirstChild();
Movie m;
while (movieElement != null)
{
m = getMovie(movieElement);
String msg = Integer.toString(m.year);
msg += ": " + m.title;
msg += " (" + cf.format(m.price) + ")";
System.out.println(msg);
movieElement =
(Element)movieElement.getNextSibling();
}
}
private static Document getDocument(String name) →29
{
try
{
DocumentBuilderFactory factory =
DocumentBuilderFactory.newInstance();
factory.setIgnoringComments(true);
factory.setIgnoringElementContentWhitespace(true);
factory.setValidating(true);
DocumentBuilder builder =
factory.newDocumentBuilder();
return builder.parse(new InputSource(name));
}
catch (Exception e)
{
System.out.println(e.getMessage());
}
return null;
}
private static Movie getMovie(Element e) →49
{
// get the year attribute
String yearString = e.getAttribute("year");
int year = Integer.parseInt(yearString);
// get the Title element
Element tElement = (Element)e.getFirstChild();
String title = getTextValue(tElement).trim();
// get the Price element
Element pElement =
(Element)tElement.getNextSibling();
String pString = getTextValue(pElement).trim();
double price = Double.parseDouble(pString);
return new Movie(title, year, price);
}
private static String getTextValue(Node n) →65
{
return n.getFirstChild().getNodeValue();
}
private static class Movie →70
{
public String title;
public int year;
public double price;
public Movie(String title, int year, double price)
{
this.title = title;
this.year = year;
this.price = price;
}
}
}

Because all the code in this program appears elsewhere in this chapter, the following paragraphs just provide a simple description of what each method in this program does:

1. →1 Wow, that’s a lot of packages to import. Too bad that Java’s designers couldn’t have put all these XML classes in one big package.
2. →11 The main method starts by calling the getDocument method to get a Document object from the file movies.xml. Then it gets the root element and uses a while loop to spin through all the child elements, which you know to be Movie elements because the document was validated when it was parsed. As each Movie element is processed, it’s passed to the getMovie method, which extracts the year attribute and the title and price elements, and returns a Movie object. Then the movie is printed on the console.
3. →29 The getDocument method accepts a filename as a parameter and returns a Document object. Before it creates the DocumentBuilder object, it sets the configuration options so that comments and white space are ignored and the XML file is validated. Because the XML file is validated, you must create a DTD file (like the file in Listing 5-2 earlier in this chapter). Also, you must begin the XML file with a DOCTYPE declaration (such as <!DOCTYPE Movies SYSTEM "movies.dtd">).
4. →49 The getMovie method is passed an Element object that represents a Movie element. It extracts the year attribute, gets the text value of the title element, and parses the text value of the price element to a double. Then it uses these values to create a new Movie object, which is returned to the caller.
5. →65 The getTextValue method is simply a little helper method that gets the text content from a node. This method assumes that the node has a child node containing the text value, so you shouldn’t call this method unless you know that to be the case. (Because the XML document was validated, you do.)
6. →70 The Movie class is a private inner class that represents a single movie. It uses public fields to hold the title, year, and price data, and it provides a simple constructor that initializes these fields.