Setting DOM Parser Features

The idea of a feature for a DOM parser is the same as with SAX – a parser option that can be either on or off. The DocumentBuilderFactory object has the following methods for setting DOM parser features:

As you see, by default the parser that is produced is neither namespace aware nor validating. We should at least set these two features before creating our parser. This is quite simple:

DocumentBuilderFactory builderFactory = DocumentBuilderFactory.newInstance();
builderFactory.setNamespaceAware(true);
builderFactory.setValidating(true);

If you add the shaded statements to the example, the newDocumentBuilder() method for the factory object should now return a validating and namespace aware parser. With a validating parser, we should define an ErrorHandler object that will deal with parsing errors. You identify the ErrorHandler object to the parser by calling the setErrorHandler() method for the DocumentBuilder object:

builder.setErrorHandler(handler);

Here handler refers to an object that implements the three methods declared in the org.xml.sax.ErrorHandler interface. We discussed these in the previous chapter in the context of SAX parser error handling, and the same applies here. If you do create a validating parser, you should implement and register an ErrorHandler object. Otherwise the parser may not work properly.

The factory object has methods to check the status of parser features corresponding to each of the setXXX() methods above. The checking methods all have corresponding names of the form isXXX(), so to check whether a parser will be namespace aware, you call the isNamespaceAware() method. Each method returns true if the parser to be created will have the feature set, and false otherwise.

Parsing a Document

Once you have created a DocumentBuilder object, you just call its parse() method with a document source as an argument to parse a document. The parse() method will return a reference of type Document to a object that encapsulates the entire XML document. The Document interface is defined in the org.w3c.dom package.

There are five overloaded versions of the parse() method that provide various options for you to identify the source of the XML document. They all return a reference to a Document object:

All five versions of the parse method can throw three types of exception. An exception of type IllegalArgumentException will be thrown if you pass null to the method for the parameter that identifies the document source. The method will throw an exception of type IOException if any I/O error occurs, and of type SAXException in the event of a parsing error. Both these last exceptions must be caught. Note that it is a SAXException that can be thrown here. Exceptions of type DOMException only arise when you are navigating the tree for a Document object.

You could parse() a document using the DocumentBuilder object, builder, like this:

File xmlFile = new File("D:/Beg Java Stuff/Address.xml"); 
Document xmlDoc = null;
 try {
   xmlDoc = builder.parse(xmlFile);
 }
   catch(SAXException e) {
   e.printStackTrace();
   System.exit(1);
 }
   catch(IOException e) {
   e.printStackTrace();
   System.exit(1);
 }

This code fragement requires imports for the File and IOException classes in the java.io package as well as the org.w3c.dom.Document class name. We can now call methods for the xmlDoc object to navigate through the elements in the document tree structure. Let's look at what the possibilities are.

Navigating a Document Object Tree

The Node interface that is defined in the org.w3c.dom package is fundamental to all objects that encapsulate components of an XML document, and this includes the Document object itself. The subinterfaces of Node that identify components of a document are:

Each of these interfaces declares its own set of methods and inherits the method declared in the Node interface. Every XML document will be modeled as a hierarchy of nodes that will be accessible as one or other of the interface types in the table above. At the top of the node hierarchy for a document will be the Document node that is returned by the parse() method. Each type of node may or may not have child nodes in the document hierarchy, and those that do can only have certain types of child node. The types of nodes in a document that can have children are as follows:

Of course, what each node may have as children follows from the XML specification, not just the DOM specification. There is one other type of node that extends the Node interface – DocumentFragment. This is not formally part of a document in the sense that a node of this type is a programming convenience. It is used to house a fragment of a document – a sub-tree of elements – for use when moving fragments of a document around, for instance, so it provides a similar function to a Document node but with less overhead. A DocumentFragment node can have the same range of child nodes as an Element node.

The starting point for exploring the entire document tree is the root element for the document. We can obtain a reference to an object that encapsulates the root element by calling the getDocumentElement() method for the Document object:

Element root = xmlDoc.getDocumentElement();

This method returns the root element for the document as type Element. You can also get the node corresponding to the DOCTYPE declaration as type DocumentType like this:

DocumentType doctype = xmlDoc.getDoctype();

The next step is to obtain the child nodes for the root element. We can use the getChildNodes() method that is defined in the Node interface for this. This method returns a NodeList reference that encapsulates all the child elements for that element. You can call this method for any node that has children, including the Document node if you wish. We can therefore obtain the child elements for the root element with the following statement:

NodeList children = root.getChildNodes();

A NodeList reference encapsulates an ordered collection of Node references, each of which may be one or other of the possible node types for the current node. So with an Element node, any of the Node references in the list that is returned can be of type Element, Text, Comment, CDATASection, EntityReference, or ProcessingInstruction. Note that if there are no child nodes, the getChildNodes() method will return a NodeList reference that is empty, not null. You call the getChildNodes() method to obtain a list of child nodes for any node type that can have them.

The NodeList interface declares just two methods:

We can use these methods to iterate through the child elements of the root element, perhaps like this:

Node[] nodes = new Node[children.getLength()];
for(int i = 0 ; i<nodes.getLength() ; i++)
  nodes[i] = children.item(i);

Of course, we will normally be interested in the specific types of nodes that are returned so we will want to extract them as specific types or at least determine what they are before processing them. This is not difficult. You can test the type of any node using the instanceof operator. Here's one way we could extract just the child nodes that are of type Element:

java.util.Vector elements = new java.util.Vector();
Node node = null;
for(int i = 0 ; i<nodes.getLength() ; i++) {
  node = children.item(i);
if(node instanceof Element)
  elements.add(node);
}

A simple loop like this is not a very practical approach to navigating a document. In general we have no idea of the level to which elements are nested in a document and this loop only examines one level. We need an approach that will allow any level of nesting. This is a job for recursion. Let's put together a working example to illustrate this.

Try It Out – Listing a Document

We can extend the previous example to list the nodes in a document. We will add a static method to the TryDOM class to list child elements recursively. We will output details of each node followed by its children. Here's the code:

import javax.xml.parsers.*;
import org.xml.sax.*;
import org.w3c.dom.*;

import java.io.File;
import java.io.IOException;

public class TryDOM implements ErrorHandler {
  public static void main(String args[]) {
    if(args.length == 0) {
      System.out.println("No file to process."+
                           "Usage is:\njava TryDOM \"filename\"");
                           
      System.exit(1);
    }
    File xmlFile = new File(args[0]);
    DocumentBuilderFactory builderFactory = DocumentBuilderFactory.newInstance();
    builderFactory.setNamespaceAware(true);       // Set namespace aware
    builderFactory.setValidating(true);           // and validating parser feaures

    DocumentBuilder builder = null;
    try {
      builder = builderFactory.newDocumentBuilder();  // Create the parser
      builder.setErrorHandler(new TryDOM()); //Error handler is instance of TryDOM

    } catch(ParserConfigurationException e) {
      e.printStackTrace();
      System.exit(1);
    }
    Document xmlDoc = null;

    try {
      xmlDoc = builder.parse(xmlFile);

    } catch(SAXException e) {
      e.printStackTrace();

    } catch(IOException e) {
      e.printStackTrace();
    }
    DocumentType doctype = xmlDoc.getDoctype();       // Get the DOCTYPE node
    System.out.println("DOCTYPE node:\n" + doctype);  // and output it
    System.out.println("\nDocument body contents are:");
    listNodes(xmlDoc.getDocumentElement(),"");         // Root element & children
  }
  
