jkesselm 01/04/06 09:11:14
Modified: java/src/org/apache/xml/utils Tag: DTM_EXP DTMIterator.java
Log:
Javadoc clarifications/issues
Revision Changes Path
No revision
No revision
1.1.2.2 +69 -35 xml-xalan/java/src/org/apache/xml/utils/DTMIterator.java
Index: DTMIterator.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xml/utils/DTMIterator.java,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- DTMIterator.java 2001/04/03 21:07:20 1.1.2.1
+++ DTMIterator.java 2001/04/06 16:11:11 1.1.2.2
@@ -57,8 +57,10 @@
package org.apache.xml.utils;
/**
- * <code>Iterators</code> are used to step through a set of nodes.
- * It is modeled largely after the DOM NodeIterator.
+
+ * <code>DTMIterators</code> are used to step through a (possibly
+ * filtered) set of nodes. Their API is modeled largely after the DOM
+ * NodeIterator.
*
* <p>A DTMIterator is a somewhat unusual type of iterator, in that it
* can serve both single node iteration and random access.</p>
@@ -71,12 +73,19 @@
* <p>A DTMIterator is meant to be created once as a master static object,
and
* then cloned many times for runtime use. Or the master object itself may
* be used for simpler use cases.</p>
- * <p>State: In progress!!</p>
- */
+ *
+ * <p>At this time, we do not expect DTMIterator to emulate
+ * NodeIterator's "maintain relative position" semantics under
+ * document mutation. It's likely to respond more like the
+ * TreeWalker's "current node" semantics. However, since the base DTM
+ * is immutable, this issue currently makes no practical
+ * difference.</p>
+ *
+ * <p>State: In progress!!</p> */
public interface DTMIterator
{
- // Constants returned by acceptNode
+ // Constants returned by acceptNode, borrowed from the DOM Traversal
chapter
/**
* Accept the node.
@@ -84,7 +93,9 @@
public static final short FILTER_ACCEPT = 1;
/**
- * Reject the node. (same as FILTER_SKIP).
+ * Reject the node. Same behavior as FILTER_SKIP. (In the DOM these
+ * differ when applied to a TreeWalker but have the same result when
+ * applied to a NodeIterator).
*/
public static final short FILTER_REJECT = 2;
@@ -95,11 +106,13 @@
/**
* Set the environment in which this iterator operates, which should
provide:
- * a node (the context node... same value as "root" defined below)
- * a pair of non-zero positive integers (the context position and the
context size)
- * a set of variable bindings
- * a function library
- * the set of namespace declarations in scope for the expression.
+ * <ul>
+ * <li>a node (the context node... same value as "root" defined below)
</li>
+ * <li>a pair of non-zero positive integers (the context position and the
context size) </li>
+ * <li>a set of variable bindings </li>
+ * <li>a function library </li>
+ * <li>the set of namespace declarations in scope for the expression.</li>
+ * <ul>
*
* <p>At this time the exact implementation of this environment is
application
* dependent. Probably a proper interface will be created fairly soon.</p>
@@ -113,6 +126,8 @@
* iterator may be passed without a DTMManager, this allows the
* caller to easily get the DTM using just the iterator.
*
+ * TODO: Do we really need this, given getDTMManager()?
+ *
* @param nodeHandle the nodeHandle.
*
* @return a non-null DTM reference.
@@ -132,25 +147,27 @@
/**
* The root node of the <code>DTMIterator</code>, as specified when it
* was created. Note the root node is not the root node of the
- * document tree, but the context node from where the itteration
- * begins.
+ * document tree, but the context node from where the iteration
+ * begins and ends.
*
* @return nodeHandle int Handle of the context node.
*/
public int getRoot();
/**
- * The root node of the <code>DTMIterator</code>, as specified when it
- * was created. Note the root node is not the root node of the
- * document tree, but the context node from where the itteration
- * begins.
+ * Reset the root node of the <code>DTMIterator</code>, overriding
+ * the value specified when it was created. Note the root node is
+ * not the root node of the document tree, but the context node from
+ * where the itteration begins.
*
* @param nodeHandle int Handle of the context node.
*/
public void setRoot(int nodeHandle);
/**
- * Reset the iterator to the start.
+ * Reset the iterator to the start. After resetting, the next node returned
+ * will be the root node -- or, if that's filtered out, the first node
+ * within the root's subtree which is _not_ skipped by the filters.
*/
public void reset();
@@ -161,25 +178,28 @@
* <code>whatToShow</code> will be skipped, but their children may still
* be considered.
*
- * @return one of the SHOW_XXX constants.
+ * @return one of the SHOW_XXX constants, or several ORed together.
*/
public int getWhatToShow();
/**
- * The value of this flag determines whether the children of entity
+ * <p>The value of this flag determines whether the children of entity
* reference nodes are visible to the iterator. If false, they and
* their descendants will be rejected. Note that this rejection takes
- * precedence over <code>whatToShow</code> and the filter.
- * <br>
- * <br> To produce a view of the document that has entity references
+ * precedence over <code>whatToShow</code> and the filter. </p>
+ *
+ * <p> To produce a view of the document that has entity references
* expanded and does not expose the entity reference node itself, use
* the <code>whatToShow</code> flags to hide the entity reference node
* and set <code>expandEntityReferences</code> to true when creating the
* iterator. To produce a view of the document that has entity reference
* nodes but no entity expansion, use the <code>whatToShow</code> flags
* to show the entity reference node and set
- * <code>expandEntityReferences</code> to false.
+ * <code>expandEntityReferences</code> to false.</p>
*
+ * NOTE: In DTM we will generally have fully expanded entity references
+ * when the document tree was built, and thus this flag will have no
effect.
+ *
* @return true if entity references will be expanded.
*/
public boolean getExpandEntityReferences();
@@ -187,8 +207,9 @@
/**
* Returns the next node in the set and advances the position of the
* iterator in the set. After a <code>DTMIterator</code> has setRoot
called,
- * the first call to <code>nextNode()</code> returns the first node in
- * the set.
+ * the first call to <code>nextNode()</code> returns that root or (if it
+ * is rejected by the filters) the first node within its subtree which is
+ * not filtered out.
* @return The next node handle in the set being iterated over, or
* -1 if there are no more members in that set.
*/
@@ -208,11 +229,20 @@
* in the INVALID state. After <code>detach</code> has been invoked,
* calls to <code>nextNode</code> or <code>previousNode</code> will
* raise a runtime exception.
+ *
+ * TODO: This method may not be required in DTMIterator.
+ * It was needed in DOMIterator because data linkages were
+ * established to support the "maintain relative position" semantic
+ * under document mutation... but if DTM decides it doesn't need
+ * that semantic, we probably don't need to worry about this
+ * cleanup. On the other hand, at worst it's a harmless no-op...
*/
public void detach();
/**
- * Get the current node in the iterator.</a>.
+ * Get the current node in the iterator. Note that this differs from
+ * the DOM's NodeIterator, where the current position lies between two
+ * nodes (as part of the maintain-relative-position semantic).
*
* @return The current node handle, or -1.
*/
@@ -234,17 +264,19 @@
* be cached, enabling random access, and giving the ability to do
* sorts and the like. They are not cached by default.
*
+ * TODO: Shouldn't the other random-access methods throw an exception
+ * if they're called on a DTMIterator with this flag set false?
+ *
* @param b true if the nodes should be cached.
*/
public void setShouldCacheNodes(boolean b);
- /**
- * Get the current position, which is one less than
- * the next nextNode() call will retrieve. i.e. if
- * you call getCurrentPos() and the return is 0, the next
- * fetch will take place at index 1.
+ /** Get the current position within the cached list, which is one
+ * less than the next nextNode() call will retrieve. i.e. if you
+ * call getCurrentPos() and the return is 0, the next fetch will
+ * take place at index 1.
*
- * @return The position of the iteration.</a>.
+ * @return The position of the iteration.
*/
public int getCurrentPos();
@@ -252,7 +284,8 @@
* If an index is requested, NodeSet will call this method
* to run the iterator to the index. By default this sets
* m_next to the index. If the index argument is -1, this
- * signals that the iterator should be run to the end.
+ * signals that the iterator should be run to the end and
+ * completely fill the cache.
*
* @param index The index to run to, or -1 if the iterator should be run
* to the end.
@@ -280,7 +313,8 @@
/**
* The number of nodes in the list. The range of valid child node indices
- * is 0 to <code>length-1</code> inclusive.
+ * is 0 to <code>length-1</code> inclusive. Note that this requires running
+ * the iterator to completion, and presumably filling the cache.
*
* @return The number of nodes in the list.
*/
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
