The Java(TM) Web Services Tutorial

The Java^TM Web Services Tutorial

Displaying a DOM Hierarchy

To create a Document Object Hierarchy (DOM) or manipulate one, it helps to have a clear idea of how nodes in a DOM are structured. In this section of the tutorial, you'll expose the internal structure of a DOM.

Echoing Tree Nodes

What you need at this point is a way to expose the nodes in a DOM so can see what it contains. To do that, you'll convert a DOM into a JTreeModel and display the full DOM in a JTree. It's going to take a bit of work, but the end result will be a diagnostic tool you can use in the future, as well as something you can use to learn about DOM structure now.

Convert DomEcho to a GUI App

Since the DOM is a tree, and the Swing JTree component is all about displaying trees, it makes sense to stuff the DOM into a JTree, so you can look it. The first step in that process is to hack up the DomEcho program so it becomes a GUI application.

Note: The code discussed in this section is in DomEcho02.java.

Add Import Statements

Start by importing the GUI components you're going to need to set up the application and display a JTree:
// GUI components and layouts	
import javax.swing.JFrame;	
import javax.swing.JPanel;	
import javax.swing.JScrollPane;	
import javax.swing.JTree; 
 
Later on in the DOM tutorial, we'll going to tailor the DOM display to generate a user-friendly version of the JTree display. When the user selects an element in that tree, you'll be displaying subelements in an adjacent editor pane. So, while we're doing the setup work here, import the components you need to set up a divided view (JSplitPane) and to display the text of the subelements (JEditorPane):
import javax.swing.JSplitPane;	
import javax.swing.JEditorPane; 
 
Add a few support classes you're going to need to get this thing off the ground:
// GUI support classes	
import java.awt.BorderLayout;	
import java.awt.Dimension;	
import java.awt.Toolkit;	
import java.awt.event.WindowEvent;	
import java.awt.event.WindowAdapter; 
 
Finally, import some classes to make a fancy border:
// For creating borders	
import javax.swing.border.EmptyBorder;	
import javax.swing.border.BevelBorder;	
import javax.swing.border.CompoundBorder; 
 
(These are optional. You can skip them and the code that depends on them if you want to simplify things.)

Create the GUI Framework

The next step is to convert the app into a GUI application. To do that, the static main method will create an instance of the main class, which will have become a GUI pane.

Start by converting the class into a GUI pane by extending the Swing JPanel class:
public class DomEcho02 extends JPanel	
{	
   // Global value so it can be ref'd by the tree-adapter	
   static Document document; 	
   ...
 
While you're there, define a few constants you'll use to control window sizes:
public class DomEcho02 extends JPanel	
{	
   // Global value so it can be ref'd by the tree-adapter	
   static Document document; 
 
