The discussion of SAX is short: simply put, you cannot modify XML with SAX. Because SAX is an event-based approach to XML data, it is only useful in parsing an XML document. The callbacks it defines are specifically designed for that purpose, and as SAX has no concept of an overall picture of an XML document, it also has no concept of changing that overall picture. It is this very fact that has caused much of the popularity of DOM; until recently, DOM has been the only means of creating XML from Java without having to write out XML directly using streams.

The Document Object Model does provide a means of creating and modifying XML from Java. However, it takes a more rigid view of the tree structure of an XML document. First, it considers everything in the DOM tree a Node (remember our discussions in Chapter 7)? Because these Nodes are all part of a tree, it is necessary to create a Node with an association to a particular DOM tree, represented by a DOM Document object. To ensure this model is adhered to, there is no facility for instantiating a DOM Node directly; instead, it is the Document interface within DOM that defines the createElement( ), createAttribute( ), and other Node creation operations. Another point to remember is that this rigid tree model considers everything in the tree a Node, including textual data. This means that there is no concept of an element’s content in DOM; instead, a DOM Element has child Nodes, some of which may be Text Nodes. This means that setting the value of an Element requires using the createTextNode( ) method to create a Text Node, and then adding that new Node to the desired parent Element. Of course, the createTextNode( ) method itself is invoked on the overall DOM Document object, to ensure the correct association with the DOM tree.

With this in mind, let’s look at building up an XML document from the data supplied by a user in the XmlRpcConfigurationServlet application.

You might be expecting us to repeat the process of finding each XML element with data and then changing the value of the textual nodes, as in our first saveConfiguration( ) method for JDOM. Although this is certainly possible (as DOM provides a setValue( ) method for textual Nodes), this is neither the easiest nor the quickest way to handle this task. Instead, we use the various createXXX( ) methods that are defined in the DOM Document interface. A method for each type of DOM Node is provided, such as createElement( ) , createTextNode( ) , and createAttribute( ) . As each of these is created, it is assigned to the Document object used to create it. This maintains an ownership between each created Node and the DOM tree they belong to.

In this way, all the needed elements and data can be created within our Java code. However, this is only half of the task; each element and its data then need to be inserted into the DOM tree and assembled into the correct hierarchy. The simplest way to insert a Node into the tree is to use the appendChild( ) method on the parent node.

In this way, we can build up the complete document starting with the root element. Finally, we can replace the old root element with the new one, completing the update of our tree.

In addition to our not needing to perform complicated searching and retrieval of elements and data, building a tree this way is often much quicker. Searches through a DOM tree, particularly when the DOM tree becomes large, can take quite a lot of processing time; creating XML from the root element up is a much faster alternative to this extensive searching. The code to perform this task is included here:

/**
 * <p>
 * This will save the current state out to the specified 
                  
 *   <code>OutputStream</code>, using DOM
 * </p>
 *
 * @throws <code>IOException</code> - when errors occur in saving.
 */
public synchronized void saveConfiguration(OutputStream out)
   throws IOException {

    String NAMESPACE_URI = "http://www.oreilly.com/catalog/javaxml/";

    // We assume the DOM Document object was loaded in
    //   parseConfiguation(  ) and is saved in a member variable called
    //   <code>doc</code>.
    Element oldRoot = doc.getDocumentElement(  );
    Element newRoot = 
        doc.createElementNS(NAMESPACE_URI, "JavaXML:xmlrpc-config");
        
    // Handle hostname
    Element hostnameNode =
        doc.createElementNS(NAMESPACE_URI, "JavaXML:hostname");
    hostnameNode.appendChild(
        doc.createTextNode(hostname));
    newRoot.appendChild(hostnameNode);
        
    // Handle port number
    Element portNumberNode =
        doc.createElementNS(NAMESPACE_URI, "JavaXML:port");
    portNumberNode.appendChild(
        doc.createTextNode(portNumber + ""));
    portNumberNode.setValue("type", "unprotected");
    newRoot.appendChild(portNumberNode);

    // Handle SAX Driver class
    Element saxDriverNode =
        doc.createElementNS(NAMESPACE_URI, "JavaXML:parserClass");
    saxDriverNode.appendChild(
        doc.createTextNode(driverClass));
    newRoot.appendChild(saxDriverNode); 
        
    Element serverNode =
        doc.createElementNS(NAMESPACE_URI, "JavaXML:xmlrpc-server");
    Element handlersNode =
        doc.createElementNS(NAMESPACE_URI, "JavaXML:handlers");

    // Handle handlers
    Enumeration handlerIDs = handlers.keys(  );
    while (handlerIDs.hasMoreElements(  )) {
      String handlerID = (String)handlerIDs.nextElement(  );
      String handlerClass = (String)handlers.get(handlerID);
          
      Element handlerIDNode =
          doc.createElementNS(NAMESPACE_URI, "JavaXML:identifier");
      handlerIDNode.appendChild(
          doc.createTextNode(handlerID));
              
      Element handlerClassNode =
          doc.createElementNS(NAMESPACE_URI, "JavaXML:class");
      handlerClassNode.appendChild(
          doc.createTextNode(handlerClass));
              
      Element handlerNode =
          doc.createElementNS(NAMESPACE_URI, "JavaXML:handler");
      handlerNode.appendChild(handlerIDNode);
      handlerNode.appendChild(handlerClassNode);
                
      handlersNode.appendChild(handlerNode);
    }
            
    serverNode.appendChild(handlersNode);               
    newRoot.appendChild(serverNode);
      
    doc.replaceChild(newRoot, oldRoot); 

    // Serialize the DOM tree       
}

We use the DOM Level 2 methods to create our XML document with namespace awareness. The createElementNS( ) method takes in the namespace URI and then the full name of the new element. The full name does include the namespace prefix; this allows the method to ensure that a namespace prefix and namespace URI are either both included, or both excluded, helping to ensure properly formed XML.

Serialization of a DOM tree is another task, like obtaining the DOM Document object, that is not outlined in the DOM specification. To achieve serialization, you need to see if your vendor provides a helper class that will handle that functionality for you. Once you have located your parser’s serializer, you typically need only to import that class and pass it an OutputStream or PrintWriter instance. Using Apache Xerces, the class needed is the org.apache.xml.serialize.XMLSerializer. We can use that class to write to the OutputStream that our saveConfiguration( ) method has supplied to it:

/**
 * <p>
 * This will save the current state out to the specified 
 *   <code>OutputStream</code>, using DOM
 * </p>
 *
 * @throws <code>IOException</code> - when errors occur in saving.
 */
public synchronized void saveConfiguration(OutputStream out)
    throws IOException {

    // Modify Document object
      
    doc.replaceChild(newRoot, oldRoot);        
        
    // Serialize the DOM tree
                  
    org.apache.xml.serialize.XMLSerializer out = 
                  
        new org.apache.xml.serialize.XMLSerializer(out, null);
                  
    out.serialize(doc);
}

The Apache XMLSerializer class has several different constructors; the one used here takes in an OutputStream and the format to use for output. We specify null to allow the default format to be used. The serialize( ) method takes as input the Document, Element, or DocumentFragment to serialize. We pass in the modified DOM tree Document, and the serialization occurs. At this point, we have emulated the functionality we created with JDOM to modify and output an XML document with user-supplied input.