You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by jk...@apache.org on 2001/05/22 00:18:49 UTC
cvs commit: xml-xalan/java/src/org/apache/xml/dtm DTMAxisIterator.java DTMAxisIteratorBase.java DTMDocumentImpl.java
jkesselm 01/05/21 15:18:47
Modified: java/src/org/apache/xml/dtm Tag: DTM_EXP
DTMAxisIterator.java DTMAxisIteratorBase.java
DTMDocumentImpl.java
Log:
Documentation tweaks
Revision Changes Path
No revision
No revision
1.1.2.2 +3 -10 xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMAxisIterator.java
Index: DTMAxisIterator.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMAxisIterator.java,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- DTMAxisIterator.java 2001/05/20 17:33:26 1.1.2.1
+++ DTMAxisIterator.java 2001/05/21 22:18:40 1.1.2.2
@@ -81,15 +81,12 @@
public DTMAxisIterator reset();
/**
- * Returns the last element in this interation.
- *
- * @return the last element in this interation.
+ * @return the number of nodes in this iterator. This may be an expensive
+ * operation when called the first time.
*/
public int getLast();
/**
- * Returns the position of the current node in the set.
- *
* @return The position of the current node in the set, as defined by XPath.
*/
public int getPosition();
@@ -115,15 +112,11 @@
public DTMAxisIterator setStartNode(int node);
/**
- * True if this iterator has a reversed axis.
- *
- * @return true if this iterator has a reversed axis.
+ * @return true if this iterator has a reversed axis, else false.
*/
public boolean isReverse();
/**
- * Returns a deep copy of this iterator.
- *
* @return a deep copy of this iterator.
*/
public DTMAxisIterator cloneIterator();
1.1.2.2 +62 -35 xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMAxisIteratorBase.java
Index: DTMAxisIteratorBase.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMAxisIteratorBase.java,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- DTMAxisIteratorBase.java 2001/05/20 17:33:26 1.1.2.1
+++ DTMAxisIteratorBase.java 2001/05/21 22:18:41 1.1.2.2
@@ -62,30 +62,41 @@
public abstract class DTMAxisIteratorBase implements DTMAxisIterator
{
- /** The position of the last node in the iteration, as defined by XPath. */
+ /** The position of the last node within the iteration, as defined by XPath.
+ * (Note that this is _not_ the node's handle within the DTM!)
+ */
private int _last = -1;
- /** The position of the current node in the iteration, as defined by XPath. */
+ /** The position of the current node within the iteration, as defined by XPath.
+ * (Note that this is _not_ the node's handle within the DTM!)
+ */
private int _position = 0;
- /** The position of the marked node in the iteration. */
+ /** The position of the marked node within the iteration.
+ * (A saved itaration state that we may want to come back to.)
+ */
protected int _markedNode;
- /** The handle to the start, or root of the iteration. */
+ /** The handle to the start, or root, of the iteration.
+ * Set this to END to construct an empty iterator.
+ */
protected int _startNode = DTMAxisIterator.END;
- /** Flag to tell if the start node should be included in the iteration. */
+ /** True if the start node should be considered part of the iteration.
+ * False will cause it to be skipped.
+ */
protected boolean _includeSelf = false;
- /** Flag to tell if the iterator is restartable. */
+ /** True if this iteration can be restarted. False otherwise (eg, if
+ * we are iterating over a stream that can not be re-scanned, or if
+ * the iterator is a clone.)
+ */
protected boolean _isRestartable = true;
/**
- * Resets the iterator to the last start node.
- *
- * @return A DTMAxisIterator, which may or may not be the same as this
- * iterator.
- */
+ * @return A DTMAxisIterator which has been reset to the start node,
+ * which may or may not be the same as this iterator.
+ * */
public DTMAxisIterator reset()
{
@@ -104,8 +115,10 @@
* Set the flag to include the start node in the iteration.
*
*
- * @return This default method returns just returns itself, after setting the
- * flag.
+ * @return This default method returns just returns this DTMAxisIterator,
+ * after setting the flag.
+ * (Returning "this" permits C++-style chaining of
+ * method calls into a single expression.)
*/
public DTMAxisIterator includeSelf()
{
@@ -115,30 +128,34 @@
return this;
}
- /**
- * Returns the number of elements in this iterator. This may be an expensive
- * operation when called the first time.
+ /** Returns the position of the last node within the iteration, as
+ * defined by XPath. (Note that this is _not_ the node's handle
+ * within the DTM!)
*
- * @return The number of elements in this iterator.
+ * This may be an expensive operation when called the first time, since
+ * it may have to iterate all the way through the subtree.
+ *
+ * @return The number of nodes in this iterator.
*/
public int getLast()
{
- if (_last == -1)
+ if (_last == -1) // Not previously established
{
- final int temp = _position;
+ // %REVIEW% I'm confused about the difference between setMark() and
+ // the local temp variable...?
+ final int temp = _position; // Save state
setMark();
- reset();
+ reset(); // Count the nodes found by this iterator
do
{
_last++;
}
while (next() != END);
-
- gotoMark();
+ gotoMark(); // Restore saved state
_position = temp;
}
@@ -146,9 +163,8 @@
}
/**
- * Returns the position of the current node in the set.
- *
- * @return The position of the current node in the set, as defined by XPath.
+ * @return The position of the current node within the set, as defined by
+ * XPath. Note that this is one-based, not zero-based.
*/
public int getPosition()
{
@@ -156,9 +172,7 @@
}
/**
- * True if this iterator has a reversed axis.
- *
- * @return true if this iterator has a reversed axis.
+ * @return true if this iterator has a reversed axis, else false
*/
public boolean isReverse()
{
@@ -166,7 +180,9 @@
}
/**
- * Returns a deep copy of this iterator.
+ * Returns a deep copy of this iterator. Cloned iterators may not be
+ * restartable, though the original they are cloned from is not
+ * necessarily further restricted by being cloned.
*
* @return a deep copy of this iterator.
*/
@@ -188,16 +204,25 @@
}
/**
- * Simply return the node that is passed in, after incrementing the position.
+ * Do any final cleanup that is required before returning the node that was
+ * passed in, and then return it. The intended use is
+ * <br />
+ * <code>return returnNode(node);</code>
+ *
+ * %REVIEW% If we're calling it purely for side effects, should we really
+ * be bothering with a return value? Something like
+ * <br />
+ * <code> accept(node); return node; </code>
+ * <br />
+ * would probably optimize just about as well and avoid questions
+ * about whether what's returned could ever be different from what's
+ * passed in.
*
+ * @param node Node handle which iteration is about to yield.
*
- * @param node Node handle.
- *
- * @return The node handle passed in.
- */
+ * @return The node handle passed in. */
protected final int returnNode(final int node)
{
-
_position++;
return node;
@@ -205,6 +230,8 @@
/**
* Reset the position to zero.
+ *
+ * %REVIEW% Document how this dffers from reset() and setStartNode().
*
*
* @return This instance.
1.1.2.22 +3 -3 xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMDocumentImpl.java
Index: DTMDocumentImpl.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMDocumentImpl.java,v
retrieving revision 1.1.2.21
retrieving revision 1.1.2.22
diff -u -r1.1.2.21 -r1.1.2.22
--- DTMDocumentImpl.java 2001/05/21 11:44:02 1.1.2.21
+++ DTMDocumentImpl.java 2001/05/21 22:18:42 1.1.2.22
@@ -2319,7 +2319,7 @@
*
* @param axis One of Axes.ANCESTORORSELF, etc.
*
- * @return A DTMAxisIterator, or null if the givin axis isn't supported.
+ * @return A DTMAxisIterator, or null if the given axis isn't supported.
*/
public DTMAxisTraverser getAxisTraverser(final int axis)
{
@@ -2334,7 +2334,7 @@
*
* @param axis One of Axes.ANCESTORORSELF, etc.
*
- * @return A DTMAxisIterator, or null if the givin axis isn't supported.
+ * @return A DTMAxisIterator, or null if the given axis isn't supported.
*/
public DTMAxisIterator getAxisIterator(final int axis)
{
@@ -2350,7 +2350,7 @@
* @param axis
* @param type An extended type ID.
*
- * @return A DTMAxisIterator, or null if the givin axis isn't supported.
+ * @return A DTMAxisIterator, or null if the given axis isn't supported.
*/
public DTMAxisIterator getTypedAxisIterator(final int axis, final int type)
{
---------------------------------------------------------------------
To unsubscribe, e-mail: xalan-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xalan-cvs-help@xml.apache.org