       static final int windowHeight = 460;	
   static final int leftWidth = 300;	
   static final int rightWidth = 340;	
   static final int windowWidth = leftWidth + rightWidth; 
 
Now, in the main method, invoke a method that will create the outer frame that the GUI pane will sit in:
public static void main(String argv[])	
{	
   ...	
   DocumentBuilderFactory factory ...	
   try {	
      DocumentBuilder builder = factory.newDocumentBuilder();	
      document = builder.parse( new File(argv[0]) );	
      makeFrame();
 
      } catch (SAXParseException spe) {	
      ...
 
Next, you'll need to define the makeFrame method itself. It contains the standard code to create a frame, handle the exit condition gracefully, give it an instance of the main panel, size it, locate it on the screen, and make it visible:
    ...	
} // main
 
public static void makeFrame()	
{	
   // Set up a GUI framework	
   JFrame frame = new JFrame("DOM Echo");	
   frame.addWindowListener(new WindowAdapter() {	
      public void windowClosing(WindowEvent e) 
{System.exit(0);}	
   });
 
       // Set up the tree, the views, and display it all	
   final DomEcho02 echoPanel = new DomEcho02();	
   frame.getContentPane().add("Center", echoPanel );	
   frame.pack();	
   Dimension screenSize = 
Toolkit.getDefaultToolkit().getScreenSize();	
   int w = windowWidth + 10;	
   int h = windowHeight + 10;	
   frame.setLocation(screenSize.width/3 - w/2, 
screenSize.height/2 - h/2);	
   frame.setSize(w, h);	
   frame.setVisible(true)	
} // makeFrame
 
Add the Display Components

The only thing left in the effort to convert the program to a GUI app is create the class constructor and make it create the panel's contents. Here is the constructor:
public class DomEcho02 extends JPane	
{	
   ...	
   static final int windowWidth = leftWidth + rightWidth; 	
   	
   public DomEcho02()	
   {	
   } // Constructor
 
Here, you make use of the border classes you imported earlier to make a regal border (optional):
public DomEcho02()	
{	
   // Make a nice border	
   EmptyBorder eb = new EmptyBorder(5,5,5,5);	
   BevelBorder bb = new BevelBorder(BevelBorder.LOWERED);	
   CompoundBorder cb = new CompoundBorder(eb,bb);	
   this.setBorder(new CompoundBorder(cb,eb));
 
} // Constructor
 
Next, create an empty tree and put it a JScrollPane so users can see its contents as it gets large:
public DomEcho02(	
{	
   ...
 
   // Set up the tree	
   JTree tree = new JTree();
 
      // Build left-side view	
   JScrollPane treeView = new JScrollPane(tree);	
   treeView.setPreferredSize( 	
      new Dimension( leftWidth, windowHeight ));
 
} // Constructor
 
Now create a non-editable JEditPane that will eventually hold the contents pointed to by selected JTree nodes:
public DomEcho02(	
{	
   ....
 
     // Build right-side view	
   JEditorPane htmlPane = new JEditorPane("text/html","");	
   htmlPane.setEditable(false);	
   JScrollPane htmlView = new JScrollPane(htmlPane);	
   htmlView.setPreferredSize( 	
      new Dimension( rightWidth, windowHeight ));
 
}  // Constructor
 
With the left-side JTree and the right-side JEditorPane constructed, create a JSplitPane to hold them:
public DomEcho02()	
{	
   ....
 
      // Build split-pane view	
   JSplitPane splitPane = new JSplitPane( 
JSplitPane.HORIZONTAL_SPLIT,	
                  treeView, htmlView );	
   splitPane.setContinuousLayout( true );	
   splitPane.setDividerLocation( leftWidth );	
   splitPane.setPreferredSize( 	
      new Dimension( windowWidth + 10, windowHeight+10 ));
 
}  // Constructor
 
With this code, you set up the JSplitPane so with a vertical divider. That produces a "horizontal split" between the tree and the editor pane. (More of a horizontal layout, really.) You also set the location of the divider so that the tree got the width it prefers, with the remainder of the window width allocated to the editor pane.

Finally, specify the layout for the panel and add the split pane:
public DomEcho02()	
{	
   ...	
   // Add GUI components	
   this.setLayout(new BorderLayout());	
   this.add("Center", splitPane );	
} // Constructor 
 
Congratulations! The program is now a GUI app. You can run it now to see what the general layout will look like on screen. For reference, here is the completed constructor:
public DomEcho02()	
{	
   // Make a nice border	
   EmptyBorder eb = new EmptyBorder(5,5,5,5);	
   BevelBorder bb = new BevelBorder(BevelBorder.LOWERED);	
   CompoundBorder CB = new CompoundBorder(eb,bb);	
   this.setBorder(new CompoundBorder(CB,eb));	
   // Set up the tree	
   JTree tree = new JTree();	
   // Build left-side view	
   JScrollPane treeView = new JScrollPane(tree);	
   treeView.setPreferredSize( 	
      new Dimension( leftWidth, windowHeight ));	
   // Build right-side view	
   JEditorPane htmlPane = new JEditorPane("text/html","");	
   htmlPane.setEditable(false);	
   JScrollPane htmlView = new JScrollPane(htmlPane);	
   htmlView.setPreferredSize( 	
      new Dimension( rightWidth, windowHeight ));	
   // Build split-pane view	
   JSplitPane splitPane = new JSplitPane(	
      JSplitPane.HORIZONTAL_SPLIT,	
                  treeView, htmlView )	
   splitPane.setContinuousLayout( true );	
   splitPane.setDividerLocation( leftWidth );	
   splitPane.setPreferredSize( 	
      new Dimension( windowWidth + 10, windowHeight+10 ));	
   // Add GUI components	
   this.setLayout(new BorderLayout());	
   this.add("Center", splitPane );	
} // Constructor 
 
Create Adapters to Display the DOM in a JTree

Now that you have a GUI framework to display a JTree in, the next step is get the JTree to display the DOM. But a JTree wants to display a TreeModel. A DOM is a tree, but it's not a TreeModel. So you'll need to create an adapter class that makes the DOM look like a TreeModel to a JTree.

Now, when the TreeModel passes nodes to the JTree, JTree uses the toString function of those nodes to get the text to display in the tree. The standard toString function isn't going to be very pretty, so you'll need to wrap the DOM nodes in an AdapterNode that returns the text we want. What the TreeModel gives to the JTree, then, will in fact be AdapterNode objects that wrap DOM nodes.

Note: The classes that follow are defined as inner classes. If you are coding for the 1.1 platform, you will need to define these class as external classes.

Define the AdapterNode Class

Start by importing the tree, event, and utility classes you're going to need to make this work:
// For creating a TreeModel	
import javax.swing.tree.*;	
import javax.swing.event.*;	
import java.util.*;
 
public class DomEcho extends JPanel	
{  
 
Moving back down to the end of the program, define a set of strings for the node element types:
        ...	
} // makeFrame
 
// An array of names for DOM node-types	
// (Array indexes = nodeType() values.)	
static final String[] typeName = {	
   "none",	
   "Element",	
   "Attr",	
   "Text",	
   "CDATA",	
   "EntityRef",	
   "Entity",	
   "ProcInstr",	
   "Comment",	
   "Document",	
   "DocType",	
   "DocFragment",	
   "Notation",	
};
 
} // DomEcho

These are the strings that will be displayed in the JTree. The specification of these nodes types can be found in the Document Object Model (DOM) Level 2 Core Specification at http://www.w3.org/TR/2000/REC-DOM/Level-2-Core-20001113, under the specification for Node. That table is reproduced below, with the headings modified for clarity, and with the nodeType() column added:

Table 1: Node Types
Node
nodeName()
nodeValue()
attributes
nodeType()

Attr
name of attribute
value of attribute
null
2

CDATASection
#cdata-section
content of the
CDATA Section
null
4

Comment
#comment
content of the comment
null
8

Document
#document
null
null
9

DocumentFragment
#document-fragment
null
null
11

DocumentType
document type name
null
null
10

Element
tag name
null
NamedNodeMap
1

Entity
entity name
null
null
6

EntityReference
name of entity referenced
null
null
5

Notation
notation name
null
null
12

ProcessingInstruction
target
entire content excluding
the target
null
7

Text
#text
content of the text node
null
3

Suggestion:

Print this table and keep it handy. You need it when working with the DOM, because all of these types are intermixed in a DOM tree. So your code is forever asking, "Is this the kind of node I'm interested in?".

Next, define the AdapterNode wrapper for DOM nodes:
static final String[] typeName = {	
   ...	
};
 
public class AdapterNode 	
{ 	
   org.w3c.dom.Node domNode;
 
   // Construct an Adapter node from a DOM node	
   public AdapterNode(org.w3c.dom.Node node) {	
      domNode = node;	
   }
 
   // Return a string that identifies this node in the tree	
   // *** Refer to table at top of org.w3c.dom.Node ***	
   public String toString() {	
      String s = typeName[domNode.getNodeType()];	
      String nodeName = domNode.getNodeName();	
      if (! nodeName.startsWith("#")) {	
         s += ": " + nodeName;	
      }	
      if (domNode.getNodeValue() != null) {	
         if (s.startsWith("ProcInstr")) 	
            s += ", "; 	
         else 	
            s += ": ";	
         // Trim the value to get rid of NL's at the front	
         String t = domNode.getNodeValue().trim();	
         int x = t.indexOf(");	
         if (x >= 0) t = t.substring(0, x);	
         s += t;	
      }	
      return s;	
   }	
   } // AdapterNode
 
} // DomEcho 
 
This class declares a variable to hold the DOM node, and requires it to be specified as a constructor argument. It then defines the toString operation, which returns the node type from the String array, and then adds to that additional information from the node, to further identify it.

As you can see in the table of node types in org.w3c.dom.Node, every node has a type, and name, and a value, which may or may not be empty. In those cases where the node name starts with "#", that field duplicates the node type, so there is in point in including it. That explains the lines that read:
if (! nodeName.startsWith("#")) {	
   s += ": " + nodeName;	
} 
 
The remainder of the toString method deserves a couple of notes, as well. For instance, these lines:
if (s.startsWith("ProcInstr")) 	
   s += ", "; 	
else 	
   s += ": ";
 
Merely provide a little "syntactic sugar". The type field for a Processing Instructions end with a colon (:) anyway, so those codes keep from doubling the colon.

The other interesting lines are:
String t = domNode.getNodeValue().trim();	
int x = t.indexOf(");	
if (x >= 0) t = t.substring(0, x);	
s += t;
 
Those lines trim the value field down to the first newline (linefeed) character in the field. If you leave those lines out, you will see some funny characters (square boxes, typically) in the JTree.

Note: Recall that XML stipulates that all line endings are normalized to newlines, regardless of the system the data comes from. That makes programming quite a bit simpler.

Wrapping a DomNode and returning the desired string are the AdapterNode's major functions. But since the TreeModel adapter will need to answer questions like "How many children does this node have?" and satisfy commands like "Give me this node's Nth child", it will be helpful to define a few additional utility methods. (The adapter could always access the DOM node and get that information for itself, but this way things are more encapsulated.)

Add the code highlighted below to return the index of a specified child, the child that corresponds to a given index, and the count of child nodes:
public class AdapterNode 	
{ 	
   ...	
   public String toString() {	
      ...	
   }
 
   public int index(AdapterNode child) {	
      //System.err.println("Looking for index of " + child);	
      int count = childCount();	
      for (int i=0; i<count; i++) {	
         AdapterNode n = this.child(i);	
         if (child == n) return i;	
      }	
      return -1; // Should never get here.	
   }	
	
   public AdapterNode child(int searchIndex) {	
      //Note: JTree index is zero-based. 	
      org.w3c.dom.Node node =	
         domNode.getChildNodes().item(searchIndex);	
      return new AdapterNode(node); 	
   }	
	
   public int childCount() {	
      return domNode.getChildNodes().getLength(); 	
   }	
} // AdapterNode
 
} // DomEcho
 
Note: During development, it was only after I started writing the TreeModel adapter that I realized these were needed, and went back to add them. In just a moment, you'll see why.

Define the TreeModel Adapter

Now, at last, you are ready to write the TreeModel adapter. One of the really nice things about the JTree model is the relative ease with which you convert an existing tree for display. One of the reasons for that is the clear separation between the displayable view, which JTree uses, and the modifiable view, which the application uses. For more on that separation, see Understanding the TreeModel at http://java.sun.com/products/jfc/tsc/articles/jtree/index.html. For now, the important point is that to satisfy the TreeModel interface we only need to (a) provide methods to access and report on children and (b) register the appropriate JTree listener, so it knows to update its view when the underlying model changes.

Add the code highlighted below to create the TreeModel adapter and specify the child-processing methods:
   ...	
	
} // AdapterNode
 
// This adapter converts the current Document (a DOM) into 	
// a JTree model. 	
public class DomToTreeModelAdapter implements 
javax.swing.tree.TreeModel 	
{	
   // Basic TreeModel operations	
   public Object  getRoot() {	
   //System.err.println("Returning root: " +document);	
   return new AdapterNode(document);	
}	
	
public boolean isLeaf(Object aNode) {	
   // Determines whether the icon shows up to the left.	
   // Return true for any node with no children	
   AdapterNode node = (AdapterNode) aNode;	
   if (node.childCount() > 0) return false;	
   return true;	
}	
public int     getChildCount(Object parent) 	
   AdapterNode node = (AdapterNode) parent;	
   return node.childCount();	
}	
public Object  getChild(Object parent, int index) {	
AdapterNode node = (AdapterNode) parent;	
return node.child(index);	
}	
public int     getIndexOfChild(Object parent, Object child) {	
   AdapterNode node = (AdapterNode) parent;	
   return node.index((AdapterNode) child);	
}	
public void    valueForPathChanged(TreePath path, Object 
newValue) {	
   // Null. We won't be making changes in the GUI	
   // If we did, we would ensure the new value was really new	
   // and then fire a TreeNodesChanged event.	
}	
} // DomToTreeModelAdapter	
} // DomEcho  
 
In this code, the getRoot method returns the root node of the DOM, wrapped as an AdapterNode object. From here on, all nodes returned by the adapter will be AdapterNodes that wrap DOM nodes. By the same token, whenever the JTree asks for the child of a given parent, the number of children that parent has, etc., the JTree will be passing us an AdapterNode. We know that, because we control every node the JTree sees, starting with the root node.

JTree uses the isLeaf method to determine whether or not to display a clickable expand/contract icon to the left of the node, so that method returns true only if the node has children. In this method, we see the cast from the generic object JTree sends us to the AdapterNode object we know it has to be. We know it is sending us an adapter object, but the interface, to be general, defines objects, so we have to do the casts.

The next three methods return the number of children for a given node, the child that lives at a given index, and the index of a given child, respectively. That's all pretty straightforward.

The last method is invoked when the user changes a value stored in the JTree. In this app, we won't support that. But if we did, the app would have to make the change to the underlying model and then inform any listeners that a change had occurred. (The JTree might not be the only listener. In many an application it isn't, in fact.)

To inform listeners that a change occurred, you'll need the ability to register them. That brings us to the last two methods required to implement the TreeModel interface. Add the code highlighted below to define them:
public class DomToTreeModelAdapter ...	
{	
   ...	
   public void    valueForPathChanged(TreePath path, Object 
newValue) {	
      ...	
   }	
   private Vector listenerList = new Vector();	
   public void addTreeModelListener(	
      TreeModelListener listener ) {	
      if ( listener != null && ! listenerList.contains(	
         listener ) ) {	
      listenerList.addElement( listener );	
      }	
   }	
   public void removeTreeModelListener( TreeModelListener	
   listener ) {	
   if ( listener != null ) {	
      listenerList.removeElement( listener );	
      }	
   }	
} // DomToTreeModelAdapter
 
Since this app won't be making changes to the tree, these methods will go unused, for now. However, they'll be there in the future, when you need them.

Note: This example uses Vector so it will work with 1.1 apps. If coding for 1.2 or later, though, I'd use the excellent collections framework instead:
   private LinkedList listenerList = new LinkedList();
 
The operations on the List are then add and remove. To iterate over the list, as in the operations below, you would use:
Iterator it = listenerList.iterator();	
while ( it.hasNext() ) {	
   TreeModelListener listener = (TreeModelListener) it.next();	
      ... 	
}
 
Here, too, are some optional methods you won't be using in this app. At this point, though, you have constructed a reasonable template for a TreeModel adapter. In the interests of completeness, you might want to add the code highlighted below. You can then invoke them whenever you need to notify JTree listeners of a change:
public void removeTreeModelListener( TreeModelListener listener 
) {	
   ...	
} 	
public void fireTreeNodesChanged( TreeModelEvent e ) {	
   Enumeration listeners = listenerList.elements();	
   while ( listeners.hasMoreElements() ) {	
      TreeModelListener listener = (TreeModelListener) 
listeners.nextElement();	
      listener.treeNodesChanged( e );	
   }	
} 	
public void fireTreeNodesInserted( TreeModelEvent e ) {	
   Enumeration listeners = listenerList.elements();	
   while ( listeners.hasMoreElements() ) {	
      TreeModelListener listener = (TreeModelListener) 
listeners.nextElement();	
      listener.treeNodesInserted( e );	
   }	
} 	
public void fireTreeNodesRemoved( TreeModelEvent e ) {	
   Enumeration listeners = listenerList.elements();	
   while ( listeners.hasMoreElements() ) {	
      TreeModelListener listener = (TreeModelListener) 
listeners.nextElement();	
      listener.treeNodesRemoved( e );	
   }	
} 	
public void fireTreeStructureChanged( TreeModelEvent e ) {	
   Enumeration listeners = listenerList.elements();	
   while ( listeners.hasMoreElements() ) {	
      TreeModelListener listener = (TreeModelListener) 
listeners.nextElement();	
      listener.treeStructureChanged( e );	
   }	
}	
} // DomToTreeModelAdapter
 
