--- projects/cms/source/util/uk/org/iscream/cms/util/XMLStringParser.java	2000/11/23 09:16:02	1.2
+++ projects/cms/source/util/uk/org/iscream/cms/util/XMLStringParser.java	2001/01/28 05:47:05	1.6
@@ -1,36 +1,57 @@
+//---PACKAGE DECLARATION---
+package uk.ac.ukc.iscream.util;
+
+//---IMPORTS---
 import java.io.*;
 import java.util.ArrayList;
 
 import org.xml.sax.*;
-
 import javax.xml.parsers.SAXParserFactory;
 import javax.xml.parsers.ParserConfigurationException;
 import javax.xml.parsers.SAXParser;
 
-// Paul Mutton, pjm2@ukc.ac.uk
-
-// XMLStringParser - Used to assist in creating XMLPacket objects.
+/**
+ * XMLStringParser - Used to assist in creating XMLPacket objects.
+ *
+ * @author  $Author: tdb $
+ * @version $Id: XMLStringParser.java,v 1.6 2001/01/28 05:47:05 tdb Exp $
+ */
 public class XMLStringParser extends HandlerBase {
 
-    // No-args constructor.  Generally not used.
+//---FINAL ATTRIBUTES---
+
+    /**
+     * The current CVS revision of this class
+     */
+    public final String REVISION = "$Revision: 1.6 $";
+    
+//---STATIC METHODS---
+
+//---CONSTRUCTORS---
+
+    /**
+     * No-args constructor.  Generally not used.
+     */
     public XMLStringParser () {
         this.packet = new XMLPacket();
     }
 
-    // Constructor for accepting a reference to an XMLPacket
+    /**
+     * Constructor for accepting a reference to an XMLPacket
+     */
     public XMLStringParser (XMLPacket packet) {
         this.packet = packet;
     }
 
-    // Accessor to the XMLPacket.
+//---PUBLIC METHODS---
+
+    /**
+     * Accessor to the XMLPacket.
+     */ 
     public XMLPacket getXMLPacket() {
         return packet;
     }
 
-    private int indentLevel = 0;
-    private ArrayList tagList = new ArrayList();
-    private XMLPacket packet;
-
     //===========================================================
     // SAX DocumentHandler methods
     //===========================================================
@@ -43,14 +64,15 @@ public class XMLStringParser extends HandlerBase {
         //System.out.println("XMLPacketParser - I just finished parsing an XML String.");
     }
 
-    // Add each tag's attribute to the XMLPacket.
-    // Note that all attributes within an opening tag are
-    // stored as "someroot.sometag.attributes.attribute_name"
-    // E.g. If <packet> is the root node, then:
-    //     <packet machine_name="raptor">
-    // is stored as:
-    //     "packet.attributes.machine_name"
-    // within the XMLPacket.
+    /** Add each tag's attribute to the XMLPacket.
+     * Note that all attributes within an opening tag are
+     * stored as "someroot.sometag.attributes.attribute_name"
+     * E.g. If <packet> is the root node, then:
+     *     <packet machine_name="raptor">
+     * is stored as:
+     *     "packet.attributes.machine_name"
+     * within the XMLPacket.
+     */
     public void startElement (String name, AttributeList attrs) throws SAXException {
         indentLevel++;
         tagList.add(name);
@@ -61,18 +83,22 @@ public class XMLStringParser extends HandlerBase {
         }
     }
 
-    // When an XML element is finished with, we must remove
-    // the tag name from the tagList and decrement the indent
-    // level.
+    /**
+     * When an XML element is finished with, we must remove
+     * the tag name from the tagList and decrement the indent
+     * level.
+     */
     public void endElement (String name) throws SAXException {
         tagList.remove(tagList.size()-1);    
         indentLevel--;
     }
 
-    // Any text falling within a pair of terminal tags must
-    // be added to the XMLPacket.  Trim leading and trailing
-    // spaces and do not bother to add if there is no data
-    // specified within the tags.
+    /**
+     * Any text falling within a pair of terminal tags must
+     * be added to the XMLPacket.  Trim leading and trailing
+     * spaces and do not bother to add if there is no data
+     * specified within the tags.
+     */
     public void characters (char[] buf, int offset, int len) throws SAXException {
         String s = new String(buf, offset, len);
         if (!s.trim().equals("")) {
@@ -80,14 +106,32 @@ public class XMLStringParser extends HandlerBase {
         }
     }
 
+    /**
+     * Overrides the {@link java.lang.Object#toString() Object.toString()}
+     * method to provide clean logging (every class should have this).
+     *
+     * This uses the uk.ac.ukc.iscream.util.NameFormat class
+     * to format the toString()
+     *
+     * @return the name of this class and its CVS revision
+     */
+    public String toString() {
+        return FormatName.getName(
+            _name,
+            getClass().getName(),
+            REVISION);
+    }
 
+//---PRIVATE METHODS---
+
     //===========================================================
     // Helpers ...
     //===========================================================
     
-    
-    // Return the heirarchical string to be used as a key value
-    // in the XMLPacket.
+    /**
+     * Return the heirarchical string to be used as a key value
+     * in the XMLPacket.
+     */
     private String getPath () {
         String path = (String)tagList.get(0);
         if (tagList.size() > 0) {
@@ -97,5 +141,37 @@ public class XMLStringParser extends HandlerBase {
         }
         return path;
     }
+
+//---ACCESSOR/MUTATOR METHODS---
+
+//---ATTRIBUTES---
+
+    /**
+     * To keep track of our identation level
+     */
+    private int indentLevel = 0;
     
-}
\ No newline at end of file
+    /**
+     * An ArrayList of tags
+     */
+    private ArrayList tagList = new ArrayList();
+    
+    /**
+     * A reference to the XMLPacket we are making
+     */
+    private XMLPacket packet;
+    
+    /**
+     * This is the friendly identifier of the
+     * component this class is running in.
+     * eg, a Filter may be called "filter1",
+     * If this class does not have an owning
+     * component,  a name from the configuration
+     * can be placed here.  This name could also
+     * be changed to null for utility classes.
+     */
+    private String _name = null;
+
+//---STATIC ATTRIBUTES---
+
+}