  // output a node and all its child nodes
  static void listNodes(Node node, String indent) {
    String nodeName = node.getNodeName();
    System.out.println(indent+nodeName+" Node, type is "
                                             +node.getClass().getName()+":");
    System.out.println(indent+" "+node);

    NodeList list = node.getChildNodes();       // Get the list of child nodes
    if(list.getLength() > 0) {                  // As long as there are some...
      System.out.println(indent+"Child Nodes of "+nodeName+" are:");
      for(int i = 0 ; i<list.getLength() ; i++) //...list them & their children...
        listNodes(list.item(i),indent+" ");     // by calling listNodes() for each  
    }         
  }

  public void fatalError(SAXParseException spe) throws SAXException {
    System.out.println("Fatal error at line "+spe.getLineNumber());
    System.out.println(spe.getMessage());
    throw spe;
  }

  public void warning(SAXParseException spe) {
    System.out.println("Warning at line "+spe.getLineNumber());
    System.out.println(spe.getMessage());
  }

  public void error(SAXParseException spe) {
    System.out.println("Error at line "+spe.getLineNumber());
    System.out.println(spe.getMessage());
  }
}

I have removed the statement outputting details of the parser to reduce the output a little. Run this with the version of Address.xml that includes a DOCTYPE declaration. The program produces quite a lot of output starting with:

DOCTYPE node:
org.apache.crimson.tree.Doctype@decdec

Document body contents are:
address Node, type is org.apache.crimson.tree.ElementNode2:
 <address>
  <buildingnumber> 29 </buildingnumber>
  <street> South Lasalle Street</street>
  <city>Chicago</city>
  <state>Illinois</state>
  <zip>60603</zip>
 /address>
Child Nodes of address are:
 #text Node, type is org.apache.crimson.tree.TextNode:
   
  
 buildingnumber Node, type is org.apache.crimson.tree.ElementNode2:
   <buildingnumber> 29 </buildingnumber>
 Child Nodes of buildingnumber are:
   #text Node, type is org.apache.crimson.tree.TextNode:
     29 
 #text Node, type is org.apache.crimson.tree.TextNode:

and so on down to the last few lines:

zip Node, type is org.apache.crimson.tree.ElementNode2:
   <zip>60603</zip>
Child Nodes of zip are:
   #text Node, type is org.apache.crimson.tree.TextNode:
    60603
 #text Node, type is org.apache.crimson.tree.TextNode:

How It Works

Since we have set the parser configuration in the factory object to include validating the XML, we have to provide an org.xml.sax.ErrorHandler object for the parser. The TryDOM class implements the warning(), error(), and fatalError() methods declared by the ErrorHandler interface so an instance of this class takes care of it.

We call the getDoctype() method for the Document object to obtain the node corresponding to the DOCTYPE declaration:

DocumentType doctype = xmlDoc.getDoctype();       // Get the DOCTYPE node
System.out.println("DOCTYPE node:\n" + doctype);  // and output it

You can see from the output that we only get the class name with a hash code for the object appended. We will see how we can get more detail a little later.

After outputting a header line showing where the document body starts, we output the contents starting with the root element. The listNodes() method does all the work. We pass a reference to the root element that we obtain from the Document object with the statement:

listNodes(xmlDoc.getDocumentElement(),"");         // Root element & children

The first argument to listNodes() is the node to be listed and the second argument is the current indent for output. On each recursive call of the method, we will append a couple of spaces. This will result in each nested level of nodes being indented in the output by two spaces relative to the parent node output.

The first step in the listNodes() method is to get the name of the current node by calling its getNodeName() method:

String nodeName = node.getNodeName();       // Get name of this node

We then output the name of the current node followed by its class name with the statement:

System.out.println(indent + nodeName + " Node, type is " 
                 + node.getClass().getName()+":");

The indent parameter defines the indentation for the current node. Calling getClass() for the node object returns a Class object encapsulating its class type. We then call the getName() method for the Class object to obtain the class type name for the node.

The next statement outputs the node itself:

System.out.println(indent+" "+node);

This will automatically output the string produced by the toString() method for the node. Take a look at the output that corresponds to this as it is quite revealing. The node corresponding to the root element is first, and for this we get the entire document contents generated by the toString() method:

<address>
  <buildingnumber> 29 </buildingnumber>
  <street> South Lasalle Street</street>
  <city>Chicago</city>
  <state>Illinois</state>
  <zip>60603</zip>
</address>

On the basis of this, when you create a new Document object and want to write it as a document to a file, you might be tempted to use the toString() method for the root element to provide all the text for the document body. This would be unwise. It would work for this particular parser but you cannot be sure that another parser will do the same. There is no prescribed string returned by toString() so what you get will depend entirely on the parser and maybe on the particular release of the parser. When you want to write a document to a file, extract the data from the Document object and assemble the text yourself.

The remainder of the listNodes() code iterates through the child nodes of the current node if it has any:

NodeList list = node.getChildNodes();       // Get the list of child nodes
if(list.getLength() > 0) {                  // As long as there are some...
  System.out.println(indent+"Child Nodes of "+nodeName+" are:");
    for(int i = 0 ; i<list.getLength() ; i++) //...list them & their children...
      listNodes(list.item(i),indent+" ");     // by calling listNodes() for each  

The for loop simply iterates through the list of child nodes obtained by calling the getChildNodes() method. Each child is passed as an argument to the listNodes() method, which will list the node and iterate through its children. In this way the method will work through all the nodes in the document. You can see that we append an extra couple of spaces to indent in the second argument to the listNodes() call for a child node. The indent parameter in the next level down will reference a string that is two spaces longer. This ensures that the output for the next level of nodes will be indented relative to the current node.

You can see from the output that the output produced by the toString() method for each node by the Crimson parser encompasses its child nodes too. Of course, we get all of them explicitly as nodes in their own right, so there is a lot of duplication in the output. You may have noticed that the output is strange in some ways. We seem to have picked up some extra #text nodes from somewhere that seem to contain just whitespace. Each block of text or whitespace is returned as a node with the name #text, and that includes ignorable whitespace here. The newline characters at the end of each line in the original document, for instance, will contribute text nodes that are ignorable whitespace.

If you don't want to see it, getting rid of the ignorable whitespace is very simple. We just need to set another parser feature in the factory object:

builderFactory.setNamespaceAware(true);        // Set namespace aware
builderFactory.setValidating(true);            // and validating parser features
builderFactory.setIgnoringElementContentWhitespace(true); 

Calling this method will result in a parser that will not report ignorable whitespace as a node, so you won't see it in the Document object. If you run the example again with this change, the #text nodes arising from ignorable whitespace will no longer be there. Of course, this is not necessarily a plus since now the output produced by the toString() method is not as readable as it was before because everything appears on a single line.

switch(node.getNodeType()) {
  case Node.DOCUMENT_NODE:
    // Code to process a document node
    break;
  case Node.DOCUMENT_TYPE_NODE:
    // Code to process a DOCTYPE node
    break;
  case Node.DOCUMENT_NODE:
    // Code to process a document node
    break;
  case Node.ELEMENT_NODE:
    // Code to process an element node
    break;
  // ... and so on for the rest of the type values...
  default:
    assert false;
}

  static void listNodes(Node node, String indent) {
    String nodeName = node.getNodeName();
    System.out.println(indent+nodeName+" Node, type is "
                                                 +node.getClass().getName()+":");
    System.out.println(indent+" "+node);
    Node childNode = node.getFirstChild();           // Get first child
    while(childNode != null) {                       // While we have a child...
        listNodes(childNode, indent+"  ");              // ...list it, then...
        childNode = childNode.getNextSibling();         // ...get next child
    }
}

if(node instanceof Element && node.has Attributes()) {
    // Process the element with its attributes

} else {
    // Process the element without attributes
}

if(node instanceof Element && node.hasAttributes()) {
  NamedNodeMap attrs = node.getAttributes();
  for(int i = 0 ; i<attrs.getLength() ; i++) {
          Attr attribute = (Attr)attrs.item(i); // Process the attribute...
  }

} else {   // Process the element without attributes
}

static void listNodes(Node node) {
    String nodeName = node.getNodeName();
    System.out.println(indent+nodeName+" Node, type is "
                                                  +node.getClass().getName()+":");
    System.out.println(indent+" "+node);

    if(node instanceof Element && node.hasAttributes()) {
      System.out.println(indent+"Element Attributes are:");
      NamedNodeMap attrs = node.getAttributes();//...get the attributes
      for(int i = 0 ; i<attrs.getLength() ; i++) {
        Attr attribute = (Attr)attrs.item(i);      // Get an attribute
        System.out.println(indent+attribute.getName()+"="+attribute.getValue());
      }
    }
  
    NodeList list = node.getChildNodes();      // Get the list of child nodes
    if(list.getLength() > 0) {                 // As long as there are some...
      System.out.println(indent+"Child Nodes of "+nodeName+" are:");
      for(int i = 0 ; i<list.getLength() ; i++)// ...list them & their children...
        listNodes(list.item(i),indent+"  ");   // by calling listNodes()  
    }         
}

import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.ParserConfigurationException;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;
import org.xml.sax.ErrorHandler;
import org.w3c.dom.Document;
import org.w3c.dom.DocumentType;
import org.w3c.dom.NodeList;
import org.w3c.dom.Node;
import org.w3c.dom.Element;
import org.w3c.dom.Attr;
import org.w3c.dom.NamedNodeMap;
import java.io.File;
import java.io.IOException;

  private static String getDoctypeString(DocumentType doctype) {
    // Create the opening string for the DOCTYPE declaration with its name
    String str = doctype.getName();
    StringBuffer doctypeStr = new StringBuffer("<!DOCTYPE ").append(str);        

    // Check for a system ID or a public ID
    final char QUOTE = '\"'; 
    if((str = doctype.getSystemId()) != null) 
      doctypeStr.append(" SYSTEM ").append(QUOTE).append(str).append(QUOTE);
    else if((str = doctype.getPublicId()) != null) // Check for a public ID
      doctypeStr.append(" PUBLIC ").append(QUOTE).append(str).append(QUOTE);

    // Check for an internal subset
    if((str = doctype.getInternalSubset()) != null)
      doctypeStr.append('[').append(str).append(']');           

    return doctypeStr.append('>').toString();  // Append '>', return the string
  }

DocumentType doctype = xmlDoc.getDoctype();                    // Get DOCTYPE node
System.out.println("DOCTYPE node:\n" + getDoctypeString(doctype));  // & output it

DOCTYPE node:
<!DOCTYPE circle[
<!ELEMENT circle (position)>
<!ELEMENT position EMPTY>
<!ATTLIST circle 
 radius CDATA #REQUIRED
 >
<!ATTLIST position 
 x CDATA #REQUIRED
  y CDATA #REQUIRED
  >
]>

Document body contents are:
circle Node, type is org.apache.xerces.dom.DeferredElementImpl:
 [circle: null]
Element Attributes are:
radius=15
Child Nodes of circle are:
#text Node, type is org.apache.xerces.dom.DeferredTextImpl:
[#text: 
]
position Node, type is org.apache.xerces.dom.DeferredElementImpl:
[position: null]
Element Attributes are:
x=30
y=50
#text Node, type is org.apache.xerces.dom.DeferredTextImpl:
[#text: 
]

String str = doctype.getName();
StringBuffer doctypeStr = new StringBuffer("<!DOCTYPE ").append(str);        

if((str = doctype.getSystemId()) != null) 
  doctypeStr.append(" SYSTEM ").append(QUOTE).append(str).append(QUOTE);
else if((str = doctype.getPublicId()) != null) // Check for a public ID
  doctypeStr.append(" PUBLIC ").append(QUOTE).append(str).append(QUOTE);

if((str = doctype.getInternalSubset()) != null)
  doctypeStr.append('[').append(str).append(']');           

return doctypeStr.append('>').toString();  // Append '>' and return the string

Creating XML Documents

You can create an XML document in a file programmatically by a two-step process. You can first create a Document object that encapsulates what you want in your XML document. Then you can use the Document object to create the hierarchy of elements that has to be written to the file. We will first look at how we create a suitable Document object.

The simplest way to create a Document object programmatically is to call the newDocument() method for a DocumentBuilder object and it will return a reference to a new empty Document object:

Document newDoc = builder.newDocument();

This is rather limited, especially since there's no way with DOM2 to modify the DocumentType node to reflect a suitable DOCTYPE declaration.

There's an alternative approach that provides a bit more flexibility but it is not quite so direct. You first call the getDOMImplementation() method for the DocumentBuilder object:

DOMImplementation domImpl = builder.getDOMImplementation();

This returns a reference of type DOMImplementation to an object that encapsulates the underlying DOM implementation. This interface type is defined in the org.w3c.dom package.

There are three methods you can call for a DOMImplementation object:

You can see from the first two methods here that there is a big advantage to using a DOMImplementation object to create a document. First of all, you can create a DocumentType object by calling the createDocumentType() method:

DocumentType doctype = null;
try {     
  doctype = domImpl.createDocumentType("sketch", null, "sketcher.dtd");

} catch(DOMException e) {
  // Handle the exception
}

This code fragment creates a DocumentType node for an external DOCTYPE declaration with the name sketch, with the system ID sketcher.dtd. There is no public ID in this case since we specified the second argument as null. You can now use the DocumentType object in the creation of a document:

Document newDoc = null;
try {     
  doctype = domImpl.createDocumentType("sketch", null, "sketcher.dtd");
  newDoc = domImpl.createDocument(null, "sketch", doctype);
}
catch(DOMException e) {
  // Handle the exception
}

The DOMException object that may be thrown by either of these two methods has a public field with the name code that is of type int. This stores an error code identifying the type of error that caused the exception so you can check the value of code to determine the cause of the error. This exception can be thrown by a number of different methods that you use to create nodes in a document so the values that code can have is not limited to the two methods we have just used. There are fifteen possible values for code that are defined in the DOMException class but obviously you would only check for those that apply to the code in the try block where the exception may arise.

The possible values for code in a DOMException object thrown by the createDocument() method are:

The createDocumentType() method can also throw an exception of type DOMException with code set to either of the first two values above.

We therefore might code the catch block in the previous fragment like this:

catch(DOMException e) {
  switch(e.code) {
    case DOMException.INVALID_CHARACTER_ERR:
      System.err.println("Qualified name contains an invalid character");
      break;
    case DOMException.NAMESPACE_ERR:
      System.err.println("Qualified name is malformed or invalid");
      break;
    case DOMException.WRONG_DOCUMENT_ERR:
      System.err.println("Document does not support this doctype");
      break;
    default:
      assert false;
    System.err.println(e.getMessage());
  }
}

Of course, you can also output the stack trace, return from the method, or even end the program here if you want.

Storing a Sketch as XML

We have already defined a DTD in the previous chapter that is suitable for defining a sketch. We can see how we can put together the code to store a sketch as an XML document instead of as a serialized object. Obviously we'll use the DTD we already have, and we can create a Document object with a DocumentType node via a DOMImplementation object from a DocumentBuilder object. We can do this with two statements in a try block:

Document doc = null;
try {
  DOMImplementation domImpl = DocumentBuilderFactory.newInstance()
                                                      .newDocumentBuilder()
                                                        .getDOMImplementation();
  doc = domImpl.createDocument(null, "sketch",
                    domImpl.createDocumentType("sketcher", null, "sketcher.dtd"));

} catch(ParserConfigurationException e) {
  e.printStackTrace(System.err);
  // Display the error and terminate the current activity...

} catch(DOMException e) {
  e.printStackTrace(System.err);
  // Determine the kind of error from the error code, 
  // display the error, and terminate the current activity...
}

They are rather long statements since they accomplish in a single statement what we previously did in several steps. However, they are quite simple. The first statement creates a DocumentBuilderFactory object from which a DocumentBuilder object is created from which a reference DOMImplementation object is obtained and stored in domImpl. This is used in the next statement to create the Document object for a sketch and its DocumentType object defining the DOCTYPE declaration for sketcher.dtd. Eventually we will add this code to the SketchModel class but let's leave that to one side for the moment while we look at how we can fill out the detail of the Document object from the objects representing elements in a sketch.

A sketch in XML is a simple two-level structure. The root node in an XML representation of a sketch will be a <sketch> element, so to define the structure we only need to add an Element node to the content for the root node for each element in the sketch. A good way to implement this would be to add a method to each of the sketch Element classes that adds its own org.w3c.dom.Element node to the Document object. This will make each object representing a sketch element able to create its own XML representation.

The Sketcher classes we have to modify are the inner classes to the Element class, plus the Element class itself. The inner classes are Element.Line, Element.Rectangle, Element.Circle, Element.Curve, and Element.Text. The nodes that have to be added for each kind of geometric element derive directly from the declaration in the DTD, so it will help if you have this to hand while we go through these classes. If you typed it in when we discussed it in the last chapter, maybe you can print a copy.

  public abstract void draw(Graphics2D g2D);
  public abstract void addElementNode(Document document);

import org.w3c.dom.Document;
import org.w3c.dom.Attr;

protected org.w3c.dom.Element createColorElement(Document doc) {
    org.w3c.dom.Element colorElement = doc.createElement("color");
 
    Attr attr = doc.createAttribute("R");
    attr.setValue(String.valueOf(color.getRed()));
    colorElement.setAttributeNode(attr);  

    attr = doc.createAttribute("G");
    attr.setValue(String.valueOf(color.getGreen()));
    colorElement.setAttributeNode(attr);  

    attr = doc.createAttribute("B");
    attr.setValue(String.valueOf(color.getBlue()));
    colorElement.setAttributeNode(attr);
    return colorElement;      
}

protected org.w3c.dom.Element createPointTypeElement(Document doc,
                                                     String name,
                                                     String xValue,
                                                     String yValue) { 
    org.w3c.dom.Element element = doc.createElement(name);

    Attr attr = doc.createAttribute("x");         // Create attribute x
    attr.setValue(xValue);                        // and set its value
    element.setAttributeNode(attr);               // Insert the x attribute   

    attr = doc.createAttribute("y");              // Create attribute y
    attr.setValue(yValue);                        // and set its value
    element.setAttributeNode(attr);               // Insert the y attribute   
    return element;              
}

  protected org.w3c.dom.Element createPositionElement(Document doc) {
    return createPointTypeElement(doc, "position",
                                  String.valueOf(position.getX()),
                                  String.valueOf(position.getY()));
  }

public void addElementNode(Document doc) {
  org.w3c.dom.Element lineElement = doc.createElement("line");
 
  // Create the angle attribute and attach it to the <line> node
  Attr attr = doc.createAttribute("angle");
  attr.setValue(String.valueOf(angle));
  lineElement.setAttributeNode(attr);
  
  // Append the <color>, <position>, and <endpoint> nodes as children
  lineElement.appendChild(createColorElement(doc));
  lineElement.appendChild(createPositionElement(doc));
  lineElement.appendChild(createEndpointElement(doc));
  
  // Append the <line> node to the document root node
  doc.getDocumentElement().appendChild(lineElement); 
} 

private org.w3c.dom.Element createEndpointElement(Document doc) {
  return createPointTypeElement(doc, "endpoint",
                                String.valueOf(line.x2+position.x),
                                String.valueOf(line.y2+position.y));
}

public void addElementNode(Document doc) {
  org.w3c.dom.Element rectElement = doc.createElement("rectangle");
 
  // Create the angle attribute and attach it to the <rectangle> node
  Attr attr = doc.createAttribute("angle");
  attr.setValue(String.valueOf(angle));
  rectElement.setAttributeNode(attr);
 
  // Append the <color>, <position>, and <bottomright> nodes as children
  rectElement.appendChild(createColorElement(doc));
  rectElement.appendChild(createPositionElement(doc));
  rectElement.appendChild(createBottomrightElement(doc));
 
  doc.getDocumentElement().appendChild(rectElement);
}

private org.w3c.dom.Element createBottomrightElement(Document doc) {
  return createPointTypeElement(doc, "bottomright",
                                String.valueOf(rectangle.width+position.x),
                                String.valueOf(rectangle.height+position.y));
}

public void addElementNode(Document doc) {
  org.w3c.dom.Element circleElement = doc.createElement("circle");
 
  // Create the radius attribute and attach it to the <circle> node
  Attr attr = doc.createAttribute("radius");
  attr.setValue(String.valueOf(circle.width/2.0));
  circleElement.setAttributeNode(attr);
  
  // Create the angle attribute and attach it to the <circle> node
  attr = doc.createAttribute("angle");
  attr.setValue(String.valueOf(angle));
  circleElement.setAttributeNode(attr);

  // Append the <color> and <position> nodes as children
  circleElement.appendChild(createColorElement(doc));
  circleElement.appendChild(createPositionElement(doc));
 
  doc.getDocumentElement().appendChild(circleElement);
}

public void addElementNode(Document doc) {
  org.w3c.dom.Element curveElement = doc.createElement("curve");
  
  // Create the angle attribute and attach it to the <curve> node
  Attr attr = doc.createAttribute("angle");
  attr.setValue(String.valueOf(angle));
  curveElement.setAttributeNode(attr);
   
  // Append the <color> and <position> nodes as children
  curveElement.appendChild(createColorElement(doc));
  curveElement.appendChild(createPositionElement(doc));
  
  // Get the defining points via a path iterator
  PathIterator iterator = curve.getPathIterator(new AffineTransform());
  int maxCoordCount = 6;                  // Maximum coordinates for a segment
  float[] temp = new float[maxCoordCount];           // Stores segment data
  
  int result = iterator.currentSegment(temp);        // Get first segment
  assert result == iterator.SEG_MOVETO;              // ... should be move to
  
  iterator.next();                                   // Next segment
  while(!iterator.isDone())   {                      // While we have segments
    result = iterator.currentSegment(temp);          // Get the segment data
    assert result == iterator.SEG_LINETO;            // Should all be lines
   
    // Create a <point> node and add it to the list of children
    curveElement.appendChild(createPointTypeElement(doc, "point",
                                  String.valueOf(temp[0]+position.x),
                                  String.valueOf(temp[1])+position.y));
    iterator.next();                                   // Go to next segment
  }
  
  doc.getDocumentElement().appendChild(curveElement);
}

public void addElementNode(Document doc) {
  org.w3c.dom.Element textElement = doc.createElement("text");
 
  // Create the angle attribute and attach it to the <text> node
  Attr attr = doc.createAttribute("angle");
  attr.setValue(String.valueOf(angle));
  textElement.setAttributeNode(attr);
     
  // Append the <color> and <position> nodes as children
  textElement.appendChild(createColorElement(doc));
  textElement.appendChild(createPositionElement(doc));
   
  // Create and apppend the <font> node 
  org.w3c.dom.Element fontElement = doc.createElement("font");
  attr = doc.createAttribute("fontname");
  attr.setValue(font.getName());
  fontElement.setAttributeNode(attr);
  
  attr = doc.createAttribute("fontstyle");
  String style = null;
  int styleCode = font.getStyle();
  if(styleCode == Font.PLAIN)
    style = "plain";
  else if(styleCode == Font.BOLD)
    style = "bold";
  else if(styleCode == Font.ITALIC)
    style = "italic";
  else if(styleCode == Font.ITALIC+Font.BOLD)
      style = "bold-italic";
  assert style != null;
  attr.setValue(style);
  fontElement.setAttributeNode(attr);
 
  attr = doc.createAttribute("pointsize");
  attr.setValue(String.valueOf(font.getSize()));
  fontElement.setAttributeNode(attr);
  textElement.appendChild(fontElement);
 
  // Create the <string> node
  org.w3c.dom.Element string = doc.createElement("string");
 
  // Create the <bounds> node and its attributes
  org.w3c.dom.Element bounds = doc.createElement("bounds");
  attr = doc.createAttribute("width");
  attr.setValue(String.valueOf(this.bounds.width));
  bounds.setAttributeNode(attr);
  attr = doc.createAttribute("height");
  attr.setValue(String.valueOf(this.bounds.height));
  bounds.setAttributeNode(attr);
  string.appendChild(bounds);      // Set <bounds> element as <string> content

  string.appendChild(doc.createTextNode(text));
  textElement.appendChild(string);// Set <text> as <string> content
  doc.getDocumentElement().appendChild(textElement);
}

import javax.swing.JOptionPane;
import javax.xml.parsers.*;
import org.w3c.dom.Document;
import org.w3c.dom.DOMImplementation;
import org.w3c.dom.DOMException;

  // Creates a DOM Document object encapsulating the current sketch  
  public Document createDocument() {
    Document doc = null;
    try {
      DOMImplementation domImpl = DocumentBuilderFactory.newInstance()
                                                        .newDocumentBuilder()
                                                        .getDOMImplementation();
      doc = domImpl.createDocument(null, "sketch",
                   domImpl.createDocumentType("sketcher", null, "sketcher.dtd"));

    } catch(ParserConfigurationException e) {
      JOptionPane.showInternalMessageDialog(null,
                  "Parser configuration error while creating document",
                  "DOM Parser Error",
                  JOptionPane.ERROR_MESSAGE); 
      System.err.println(e.getMessage());
      e.printStackTrace(System.err);
      return null;

    } catch(DOMException e) {
      JOptionPane.showInternalMessageDialog(null,
                  "DOM exception thrown while creating document",
                  "DOM Error",
                  JOptionPane.ERROR_MESSAGE); 
      System.err.println(e.getMessage());
      e.printStackTrace(System.err);
      return null;
    }

    // Each element in the sketch can create its own node in the document
    Iterator iter = getIterator();                 // Iterator for sketch elements
    while(iter.hasNext())                          // For each element...
      ((Element)iter.next()).addElementNode(doc);  // ...add its node.
    return doc;
  }

private FileAction newAction,  openAction,   closeAction,
                   saveAction, saveAsAction, printAction;
private XMLExportAction exportAction;    // Stores action for XML export menu item
private XMLImportAction importAction;    // Stores action for XML import menu item

addMenuItem(fileMenu, saveAction);
addMenuItem(fileMenu, saveAsAction);
fileMenu.addSeparator();                                      // Add separator
addMenuItem(fileMenu, 
            exportAction = new XMLExportAction("Export XML",
                                               "Export sketch as an XML file"));
addMenuItem(fileMenu, 
            importAction = new XMLImportAction("Import XML",
                                               "Import sketch from an XML file"));
fileMenu.addSeparator();                                    // Add separator

  class XMLExportAction extends AbstractAction {
    public XMLExportAction(String name, String tooltip) {
      super(name);
      if(tooltip != null)                             // If there is tooltip text
        putValue(SHORT_DESCRIPTION, tooltip);         // ...squirrel it away
    }

    public void actionPerformed(ActionEvent e) {
        JFileChooser chooser = new JFileChooser(DEFAULT_DIRECTORY);
        chooser.setDialogTitle("Export Sketch as XML");
        chooser.setApproveButtonText("Export");
        ExtensionFilter xmlFiles = new ExtensionFilter(".xml",
                                                      "XML Sketch files (*.xml)");
        chooser.addChoosableFileFilter(xmlFiles);             // Add the filter
        chooser.setFileFilter(xmlFiles);                      // and select it
        int result = chooser.showDialog(SketchFrame.this, null); // Show dialog
        File file = null;
        if(chooser.showDialog(SketchFrame.this, null) == chooser.APPROVE_OPTION){
          file = chooser.getSelectedFile();
          if(file.exists()) {                           // Check file exists
            if(JOptionPane.NO_OPTION ==                 // Overwrite warning
               JOptionPane.showConfirmDialog(SketchFrame.this,
                                  file.getName()+" exists. Overwrite?",
                                  "Confirm Save As",
                                  JOptionPane.YES_NO_OPTION,
                                  JOptionPane.WARNING_MESSAGE))
               return;                                   // No overwrite
          }
          saveXMLSketch(file);
      }
    }
  }

  class XMLImportAction extends AbstractAction {
    public XMLImportAction(String name, String tooltip) {
      super(name);
      if(tooltip != null)                             // If there is tooltip text
        putValue(SHORT_DESCRIPTION, tooltip);         // ...squirrel it away
    }

    public void actionPerformed(ActionEvent e) {
      JFileChooser chooser = new JFileChooser(DEFAULT_DIRECTORY);
      chooser.setDialogTitle("Import Sketch from XML");
      chooser.setApproveButtonText("Import");
      ExtensionFilter xmlFiles = new ExtensionFilter(".xml",
                                                    "XML Sketch files (*.xml)");
      chooser.addChoosableFileFilter(xmlFiles);             // Add the filter
      chooser.setFileFilter(xmlFiles);                      // and select it
      int result = chooser.showDialog(SketchFrame.this, null);  // Show dialog
      if(chooser.showDialog(SketchFrame.this, null) == chooser.APPROVE_OPTION)
        openXMLSketch(chooser.getSelectedFile());     
    }
  }

  String QUOTE_ENTITY = """;
  char QUOTE = '\"';
  char NEWLINE = '\n';
  char TAG_START = '<';
  char TAG_END = '>';
  String EMPTY_TAG_END = "/>";
  String END_TAG_START = "</";

  private void saveXMLSketch(File outFile) {
    FileOutputStream outputFile = null;      // Stores an output stream reference 
    try {
      outputFile = new FileOutputStream(outFile);    // Output stream for the file 
      FileChannel outChannel = outputFile.getChannel(); // Channel for file stream 
      writeXMLFile(theApp.getModel().createDocument(), outChannel);

    } catch(FileNotFoundException e) {
      e.printStackTrace(System.err);
      JOptionPane.showMessageDialog(SketchFrame.this,
                       "Sketch file " + outFile.getAbsolutePath() + " not found.",
                       "File Output Error",
                       JOptionPane.ERROR_MESSAGE);
      return;                           // Serious error – return
    }
  }

import java.nio.channels.FileChannel; 

  private void writeXMLFile(org.w3c.dom.Document doc, FileChannel channel) {
    StringBuffer xmlDoc = new StringBuffer(
                                 "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"); 
    xmlDoc.append(NEWLINE).append(getDoctypeString(doc.getDoctype()));
    xmlDoc.append(getDocumentNode(doc.getDocumentElement(), ""));
 
    try {
      channel.write(ByteBuffer.wrap(xmlDoc.toString().getBytes("UTF-8")));

    } catch(UnsupportedEncodingException e) {
      System.out.println(e.getMessage());

    } catch(IOException e) {
      JOptionPane.showMessageDialog(SketchFrame.this,
                                          "Error writing XML to channel.",
                                              "File Output Error",
                                              JOptionPane.ERROR_MESSAGE);
      e.printStackTrace(System.err);
      return;
    }
  }

xmlDoc.append(getDocumentNode(doc.getDocumentElement(), ""));

channel.write(ByteBuffer.wrap(xmlDoc.toString().getBytes("UTF-8")));

   private String getDoctypeString(org.w3c.dom.DocumentType doctype) {
      // Create the opening string for the DOCTYPE declaration with its name
      String str = doctype.getName();
      StringBuffer doctypeStr = new StringBuffer("<!DOCTYPE ").append(str);        

      // Check for a system ID
      if((str = doctype.getSystemId()) != null)
        doctypeStr.append(" SYSTEM ").append(QUOTE).append(str).append(QUOTE);

      // Check for a public ID
      if((str = doctype.getPublicId()) != null)
        doctypeStr.append(" PUBLIC ").append(QUOTE).append(str).append(QUOTE);

      // Check for an internal subset
      if((str = doctype.getInternalSubset()) != null)
        doctypeStr.append('[').append(str).append(']');           

      return doctypeStr.append(TAG_END).toString();  // Append '>' & return string
  }

  private String getDocumentNode(Node node, String indent) {
    StringBuffer nodeStr = new StringBuffer().append(NEWLINE).append(indent); 
    String nodeName = node.getNodeName();       // Get name of this node

    switch(node.getNodeType()) {
      case Node.ELEMENT_NODE:
      nodeStr.append(TAG_START);
      nodeStr.append(nodeName);
      if(node.hasAttributes()) {             // If the element has attributes...
        org.w3c.dom.NamedNodeMap attrs = node.getAttributes();   // ...get them 
        for(int i = 0 ; i<attrs.getLength() ; i++) {
          org.w3c.dom.Attr attribute = (org.w3c.dom.Attr)attrs.item(i);      
          // Append " name="value" to the element string
          nodeStr.append(' ').append(attribute.getName()).append('=')
                        .append(QUOTE).append(attribute.getValue()).append(QUOTE);
        }
      }
      if(!node.hasChildNodes()) {        // Check for no children for this element
        nodeStr.append(EMPTY_TAG_END);   // There are none-close as empty element
        return nodeStr.toString();       // and return the completed element

      } else {                             // It has children
        nodeStr.append(TAG_END);         // so close start-tag
        NodeList list = node.getChildNodes();       // Get the list of child nodes
        assert list.getLength()>0;                  // There must be at least one
 
       // Append child nodes and their children...
        for(int i = 0 ; i<list.getLength() ; i++)     
          nodeStr.append(getDocumentNode(list.item(i), indent+" "));     
      }
      nodeStr.append(NEWLINE).append(indent).append(END_TAG_START)
                                               .append(nodeName).append(TAG_END);
      break;    

      case Node.TEXT_NODE:
      nodeStr.append(replaceQuotes(((org.w3c.dom.Text)node).getData()));
      break;

      default:
      assert false;
    }
    return nodeStr.toString();
  }

  public String replaceQuotes(String str) {
    StringBuffer buf = new StringBuffer();
    for(int i = 0 ; i<str.length() ; i++)
      if(str.charAt(i)==QUOTE)
        buf.append(QUOTE_ENTITY);
      else
        buf.append(str.charAt(i));

    return buf.toString(); 
  }       

import java.nio.ByteBuffer;
import java.nio.channels.FileChannel;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;

Reading an XML Representation of a Sketch

The Import XML operation will also be implemented in the SketchFrame class. We have already added the menu item and the XMLImportAction class that is used to create it. We just need to implement the openXMLSketch() method that is called by the actionPerformed() method in the XMLImportAction class.

Assuming our XML representation of a sketch is well-formed and valid, creating a Document object encapsulating a sketch will be a piece of cake. We will just get a DOM parser to do it – and it will verify that the document is well-formed and valid along the way. We will need an ErrorHandler object to deal with parsing errors, so let's add an inner class to our SketchFrame class for that:

  class DOMErrorHandler implements org.xml.sax.ErrorHandler {
    public void fatalError(org.xml.sax.SAXParseException spe) 
       throws org.xml.sax.SAXException {
      JOptionPane.showMessageDialog(SketchFrame.this,
                                    "Fatal error at line "+spe.getLineNumber()
                                  + "\n"+spe.getMessage(),
                                    "DOM Parser Error",
                                    JOptionPane.ERROR_MESSAGE);
      throw spe;
    }

    public void warning(org.xml.sax.SAXParseException spe) {
      JOptionPane.showMessageDialog(SketchFrame.this,
                                    "Warning at line "+spe.getLineNumber()
                                  + "\n"+spe.getMessage(),
                                    "DOM Parser Error",
                                    JOptionPane.ERROR_MESSAGE);
    }

    public void error(org.xml.sax.SAXParseException spe) {
      JOptionPane.showMessageDialog(SketchFrame.this,
                                    "Error at line "+spe.getLineNumber()
                                  + "\n"+spe.getMessage(),
                                    "DOM Parser Error",
                                    JOptionPane.ERROR_MESSAGE);
    }
  }

This implements the three methods declared in the ErrorHandler interface. In contrast to our previous example using a DOM error handler, rather than writing error information to the command line, here we display it in a suitable dialog.

Here's how we can implement the openXMLSketch() method in the SketchFrame class:

private void openXMLSketch(File xmlFile) {
  DocumentBuilderFactory builderFactory = DocumentBuilderFactory.newInstance();
  builderFactory.setValidating(true);           // Add validating parser feature
  builderFactory.setIgnoringElementContentWhitespace(true); 
     
  try {
    DocumentBuilder builder = builderFactory.newDocumentBuilder();
    builder.setErrorHandler(new DOMErrorHandler());
    checkForSave();
    theApp.insertModel(createSketchModel(builder.parse(xmlFile)));
    filename = xmlFile.getName();            // Update the file name
    setTitle(frameTitle+xmlFile.getPath());  // Change the window title
    sketchChanged = false;                     // Status is unchanged

  } catch(ParserConfigurationException e) {
    JOptionPane.showMessageDialog(SketchFrame.this,
                                  e.getMessage(),
                                  "DOM Parser Factory Error",
                                  JOptionPane.ERROR_MESSAGE);
    e.printStackTrace(System.err);

  } catch(org.xml.sax.SAXException e) {
     JOptionPane.showMessageDialog(SketchFrame.this,
                                   e.getMessage(),
                                   "DOM Parser Error",
                                   JOptionPane.ERROR_MESSAGE);
    e.printStackTrace(System.err);

  } catch(IOException e) {
    JOptionPane.showMessageDialog(SketchFrame.this,
                                  e.getMessage(),
                                  "I/O Error",
                                  JOptionPane.ERROR_MESSAGE);
    e.printStackTrace();
  }    
}

Most of the code here is devoted to catching exceptions that we hope will not get thrown. We set up the parser factory object to produce a validating parser that will ignore surplus whitespace. The latter feature will avoid extraneous nodes in the Document object that will be created by the parser from the XML file.

After storing a reference to the DOM parser that is created in builder, we create a DOMErrorHandler object and set that as the handler for any parsing errors that arise. If the parser finds any errors, we will see a dialog displayed indicating what the error is. We use the builder object to parse the XML file that is identified by the File object, xmlFile and pass the Document object that is returned by the parse() method to the createSketchModel() method that we will be adding to the SketchFrame class next. This method has the job of creating a new SketchModel object from the Document object.

Let's see how we can create a new SketchModel object encapsulating a new sketch by analyzing the Document object.

private SketchModel createSketchModel(org.w3c.dom.Document doc) {
   SketchModel model = new SketchModel();                 // The new model object

   // Get the first child of the root node
   org.w3c.dom.Node node = doc.getDocumentElement().getFirstChild();

   // Starting with the first child, check out each child in turn
   while (node != null) {
    assert node instanceof org.w3c.dom.Element;          // Should all be Elements
 
    String name = ((org.w3c.dom.Element)node).getTagName();  // Get the name

    if(name.equals("line"))                               // Check for a line
      model.add(new Element.Line((org.w3c.dom.Element)node)); 

    else if(name.equals("rectangle"))                     // Check for a rectangle
      model.add(new Element.Rectangle((org.w3c.dom.Element)node));  

    else if(name.equals("circle"))                        // Check for a circle
      model.add(new Element.Circle((org.w3c.dom.Element)node));     

    else if(name.equals("curve"))                         // Check for a curve
      model.add(new Element.Curve((org.w3c.dom.Element)node));      

    else if(name.equals("text"))                          // Check for a text
      model.add(new Element.Text((org.w3c.dom.Element)node));   

    node = node.getNextSibling();                          // Next child node
   }
      return model;    
  }

Creating Sketch Elements from XML Elements

Every element has to have the color field in the base class set to a color determined from a <color> element in the document. We can therefore usefully add a base class method to take care of this. Add the following to the Element class definition:

  protected void setElementColor(org.w3c.dom.Element colorElement) {
      color = new Color(Integer.parseInt(colorElement.getAttribute("R")),
                        Integer.parseInt(colorElement.getAttribute("G")),
                        Integer.parseInt(colorElement.getAttribute("B")));
  }

The method expects to receive a reference to an org.w3c.dom.Element object as an argument that contains the RGB values for the color. We extract the value of each of the attributes in the colorElement object by calling its getAttribute() method with the attribute name as the argument. We pass each of the values obtained to the Color constructor and we store the reference to this object in color. Because the attribute values are strings, we have to convert them to numerical values using the static parseInt() method that is defined in the Integer class.

The same applies to the position field in the Element class, so we will define a method in the Element class to initialize it from an org.w3c.dom.Element object:

  protected void setElementPosition(org.w3c.dom.Element posElement) {
      position = new Point(); 
      position.setLocation(Double.parseDouble(posElement.getAttribute("x")),
                           Double.parseDouble(posElement.getAttribute("y")));
  }

This uses essentially the same mechanism as the previous method. Here the attributes strings represent double values so we use the static parseDouble() method from the Double class to convert them to the numeric equivalent.

Every sketcher element has a color, a position, and an angle that are stored in base class fields so we can create a base class constructor to initialize these from the document node for the element:

  protected Element(org.w3c.dom.Element xmlElement) {
    // Get the <color> element
    org.w3c.dom.NodeList list = xmlElement.getElementsByTagName("color");
    setElementColor((org.w3c.dom.Element)list.item(0));        // Set the color

    list = xmlElement.getElementsByTagName("position");        // Get <position>
    setElementPosition((org.w3c.dom.Element)list.item(0));     // Set the position

    angle = Double.parseDouble(xmlElement.getAttribute("angle")); // Set the angle
  }

We have declared this constructor as protected to prevent the possibility of it being called externally.

Every one of our new constructors in the inner classes to Element will call this constructor first. An important point to remember is that if a constructor for a derived class object does not call a base class constructor as the first statement in the body of the constructor, the compiler will insert a call to the no-arg constructor for the base class. This means that a base class always has to have a no-arg constructor if the derived class constructors do not call a base class constructor with arguments.

We first extract the child element for the current element with the name "color" by calling the getElementsByTagName() method for xmlElement. This method, declared in the org.w3c.dom.Element interface, returns a NodeList object containing all the child nodes with the given name. If you pass the string "*" as the argument to this method, it will return all child org.w3c.dom.Element objects in the node list. There's another method, getElementsByTagNameNS(), that is declared in the Element interface that does the same for documents using namespaces. The first argument in this case is the namespace URI and the second argument is the element name. The strings to either or both arguments can be "*", in which case all namespaces and/or names will be matched.

We pass the reference to the element with the name "color" to the setElementColor() method that is inherited from the base class. This sets the value of the color field in the base class.

Next we initialize the position field in the Element class by calling the setElementPosition() method. The process is much the same as for the color field. Lastly we set the angle field by converting the string that is the value for the angle attribute for the current node to type double.

Now we are ready to add the new constructors to the subclasses to create sketch elements from XML elements.

Creating a Line Element

We can construct an Element.Line object by first calling the base class constructor we have just defined to set the color, position, and angle fields, and then setting the line field in the derived class. Here's the code for the constructor:

  // Content is <color>, <position>, <endpoint> elements. Attribute is angle.
  public Line(org.w3c.dom.Element xmlElement) {
    super(xmlElement);

    org.w3c.dom.NodeList list = xmlElement.getElementsByTagName("endpoint");
    org.w3c.dom.Element endpoint = (org.w3c.dom.Element)list.item(0);
    line = new Line2D.Double(origin.x, origin.y,
                Double.parseDouble(endpoint.getAttribute("x"))-position.getX(), 
                Double.parseDouble(endpoint.getAttribute("y"))-position.getY());
  }    

To save having to refer back to the DTD, the first comment in the constructor outlines the XML corresponding to the element. We first call the base class constructor and then extract the child element that is the <endpoint> element. You will doubtless recall that all our sketch elements are defined at the origin. This makes moving an element very easy and allows all elements to be moved in the same way – by modifying the position field. We therefore create the Line2D.Double object as a line starting at the origin. The coordinates of its end point are the values stored in the <endpoint> child element minus the corresponding coordinates of position that were set in the base class constructor.

Creating a Rectangle Element

This constructor will be almost identical to the previous constructor for a line:

    // Rectangle has angle attribute. Content is <color>,<position>,<bottomright>
    public Rectangle(org.w3c.dom.Element xmlElement) {
      super(xmlElement);

      org.w3c.dom.NodeList list = xmlElement.getElementsByTagName("bottomright");
      org.w3c.dom.Element bottomright = (org.w3c.dom.Element)list.item(0);
      rectangle = new Rectangle2D.Double(origin.x, origin.y, 
             Double.parseDouble(bottomright.getAttribute("x"))-position.getX(), 
             Double.parseDouble(bottomright.getAttribute("y"))-position.getY());
  }

Spot the differences! This code is so similar to that of the Line constructor that I don't think it requires further explanation.

Creating a Circle Element

Here's the code for the Circle constructor:

    // Circle has radius, angle attributes. Content is <color>, <position>
    public Circle(org.w3c.dom.Element xmlElement) {
      super(xmlElement);
      
      double radius = Double.parseDouble(xmlElement.getAttribute("radius")); 
      circle = new Ellipse2D.Double(origin.x, origin.y,     // Position - top-left
                                    2.*radius, 2.*radius ); // Width & height
    }

Compared to the previous two constructors the only change is the last bit where we use the radius attribute value to define the Ellipse2D.Double object representing the circle.

Creating a Curve Element

Before you nod off, this one's a little more challenging as there may be an arbitrary number of child nodes:

    // Curve has angle attribute. Content is <color>, <position>, <point>+
    public Curve(org.w3c.dom.Element xmlElement) {
      super(xmlElement);

      curve = new GeneralPath();
      curve.moveTo(origin.x, origin.y);
      org.w3c.dom.NodeList nodes = xmlElement.getElementsByTagName("point");
      for(int i = 0 ; i<nodes.getLength() ; i++)
        curve.lineTo(
                     (float)(Double.parseDouble(
           ((org.w3c.dom.Element)nodes.item(i)).getAttribute("x")) - position.x),
                     (float)(Double.parseDouble(
           ((org.w3c.dom.Element)nodes.item(i)).getAttribute("y")) - position.y));
    }

Having said that, the first part calls the base class constructor the same as ever. It's more interesting when we get the list of Element nodes with the name "point" by calling getElementsByTagName() for the xmlElement object. These are the nodes holding the coordinates of the points that define the curve. It is important to us here that the method returns the nodes in the NodeList object in the sequence in which they were originally added to the XML document. If it didn't, we would have no way to reconstruct the curve. With the data encapsulated in the nodes from the NodeList object that is returned, we can reconstruct the GeneralPath object that describes the curve. The first point on the curve is always the origin, so the first definition in the path is defined by calling its moveTo() method to move to the origin.

Each of the <point> nodes contains a point on the path in absolute coordinates. Since we want the curve to be defined relative to the origin, we subtract the coordinates of the start point, position, from the corresponding coordinates stored in each node. We use the resulting coordinates to define the end on each line segment by passing them to the lineTo() method for the path object.

Creating a Text Element

Recreating an Element.Text object from a <text> element is the messiest of all. It certainly involves the most code. It's not difficult though. There are just a lot of bits and pieces to take care of.

    // Text has angle attribute. Content is <color>, <position>, <font>, <string>
    // <font> has attributes fontname, fontstyle, pointsize
    // fontstyle is "plain", "bold", "italic", or "bold-italic"
    // <string> content is text plus <bounds>
    public Text(org.w3c.dom.Element xmlElement) {
      super(xmlElement);

      // Get the font details
      org.w3c.dom.NodeList list = xmlElement.getElementsByTagName("font");
      org.w3c.dom.Element fontElement = (org.w3c.dom.Element)list.item(0);
      String styleStr = fontElement.getAttribute("fontstyle");
      int style = 0;
      if(styleStr.equals("plain"))
        style = Font.PLAIN;
      else if(styleStr.equals("bold"))
        style = Font.BOLD;
      else if(styleStr.equals("italic"))
        style = Font.ITALIC;
      else if(styleStr.equals("bold-italic"))
        style = Font.BOLD + Font.ITALIC;
      else
        assert false;
 
      font = new Font(fontElement.getAttribute("fontname"), style,
                      Integer.parseInt(fontElement.getAttribute("pointsize")));    

      // Get string bounds
      list = xmlElement.getElementsByTagName("bounds");
      org.w3c.dom.Element boundsElement = (org.w3c.dom.Element)list.item(0);
      
      this.bounds = new java.awt.Rectangle(origin.x, origin.y,
                          Integer.parseInt(boundsElement.getAttribute("width")),
                          Integer.parseInt(boundsElement.getAttribute("height")));
      
      // Get the string
      list = xmlElement.getElementsByTagName("string");
      org.w3c.dom.Element string = (org.w3c.dom.Element)list.item(0);
      list = string.getChildNodes();

     StringBuffer textStr = new StringBuffer();
     for(int i = 0 ; i<list.getLength() ; i++)
        if(list.item(i).getNodeType()==org.w3c.dom.Node.TEXT_NODE)
          textStr.append(((org.w3c.dom.Text)list.item(i)).getData());

     text = textStr.toString().trim();
   }  

The attributes of the <string> element define the font. Only the fontstyle attribute needs some analysis since we have to represent the style by an integer constant. This means testing for the possible values for the string and setting the appropriate integer value in style. Of course, we could have stored the style as a numeric value, but that would have been meaningless to a human reader. Making the attribute value a descriptor string makes it completely clear. After obtaining the style code we have an assertion to make sure it actually happened. Of course, since the XML was created by Sketcher, the only reasons why this would assert is if there is an error in the code somewhere, or the XML was written by a different version of Sketcher, or the XML was generated by hand. Of course, errors in the XML due to inconsistencies with the DTD would be caught by the parser and signaled by one or other of our ErrorHandler methods.

Text content for an element can appear distributed among several child <Text> nodes. We accommodate this possibilty by concatenating the data from all the child <Text> nodes that we find, and then trimming any leading and trailing white space from the string before storing it in text.

That's all the code we need. You now need to make sure all the imports are in place for the source files we have modified. In addition to what was already there, the Element.java file needs:

import org.w3c.dom.Document;
import org.w3c.dom.Attr;

The SketchFrame.java file needs the following import statements added to the original set:

import java.nio.ByteBuffer;
import java.nio.channels.FileChannel;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.ParserConfigurationException;

You should also have added the following imports to the SketchModel.java file:

import javax.swing.JOptionPane;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.ParserConfigurationException;
import org.w3c.dom.Document;
import org.w3c.dom.DOMImplementation;
import org.w3c.dom.DOMException; 

If everything compiles, you are ready to try exporting and importing sketches.

Try It Out– Sketches in XML

You can try various combinations of elements to see how they look in XML. Be sure to copy the sketcher.dtd file to the directory in which you are storing exported sketches. If you don't, you won't be able to import them since the DTD will not be found. Don't forget you can look at the XML using any text editor and in most browsers. I created the sketch below.

When I exported this I got an XML file with the contents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sketch SYSTEM "sketcher.dtd">
<sketch>
 <circle radius="15.0" angle="0.0">
  <color B="255" G="0" R="0"/>
  <position x="153.0" y="109.0"/>
 </circle>
 <circle radius="18.027756377319946" angle="0.0">
  <color B="255" G="0" R="0"/>
  <position x="217.0" y="123.0"/>
 </circle>
 <circle radius="134.61797799699713" angle="0.0">
  <color B="255" G="0" R="0"/>
  <position x="78.0" y="48.0"/>
 </circle>
 <line angle="0.0">
  <color B="0" G="0" R="255"/>
  <position x="191.0" y="158.0"/>
  <endpoint x="162.0" y="194.0"/>
 </line>
 <line angle="0.0">
  <color B="0" G="0" R="255"/>
  <position x="162.0" y="193.0"/>
  <endpoint x="197.0" y="198.0"/>
 </line>
 <line angle="0.0">
  <color B="0" G="255" R="0"/>
  <position x="185.0" y="94.0"/>
  <endpoint x="137.0" y="104.0"/>
 </line>
 <line angle="0.0">
  <color B="0" G="255" R="0"/>
  <position x="246.0" y="110.0"/>
  <endpoint x="285.0" y="166.0"/>
 </line>
 <curve angle="0.0">
  <color B="0" G="0" R="255"/>
  <position x="132.0" y="224.0"/>
  <point x="132.0" y="223.0"/>
  <point x="133.0" y="222.0"/>
  <point x="134.0" y="222.0"/>
  <point x="137.0" y="222.0"/>
  <!-- points cut here for the sake of brevity -->
  <point x="211.0" y="245.0"/>
  <point x="212.0" y="245.0"/>
  <point x="213.0" y="245.0"/>
  <point x="214.0" y="245.0"/>
 </curve>
 <text angle="0.3183694064160789">
  <color B="0" G="255" R="0"/>
  <position x="42.0" y="283.0"/>
  <font fontname="Comic Sans MS" fontstyle="bold-italic" pointsize="18"/>
  <string>
   <bounds width="271" height="21"/>
   The Complete Set! &quot;Try it out&quot;
  </string>
 </text>
</sketch>

This file is also available as sketchexample.xml in the code download for this book from the Wrox Press web site, http://www.wrox.com. You could try importing it into Sketcher and see if you get the same sketch.