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.

Several classes in the Java class library can read and write XML, including the Properties class in the java.util package, which was covered in Hour 20, “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 NetBeans, enter the text from Listing 21.1 in a new empty Java file named PropertyFileCreator, and save the file.

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: }

When you run the application, it 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 Wed Jun 15 20:56:33 EDT 2011
# Thu Wed Jun 15 20:56:33 EDT 2011
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 Wed Jun 15 20:56:33 EDT 2011</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 might be tough to follow, but the rest of the file should be reasonably simple.

Data in an XML file is surrounded by tags that look a lot like HTML, the markup language employed on the 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 its data. In Listing 21.2, the root is the properties element defined in Lines 3–8.

An element might 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 Wed Jun 15 20:56:33 EDT 2011</comment>

This element has the value of the text it encloses: “Created on Wed Jun 15 20:56:33 EDT 2011.”

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. Oracle 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 the valid elements.