Creating an XML File

Before exploring XOM, you should learn some things about XML and how it stores data. XML data turns up in countless places—it can be stored to a file, transmitted over an Internet network, and held in a program's memory.

As XML became popular, Sun Microsystems took note of its usefulness by supporting the format. Several classes in the Java 2 class library can read and write XML, including the Properties class in the java.util package, which was covered in the previous hour, "Reading and Writing Files."

A Properties object can be stored as XML rather than in the name=value format covered in the preceding hour.

After the object has been filled with configuration properties, its storeToXML() method saves it to an XML file. This method takes two arguments:

• A FileOutputStream over which the file should be saved

• A comment, which can be the empty string "" if the data requires no comment

This hour's first project is a simple application, PropertyFileCreator, that stores configuration properties in XML format. Fire up your favorite programming editor and enter the text of Listing 21.1, saving the result as PropertyFileCreator.java.

Listing 21.1. The Full Text of PropertyFileCreator.java

 1: import java.io.*;

 2: import java.util.*;

 3:

 4: public class PropertyFileCreator {

 5:     public PropertyFileCreator() {

 6:         Properties prop = new Properties();

 7:         prop.setProperty("username", "rcade");

 8:         prop.setProperty("browser", "Mozilla Firefox");

 9:         prop.setProperty("showEmail", "no");

10:         try {

11:             File propFile = new File("properties.xml");

12:             FileOutputStream propStream = new FileOutputStream(propFile);

13:             Date now = new Date();

14:             prop.storeToXML(propStream, "Created on " + now);

15:         } catch (IOException exception) {

16:             System.out.println("Error: " + exception.getMessage());

17:         }

18:     }

19:

20:     public static void main(String[] arguments) {

21:         PropertyFileCreator pfc = new PropertyFileCreator();

22:     }

23: }

Compile the application, which creates a properties file with three settings: the username "rcade", browser "Mozilla Firefox", and showEmail "no".

If the properties had been saved in the other format, it would look like this:

#Created on Sun Jul 10 21:18:33 EDT 2005

# Sun Jul 10 21:18:33 EDT 2005

showEmail=no

browser=Mozilla Firefox

username=rcade

When you run the application, it creates the XML file properties.xml, which is presented in Listing 21.2.

Listing 21.2. The Full Text of properties.xml

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

 2: <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">

 3: <properties>

 4: <comment>Created on Sun Jul 10 21:18:33 EDT 2005</comment>

 5: <entry key="showEmail">no</entry>

 6: <entry key="browser">Mozilla Firefox</entry>

 7: <entry key="username">rcade</entry>

 8: </properties>

XML organizes data in a self-documenting manner, making it possible to understand a great deal about the data simply by looking at it.

As you glance over Listing 21.2, you can tell pretty quickly how it stored the configuration properties. The ?xml and !DOCTYPE tags may be tough to follow, but the rest of the file should be simple to grok.

By the way The term grok, which means to understand something confidently enough to brag about it, was borrowed from Robert Heinlein's science fiction novel Stranger in a Strange Land, where it was a Martian word that meant "to be one with." With terms like grok and instances and ternary operators, you're learning a second language as you learn Java, which will be a real help as you work further with fellow programmers. I call it Jargonese.

Data in an XML file is surrounded by tags that look a lot like HTML, the markup language employed on the World Wide Web.

Start tags begin with a "<" character followed by the name of an element and a ">" character, such as <properties> on Line 3 of Listing 21.2.

End tags begin with "<" followed by the same element name and the "/>" characters, such as </properties> on Line 8.

Everything nested within a start tag and end tag is considered to be the element's value.

XML data must have a single root element that encloses all of its data. In Listing 21.2, the root is the properties element defined in Lines 3–18.

An element may contain text, a child element, or multiple child elements. The properties element holds four children: a comment element and three enTRy elements.

Here's the comment element:

<comment>Created on Sun Jul 10 21:18:33 EDT 2005</comment>

This element has the value of the text it encloses: "Created on Sun Jul 10 21:18:33 EDT 2005."

An XML element also can have one or more attributes, which are defined inside its start tag as name="value" pairs. Attributes must be separated by spaces. They provide supplemental information about the element.

Each enTRy element has an attribute and a value:

<entry key="showEmail">no</entry>

This element has the value "no" and a key attribute with the value "showEmail".

One kind of XML element isn't present in Listing 21.2—an element defined entirely as a single tag. These elements begin with the "<" character, followed by the element name and the "/>" characters.

For instance, this element could be present as a child of the properties element:

<inactive/>

Although XML has been described as a format and compared to HTML, it's not actually a language itself. Instead, XML describes how to create data formats specific to the tasks you want to accomplish with a computer program. XML formats are called dialects.

The XML dialect created by Java's Properties class is an example of this. Sun has developed this format for the representation of software configuration settings.

Data that follows the rules of XML formatting is described as well-formed. Software that reads or writes XML must accept well-formed data.

Data also can follow a more meticulous standard called validity. A valid XML file contains the right elements in the right places, requiring some means of defining what the valid elements are.