mmidy 00/11/30 10:28:23
Modified: java/src/org/apache/xalan/transformer KeyIterator.java
KeyManager.java KeyRefIterator.java KeyTable.java
KeyWalker.java
Log:
Update javadoc
Revision Changes Path
1.8 +25 -20
xml-xalan/java/src/org/apache/xalan/transformer/KeyIterator.java
Index: KeyIterator.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/transformer/KeyIterator.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- KeyIterator.java 2000/11/30 16:26:48 1.7
+++ KeyIterator.java 2000/11/30 18:28:19 1.8
@@ -77,7 +77,10 @@
/**
* <meta name="usage" content="internal"/>
- * NEEDSDOC Class KeyIterator <needs-comment/>
+ * This class implements an optimized iterator for
+ * "key()" patterns. This iterator incrementally walks the
+ * source tree and finds all the nodes that match
+ * a given key name and match pattern.
*/
public class KeyIterator extends LocPathIterator
{
@@ -85,7 +88,7 @@
/** The key table this iterator is associated to */
private KeyTable m_keyTable;
- /** NEEDSDOC Field m_name */
+ /** Key name */
private QName m_name;
/**
@@ -95,24 +98,24 @@
private boolean m_lookForMoreNodes = true;
/**
- * NEEDSDOC Method getName
+ * Get the key name from a key declaration this iterator will process
*
*
- * NEEDSDOC (getName) @return
+ * @return Key name
*/
public QName getName()
{
return m_name;
}
- /** NEEDSDOC Field m_keyDeclarations */
+ /** Vector of Key declarations in the stylesheet */
private Vector m_keyDeclarations;
/**
- * NEEDSDOC Method getKeyDeclarations
+ * Get the key declarations from the stylesheet
*
*
- * NEEDSDOC (getKeyDeclarations) @return
+ * @return Vector containing the key declarations from the stylesheet
*/
public Vector getKeyDeclarations()
{
@@ -123,11 +126,11 @@
* Constructor KeyIterator
*
*
- * NEEDSDOC @param doc
- * NEEDSDOC @param nscontext
- * NEEDSDOC @param name
- * NEEDSDOC @param keyDeclarations
- * NEEDSDOC @param xctxt
+ * @param doc The document node
+ * @param nscontext The prefix resolver for the execution context.
+ * @param name The key name
+ * @param keyDeclarations The key declarations from the stylesheet
+ * @param xctxt The XPath runtime state
*/
public KeyIterator(Node doc, PrefixResolver nscontext, QName name,
Vector keyDeclarations, XPathContext xctxt)
@@ -145,11 +148,13 @@
}
/**
- * NEEDSDOC Method nextNode
+ * Returns the next node in the set and advances the position of the
+ * iterator in the set. After a NodeIterator is created, the first call
+ * to nextNode() returns the first node in the set.
+ *
+ * @return The next <code>Node</code> in the set being iterated over, or
+ * <code>null</code> if there are no more members in that set.
*
- *
- * NEEDSDOC (nextNode) @return
- *
* @throws DOMException
*/
public Node nextNode() throws DOMException
@@ -164,10 +169,10 @@
}
/**
- * NEEDSDOC Method setLookupKey
+ * Set the value of the key that this iterator will look for
*
*
- * NEEDSDOC @param lookupKey
+ * @param lookupKey value of the key to look for
*/
public void setLookupKey(String lookupKey)
{
@@ -194,10 +199,10 @@
}
/**
- * Add this ref to the refsTable in KeyTable
+ * Add this value(ref) to the refsTable in KeyTable
*
*
- * @param ref Key ref(from key use field)
+ * @param ref Key value(ref)(from key use field)
* @param node Node matching that ref
*/
void addRefNode(String ref, Node node)
1.9 +6 -6
xml-xalan/java/src/org/apache/xalan/transformer/KeyManager.java
Index: KeyManager.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/transformer/KeyManager.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- KeyManager.java 2000/11/30 09:57:38 1.8
+++ KeyManager.java 2000/11/30 18:28:20 1.9
@@ -82,13 +82,13 @@
/**
* Given a valid element key, return the corresponding node list.
*
- * NEEDSDOC @param xctxt
- * NEEDSDOC @param doc
- * NEEDSDOC @param name
- * NEEDSDOC @param ref
- * NEEDSDOC @param nscontext
+ * @param xctxt The XPath runtime state
+ * @param doc The document node
+ * @param name The key element name
+ * @param ref The key value we're looking for
+ * @param nscontext The prefix resolver for the execution context
*
- * NEEDSDOC ($objectName$) @return
+ * @return A nodelist of nodes mathing the given key
*
* @throws javax.xml.transform.TransformerException
*/
1.2 +6 -6
xml-xalan/java/src/org/apache/xalan/transformer/KeyRefIterator.java
Index: KeyRefIterator.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/transformer/KeyRefIterator.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- KeyRefIterator.java 2000/11/30 16:26:48 1.1
+++ KeyRefIterator.java 2000/11/30 18:28:20 1.2
@@ -68,7 +68,10 @@
/**
* <meta name="usage" content="internal"/>
- * NEEDSDOC Class KeyIterator <needs-comment/>
+ * This class implements an optimized iterator for
+ * "key()" patterns. It uses a KeyIterator to walk the
+ * source tree and incrementally build a list of nodes that match
+ * a given key name, match pattern and value.
*/
public class KeyRefIterator extends LocPathIterator
{
@@ -99,11 +102,8 @@
* Constructor KeyRefIterator
*
*
- * NEEDSDOC @param doc
- * NEEDSDOC @param nscontext
- * NEEDSDOC @param name
- * NEEDSDOC @param keyDeclarations
- * NEEDSDOC @param xctxt
+ * @param ref Key value to match
+ * @param ki The main key iterator used to walk the source tree
*/
public KeyRefIterator(String ref, KeyIterator ki)
{
1.8 +35 -27
xml-xalan/java/src/org/apache/xalan/transformer/KeyTable.java
Index: KeyTable.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/transformer/KeyTable.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- KeyTable.java 2000/11/30 16:26:48 1.7
+++ KeyTable.java 2000/11/30 18:28:20 1.8
@@ -95,32 +95,36 @@
private Node m_docKey;
/**
- * NEEDSDOC Method getDocKey
+ * Get the document root matching this key.
*
*
- * NEEDSDOC (getDocKey) @return
+ * @return the document root matching this key
*/
public Node getDocKey()
{
return m_docKey;
}
+ /**
+ * The main iterator that will walk through the source
+ * tree for this key.
+ */
+ private KeyIterator m_keyIter;
+
/**
* Hashtable of keys.
* The table is:
- * a) keyed by name,
- * b) with a value that is a KeyIterator.
+ * a) keyed by key name,
+ * b) with a value that is a hashtable keyed by key values
+ * with at value of KeyRefIterator(cloned).
*/
- private KeyIterator m_keyIter;
-
- private Hashtable defsTable;
+ private Hashtable m_defsTable;
/**
* Build a keys table.
- * @param doc The owner document key (normally the same as startNode).
- * @param startNode The node to start itterating from to build the keys
index.
+ * @param doc The owner document key.
* @param nscontext The stylesheet's namespace context.
- * NEEDSDOC @param name
+ * @param name The key name
* @param keyDeclarations The stylesheet's xsl:key declarations.
* @param xmlLiaison The parser liaison for support of
getNodeData(useNode).
*
@@ -135,13 +139,12 @@
m_keyIter = new KeyIterator(doc, nscontext, name, keyDeclarations,
xmlLiaison);
m_keyIter.setKeyTable(this);
- } // end buildKeysTable method
+ }
/**
* Given a valid element key, return the corresponding node list.
+ *
* @param The name of the key, which must match the 'name' attribute on
xsl:key.
- *
- * @param name The name of the key
* @param ref The value that must match the value found by the 'match'
attribute on xsl:key.
* @return If the name was not declared with xsl:key, this will return
null,
* if the identifier is not found, it will return null,
@@ -154,14 +157,17 @@
KeyRefIterator kiRef;
Hashtable refsTable = null;
- if (defsTable != null)
+ // First look for the key in the existing key names table
+ if (m_defsTable != null)
{
- refsTable = (Hashtable)defsTable.get(name);
+ refsTable = (Hashtable)m_defsTable.get(name);
if (refsTable != null)
{
Object kiObj = refsTable.get(ref);
if (kiObj != null)
{
+ // An entry already exists for this key name and value.
+ // Return a clone of the node iterator found.
try
{
// clone with reset??
@@ -176,9 +182,10 @@
}
}
+ // No entry was found for this key name and value. Create one.
{
- if (defsTable == null)
- defsTable = new Hashtable();
+ if (m_defsTable == null)
+ m_defsTable = new Hashtable();
if (refsTable == null)
refsTable = new Hashtable();
@@ -189,16 +196,16 @@
((KeyWalker)m_keyIter.getFirstWalker()).m_lookupKey = ref;
kiRef = new KeyRefIterator(ref, m_keyIter);
refsTable.put(ref, kiRef);
- defsTable.put(name,refsTable);
+ m_defsTable.put(name,refsTable);
return kiRef;
}
}
/**
- * NEEDSDOC Method getKeyTableName
+ * Get Key Name for this KeyTable
*
*
- * NEEDSDOC (getKeyTableName) @return
+ * @return Key name
*/
public QName getKeyTableName()
{
@@ -206,8 +213,9 @@
}
/**
- * Add this ref to the refsTable
- *
+ * Add this node to the nodelist matching this key value.
+ * If there was no existing entry for that key value, create
+ * one.
*
* @param ref Key ref(from key use field)
* @param node Node matching that ref
@@ -216,9 +224,9 @@
{
KeyRefIterator kiRef = null;
Hashtable refsTable = null;
- if (defsTable != null)
+ if (m_defsTable != null)
{
- refsTable = (Hashtable)defsTable.get(getKeyTableName());
+ refsTable = (Hashtable)m_defsTable.get(getKeyTableName());
if (refsTable != null)
{
Object kiObj = refsTable.get(ref);
@@ -230,12 +238,12 @@
}
if (kiRef == null)
{
- if (defsTable == null)
- defsTable = new Hashtable();
+ if (m_defsTable == null)
+ m_defsTable = new Hashtable();
if (refsTable == null)
{
refsTable = new Hashtable();
- defsTable.put(getKeyTableName(),refsTable);
+ m_defsTable.put(getKeyTableName(),refsTable);
}
kiRef = new KeyRefIterator(ref, m_keyIter);
refsTable.put(ref, kiRef);
1.10 +16 -10
xml-xalan/java/src/org/apache/xalan/transformer/KeyWalker.java
Index: KeyWalker.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/transformer/KeyWalker.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- KeyWalker.java 2000/11/30 16:26:49 1.9
+++ KeyWalker.java 2000/11/30 18:28:20 1.10
@@ -77,7 +77,7 @@
/**
* <meta name="usage" content="internal"/>
- * NEEDSDOC Class KeyWalker <needs-comment/>
+ * Walker for a Key() function.
*/
public class KeyWalker extends DescendantOrSelfWalker
{
@@ -85,7 +85,7 @@
/**
* Construct a KeyWalker using a LocPathIterator.
*
- * NEEDSDOC @param locPathIterator
+ * @param locPathIterator: this is usually a KeyIterator
*/
public KeyWalker(LocPathIterator locPathIterator)
{
@@ -95,7 +95,7 @@
/**
* Set the root node of the TreeWalker.
*
- * NEEDSDOC @param root
+ * @param root Document root node
*/
public void setRoot(Node root)
{
@@ -107,22 +107,22 @@
super.setRoot(root);
}
- /** NEEDSDOC Field m_attrs */
+ /** List of attribute nodes of the current node */
NamedNodeMap m_attrs;
- /** NEEDSDOC Field m_foundAttrs */
+ /** Flag indicating that attibute nodes were found for the current node
*/
boolean m_foundAttrs;
- /** NEEDSDOC Field m_attrPos */
+ /** Current position in the attribute nodes list */
int m_attrPos;
- /** NEEDSDOC Field m_lookupKey */
+ /** Key value that this is looking for */
String m_lookupKey;
/**
* Get the next node in document order on the axes.
*
- * NEEDSDOC ($objectName$) @return
+ * @return The next node found or null.
*/
protected Node getNextNode()
{
@@ -158,9 +158,9 @@
* TreeWalker or NodeIterator. This function will be called by the
* implementation of TreeWalker and NodeIterator; it is not intended to
* be called directly from user code.
- * @param n The node to check to see if it passes the filter or not.
+ *
+ * @param testnode The node to check to see if it passes the filter or
not.
*
- * NEEDSDOC @param testNode
* @return a constant to determine whether the node is accepted,
* rejected, or skipped, as defined above .
*/
@@ -183,6 +183,8 @@
{
KeyDeclaration kd = (KeyDeclaration) keys.elementAt(i);
+ // Only continue if the name on this key declaration
+ // matches the name on the iterator for this walker.
if(!kd.getName().equals(name))
continue;
@@ -256,12 +258,16 @@
* current node has no next node, or if the search for nextNode attempts
* to step upward from the TreeWalker's root node, returns
* <code>null</code> , and retains the current node.
+ *
* @return The new node, or <code>null</code> if the current node has no
* next node in the TreeWalker's logical view.
*/
public Node nextNode()
{
Node node = super.nextNode();
+ // If there is no next node, we have walked the whole source tree.
+ // Notify the iterator of that so that its callers know that there
+ // are no more nodes to be found.
if (node == null)
((KeyIterator)m_lpi).setLookForMoreNodes(false);
return node;
