svn commit: r153051 - jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/Path.java

[sk...@apache.org]

Author: skitching
Date: Wed Feb  9 04:14:07 2005
New Revision: 153051

URL: http://svn.apache.org/viewcvs?view=rev&rev=153051
Log:
* add stacks to store namespace and localName for each xml element in the path as they are pushed.
* add access methods to get namespace/localName info for prior xml elements, esp. for the parent
  of the current xml element.
* add lots of javadoc

Modified:
    jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/Path.java

Modified: jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/Path.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/Path.java?view=diff&r1=153050&r2=153051
==============================================================================
--- jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/Path.java (original)
+++ jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/Path.java Wed Feb  9 04:14:07 2005
@@ -23,12 +23,55 @@
  */
 
 public class Path {
-    StringBuffer buf = new StringBuffer();
-    ArrayStack lengths = new ArrayStack();
+    /**
+     * Contains a string of form "/foo/{ns1}bar/baz" which describes the
+     * complete path from the root of the document to the current element.
+     */
+    private StringBuffer buf = new StringBuffer();
     
+    /**
+     * Contains offsets into the "buf" buffer. As new elements are added to
+     * the path, the old buffer length is stored so that it is easy to
+     * restore the old path when an element is "popped" from the path.
+     * Note that namespaces may have forward-slashes in them, so simply
+     * performing string scans to "remove" an element from the path is
+     * not effective.
+     * <p>
+     * Note that this could be recomputed from the information present
+     * in the namespaces and localNames stacks, but that would be very
+     * inefficient.
+     */
+    private ArrayStack lengths = new ArrayStack();
+    
+    /**
+     * The namespaces of the elements found so far. This stack is correlated
+     * with the localNames stack; they always have the same number of 
+     * elements and entries with the same stack offset are a (namespace, name)
+     * pair.
+     */
+    private ArrayStack namespaces = new ArrayStack();
+
+    /**
+     * The localnames of the elements found so far. This stack is correlated
+     * with the namespaces stack; they always have the same number of 
+     * elements and entries with the same stack offset are a (namespace, name)
+     * pair.
+     */
+    private ArrayStack localNames = new ArrayStack();
+    
+    /**
+     * Create a new initial path. Note that this does not represent
+     * "the root of a document", but rather "no path". It should not
+     * be used until the push method has been called for the first
+     * time, to define the root element of the document.
+     */
     public Path() {
     }
     
+    /**
+     * Expand the path to include the specified child element.
+     */
+    
     public void push(String namespace, String elementName) {
         lengths.push(new Integer(buf.length()));
         buf.append("/");
@@ -38,20 +81,65 @@
             buf.append('}');
         }
         buf.append(elementName);
+        
+        namespaces.push(namespace);
+        localNames.push(elementName);
     }
     
+    /**
+     * Remove the last-pushed element, restoring the path to its
+     * previous state.
+     */
     public void pop() {
         int length = ((Integer)lengths.pop()).intValue();
         buf.setLength(length);
+        
+        namespaces.pop();
+        localNames.pop();
     }
     
+    /**
+     * Return the path to the current element.
+     */
     public String getPath() {
         return buf.toString();
     }
+
+    /**
+     * Returns the number of xml elements currently in the path.
+     */
+    public int getDepth() {
+        return namespaces.size();
+    }
+    
+    /**
+     * Returns the namespace of the element at the specified offset from
+     * the top of the stack. An offset of zero returns the most recently
+     * pushed element, while an offset of getDepth()-1 returns the first
+     * pushed element.
+     */
+    public String peekNamespace(int offset) {
+        return (String) namespaces.peek(offset);
+    }
+    
+    /**
+     * Returns the localname of the element at the specified offset from
+     * the top of the stack. An offset of zero returns the most recently
+     * pushed element, while an offset of getDepth()-1 returns the first
+     * pushed element.
+     */
+    public String peekLocalname(int offset) {
+        return (String) localNames.peek(offset);
+    }
     
+    /**
+     * Reset this object to its initially-constructed state.
+     */
     public void clear() {
         buf.setLength(0);
         lengths.clear();
+        namespaces.clear();
+        localNames.clear();
     }
 }
 



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org