The Comment Class

The org.jdom.Comment class represents an XML comment such as <-- Remember to verify this --> . As you can see from Example 15.15, Comment is a very simple class that contains some string data, the usual getParent() and getDocument() methods, and the customary Java utility methods such as equals() and toString() .

Example 15.15 The JDOM Comment Class

 package org.jdom; public class Comment implements Serializable, Cloneable {   protected String text;   protected Object parent;   protected Comment();   public Comment(String text);   public Element    getParent();   protected Comment setParent(Element parent);   public Comment    detach();   public Document   getDocument();   protected Comment setDocument(Document document);   public String     getText();   public Comment    setText(String text);   public       String  toString();   public final boolean equals(Object ob);   public final int     hashCode();   public       Object  clone(); } 

For example, the following code fragment adds the comment <--An example from Chapter 15 of Processing XML with Java--> at the top of the Document object doc :

 Comment comment = new Comment(   "An example from Chapter 15 of Processing XML with Java"); List content = doc.getContent(); content.add(0, comment); 

As with the other JDOM node classes, JDOM does attempt to verify that any data you supply for a Comment is well- formed . There are really only two constraints that matter for comments:

• The comment must not contain any illegal characters such as a null or a vertical tab.

• The comment must not contain the double hyphen -- that signals the end of the comment.

JDOM checks both of them.

There's not a lot you can do with comments, nor is there a lot you should do with them. Comments are intended purely as a convenience for human authors. Programs really shouldn't consider them or attempt to parse their contents. The only reason they're in the API at all is to support round-tripping between the document that's read and the document that's written. Thus the examples are going to be fairly simple.

Earlier in Examples 7.12 and 11.20, you saw SAX and DOM programs that printed the comments in an XML document on System.out . Now in Example 15.16 you can see the JDOM equivalent. The pattern is very much the same as in the DOM version, recursively descending the tree looking for objects of type Comment . However, the detailed classes are different.

Example 15.16 Printing Comments

 import org.jdom.*; import org.jdom.input.SAXBuilder; import java.util.*; import java.io.IOException; public class JDOMCommentReader {   public static void main(String[] args) {     if (args.length <= 0) {       System.out.println("Usage: java JDOMCommentReader url");       return;     }     SAXBuilder builder = new SAXBuilder();     try {       // Read the entire document into memory       Document doc = builder.build(args[0]);       List content = doc.getContent();       Iterator iterator = content.iterator();       while (iterator.hasNext()) {         Object o = iterator.next();         if (o instanceof Comment) {           Comment c = (Comment) o;           System.out.println(c.getText());           System.out.println();         }         else if (o instanceof Element) {           processElement((Element) o);         }       }     }     catch (JDOMException e) {       System.err.println(e);     }     catch (IOException e) {       System.err.println(e);     }   } // end main   // note use of recursion   public static void processElement(Element element) {     List content = element.getContent();     Iterator iterator = content.iterator();     while (iterator.hasNext()) {       Object o = iterator.next();       if (o instanceof Comment) {         Comment c = (Comment) o;         System.out.println(c.getText());         System.out.println();       }       else if (o instanceof Element) {         processElement((Element) o);       }     } // end while   } } 

Following is the result of running this program on the XLink specification:

 %  java JDOMCommentReader   http://www.w3.org/TR/2001/REC-xlink-20010627/Overview.xml  Last edited: 19 December 2000 by elm TO DO: - Point to the linking/style Note if it gets published in time http://www.w3.org/TR/2000/CR-xlink-20000703/ http://www.w3.org/TR/WD-xlink-20000221 http://www.w3.org/TR/WD-xlink-20000119 http://www.w3.org/TR/WD-xlink-19991220 http://www.w3.org/1999/07/WD-xlink-19990726 http://www.w3.org/TR/1998/WD-xlink-19980303 http://www.w3.org/TR/WD-xml-link-970731