7.2.1. Java Properties Files

Figure 7-3. Expected structure of properties shown in Example 7-1

While this sounds good, Java provides no means of accessing the name-value pairs in this manner; it does not give the period any special value, but instead treats it as just another character. So while you can do this:

String classpathValue = Properties.getProperty("org.enhydra.classpath");

You cannot do this:

List enhydraProperties = Properties.getProperties("org.enhydra");

You would expect (or at least I do!) that the latter would work, and provide you all the subproperties with the structure org.enhydra (org.enhydra.classpath, org.enhydra.initialargs, etc.). Unfortunately, that's not part of the Properties class. For this reason, many developers have had to write their own little wrapper methods around this object, which of course is nonstandard and a bit of a pain. Wouldn't it be nice if this information could be modeled in XML, where operations like the second example are simple? That's exactly what I want to write code to do, and I'll use JDOM to demonstrate that API.

7.2.2. Converting to XML

The only new part of this code is the Java Properties object, which I've mentioned briefly. The supplied properties filename is used in the load( ) method, and that object is delegated on to a method that will use JDOM, which I'll focus on next.

7.2.3. Creating XML with JDOM

Once the code has the properties in a (more) usable form, it's time to start using JDOM. The first task is to create a JDOM Document. For that to occur, you need to create a root element for the document, using JDOM's Element class. Since an XML document can't exist without a root element, an instance of the Element class is required as input for the Document class constructor.

    private void convertToXML(Properties props, String xmlFilename)
        throws IOException {
    
        // Create a new JDOM Document with a root element "properties"
        Element root = new Element("properties");
        Document doc = new Document(root);
        
        // Get the property names
        Enumeration propertyNames = props.propertyNames( );
        while (propertyNames.hasMoreElements( )) {
            String propertyName = (String)propertyNames.nextElement( );
            String propertyValue = props.getProperty(propertyName);
            createXMLRepresentation(root, propertyName, propertyValue);
        }        
        
        // Output document to supplied filename
        XMLOutputter outputter = new XMLOutputter("  ", true);
        FileOutputStream output = new FileOutputStream(xmlFilename);
        outputter.output(doc, output);
    }

The easiest (and logically, the first) step in moving from a property to XML is to take the name of the property and create an Element with that name. You've already seen how to do this; simply pass the name of the element to its constructor. Once the element is created, assign the value of the property as the textual content of the element. This can be done easily enough through the setText( ) method, which of course takes a String. Once the element is ready for use, it can be added as a child of the root element through the addContent( ) method. In fact, any legal JDOM construct can be passed to an element's addContent( ) method, as it is overloaded to accept these various types. These include instances of a JDOM Entity, Comment, ProcessingInstruction, and more. But I'll get to those later; for now, add the following method into your source file:

    /**
     * <p> This will convert a single property and its value to
     *  an XML element and textual value. </p>
     *
     * @param root JDOM root <code>Element</code> to add children to.
     * @param propertyName name to base element creation on.
     * @param propertyValue value to use for property.
     */
    private void createXMLRepresentation(Element root, 
                                         String propertyName,
                                         String propertyValue) {
        
        Element element = new Element(propertyName);
        element.setText(propertyValue);
        root.addContent(element);
    }

/javaxml2/build $ java javaxml2.PropsToXML \
                  /javaxml2/ch07/properties/enhydra.properties \
                  enhydraProps.xml

In about 50 lines of code, you've gone from Java properties to XML. However, this XML document isn't much better than the properties file; there is still no way to relate the org.enhydra.initialArgs property to the org.enhydra.classpath property. Our job isn't done yet.

<org>
  <xml>
    <sax>[property Value]</sax>
  </xml>
</org>

    private void createXMLRepresentation(Element root, 
                                         String propertyName,
                                         String propertyValue) {
        
        /*           
        Element element = new Element(propertyName);
        element.setText(propertyValue);
        root.addContent(element);
        */
        
        int split;
        String name = propertyName;
        Element current = root;
        Element test = null;
              
        while ((split = name.indexOf(".")) != -1) {
            String subName = name.substring(0, split);
            name = name.substring(split+1);
            
            // Check for existing element            
            if ((test = current.getChild(subName)) == null) {
                Element subElement = new Element(subName);
                current.addContent(subElement);
                current = subElement;
            } else {
                current = test;
            }
        }
        
        // When out of loop, what's left is the final element's name
        Element last = new Element(name);                        
        last.setText(propertyValue); 
        current.addContent(last);
    }

        // When out of loop, what's left is the final element's name
        Element last = new Element(name);                        
        /* last.setText(propertyValue);  */
        Attribute attribute = new Attribute("value", propertyValue);
        current.setAttribute(attribute);
        current.addContent(last);

        // When out of loop, what's left is the final element's name        
        Element last = new Element(name);                        
        /* last.setText(propertyValue); */
        last.setAttribute("value", propertyValue);
        current.addContent(last);

Each property value is now an attribute of the innermost element. Notice that JDOM converts the quotation marks within the attribute values, which are disallowed, to entity references so the document as output is well-formed. However, this makes the output a little less clean, so you may want to switch your code back to using textual data within elements, rather than attributes.

7.2.4. Outputting XML with JDOM

    private void convertToXML(Properties props, String xmlFilename)
        throws IOException {
    
        // Create a new JDOM Document with a root element "properties"
        Element root = new Element("properties");
        Document doc = new Document(root);
        
        // Get the property names
        Enumeration propertyNames = props.propertyNames( );
        while (propertyNames.hasMoreElements( )) {
            String propertyName = (String)propertyNames.nextElement( );
            String propertyValue = props.getProperty(propertyName);
            createXMLRepresentation(root, propertyName, propertyValue);
        }        
        
        // Output document to supplied filename
        XMLOutputter outputter = new XMLOutputter("  ", true);
        FileOutputStream output = new FileOutputStream(xmlFilename);
        outputter.output(doc, output);
    }

public XMLOutputter( );

public XMLOutputter(String indent);

public XMLOutputter(String indent, boolean newlines);

public XMLOutputter(String indent, boolean newlines, String encoding);

public XMLOutputter(XMLOutputter that);

Most of these are self-explanatory. The indent parameter allows specification of how many spaces to use for indentation; I used two spaces (" ") in the sample code. The boolean value for newlines determines if line breaks are used (this was on in the sample). If needed, an encoding parameter can be specified, which becomes the value for encoding in the XML declaration:

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

// Create an outputter with 4 space indentation and new lines
XMLOutputter outputter = new XMLOutputter("    ", true);

// Output different JDOM constructs
outputter.output(myDocument, myOutputStream);
outputter.output(myElement, myWriter);
outputter.output(myComment, myOutputStream);
// etc...