[ZooLib-checkins] CVS: zoolib/java/org/zoolib/tuplebase ZTBIter.java, 1.11, 1.12

[Ben S. L. <car...@us...>]

Update of /cvsroot/zoolib/zoolib/java/org/zoolib/tuplebase
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv19768/java/org/zoolib/tuplebase

Modified Files:
	ZTBIter.java 
Log Message:
Javadoc comments inserted

Index: ZTBIter.java
===================================================================
RCS file: /cvsroot/zoolib/zoolib/java/org/zoolib/tuplebase/ZTBIter.java,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -d -r1.11 -r1.12
--- ZTBIter.java	26 Jul 2007 15:28:43 -0000	1.11
+++ ZTBIter.java	23 Jan 2008 23:52:25 -0000	1.12
@@ -29,8 +29,35 @@
 import org.zoolib.ZTuple;
 import org.zoolib.ZTxn;
 
-// =================================================================================================
-
+/**
+ * Implements the Iterator interface for representing search
+ * results against a tuplebase. Operations involving a ZTBIter instance 
+ * ought to take place in the context of a {@link ZTxn} transaction, 
+ * and the exit status of that transaction ought to be checked or 
+ * else the integrity of the search results will not be guaranteed.
+ * Practically, what this means is that the iterator should be used 
+ * inside a loop which exits upon a the success of {@link ZTxn#commit()}.
+ * On failure, the search performed anew on a new transaction.
+ * <pre>for(;;)
+ * {
+ *   ZTxn theTxn = new ZTxn();
+ *   ZTBIter theIter = new ZTBIter(theTxn,theTB,theQuery);
+ *   while(theIter.hasNext())
+ *   {
+ *   	ZTuple theTuple = theIter.get();
+ *   	... do something ...
+ *   }
+ *   if (theTxn.commit())
+ *   	break; //discard results and start over
+ * }</pre>
+ * 
+ * It's not recommended that you use the Iterator interface, namely 
+ * {@link #hasNext()}, {@link #remove()} and {@link #next()}. The 
+ * ZTBIter API provides accessors for both the current tuple and 
+ * the current ID.
+ * @author Andrew Green
+ *
+ */
 public class ZTBIter implements java.util.Iterator, Cloneable
 	{
 	public ZTBIter(ZTBIter iOther)
@@ -161,11 +188,18 @@
 	// just here in case it's needed. The ZTBIter API provides accessors for
 	// both the current tuple and the current ID.
 
+	/**
+	 * Not recommended. Use {@link #hasValue()} instead.
+	 */
 	public boolean hasNext()
 		{
 		return this.hasValue();
 		}
 
+	/**
+	 * Not recommended. Use {@link #get()} for current ID and
+	 * {@link #advance()} to increment current ID.
+	 */
 	public Object next()
 		{
 		// Perhaps should return a pair of some sort.
@@ -174,6 +208,9 @@
 		return result;
 		}
 
+	/**
+	 * Not supported. Use {@link #erase()} instead.
+	 */
 	public void remove()
 		{
 		throw new UnsupportedOperationException();