Note: These methods are taken from the TreeModelSupport class described in Understanding the TreeModel. That architecture was produced by Tom Santos and Steve Wilson, and is a lot more elegant than the quick hack going on here. It seemed worthwhile to put them here, though, so they would be immediately at hand when and if they're needed.

Finishing Up

At this point, you are basically done. All you need to do is jump back to the constructor and add the code to construct an adapter and deliver it to the JTree as the TreeModel:
// Set up the tree	
JTree tree = new JTree(new DomToTreeModelAdapter()); 
 
You can now compile and run the code on an XML file. In the next section, you will do that, and explore the DOM structures that result.

**Table 1: Node Types**
Node	nodeName()	nodeValue()	attributes	nodeType()
Attr	name of attribute	value of attribute	null	2
CDATASection	#cdata-section	content of the CDATA Section	null	4
Comment	#comment	content of the comment	null	8
Document	#document	null	null	9
DocumentFragment	#document-fragment	null	null	11
DocumentType	document type name	null	null	10
Element	tag name	null	NamedNodeMap	1
Entity	entity name	null	null	6
EntityReference	name of entity referenced	null	null	5
Notation	notation name	null	null	12
ProcessingInstruction	target	entire content excluding the target	null	7
Text	#text	content of the text node	null	3

Home
TOC