Download FAQ History |  | API Search Feedback

> ## Displaying a DOM Hierarchy

> To create a Document Object Hierarchy (DOM) or manipulate one, it helps to have a clear idea of how the 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 you 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 at 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 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 application 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 application is to create the class constructor and make it create the panel's contents. Here is the constructor:

>     public class DomEcho02 extends JPanel
>     {
>       ...
>       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` 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 application. 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 8-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 as an inner class:

>     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
>       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.)

> Next, 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 application 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 application 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 application. 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.

Download FAQ History |  | API Search Feedback

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.