//============================================================================== // DocumentIterator.java //============================================================================== package tribble.repository; import java.io.Closeable; import java.io.IOException; import java.lang.Exception; import java.lang.String; import java.lang.UnsupportedOperationException; import java.util.Iterator; /******************************************************************************* * Abstract generic document set iterator. * *

* A repository document set is a collection of zero or more * repository documents residing within a document folder on a * document repository. Such a set is typically the result of a query * performed on a repository. A document set iterator allows for * a first-to-last iteration over the documents contained within the set. * *

* Note: This requires Java 1.5 or later. * * *

*
Source code:
*
* http://david.tribble.com/src/java/tribble/repository/DocumentIterator.java *
*
Documentation:
*
* http://david.tribble.com/docs/tribble/repository/DocumentIterator.html *
*
* * * @version API 3.0, $Revision: 1.2 $ $Date: 2012/03/17 23:01:02 $ * @since 2008-04-09 * @author David R. Tribble (david@tribble.com)
* Copyright ©2008-2012 by David R. Tribble, all rights reserved.
* Permission is granted to any person or entity except those designated * by the United States Department of State as a terrorist or terrorist * government or agency, to use and distribute this source code provided * that the original copyright notice remains present and unaltered. * * @see AbstractDocumentIterator * @see RepositoryReader */ public interface DocumentIterator extends java.util.Iterator, java.io.Closeable { static final String REV = "@(#)tribble/repository/DocumentIterator.java $Revision: 1.2 $ $Date: 2012/03/17 23:01:02 $\n"; // ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ // Methods /*************************************************************************** * Close this document set iterator. * Deallocates all resources associated with the document set. Any further * use of this object will result in exceptions. * *

* Note that this method does not throw any exceptions. * *

* Implementations may allow this method to be called more than once. * * @since API 2.0, 2008-04-09 */ //@Override public abstract void close(); /*************************************************************************** * Determine if there are any more documents within the document set. * * @return * True if one or more documents remain within the document set, false * otherwise. * * @throws IOException * Thrown if an error occurred while accessing the document * iterator. * * @since API 2.0, 2008-04-09 */ //@Override public abstract boolean hasNext(); /*************************************************************************** * Retrieve the next document within the document set, and advance the * iterator to the next document in the set. * *

* Note that this method also removes the previous document from the document * set (but not from the repository itself), so calling * {@link #remove remove()} is not necessary. * Note also that removed documents do not have their * {@link Document#close close()} methods called, which could leave * them in an unstable state. Callers of this method should therefore call * the close() method explicitly for each document returned. * * @return * The next repository document in the set. * * @since API 2.0, 2008-04-09 */ //@Override public abstract DocType next(); /*************************************************************************** * Remove the current document from the document set (but not from the * repository itself). * *

* Note that calling this method is not necessary, since {@link #next()} * automatically removes each document it previously returned. * Note also that removed documents do not have their * {@link Document#close close()} methods called, which could leave * them in an unstable state. * * @throws UnsupportedOperationException (unchecked) * Thrown if this operation is not supported by this iterator. * * @throws IllegalStateException (unchecked) * Thrown if {@link #next} has not been called, or if {@link #remove} has * already been called on the same item in the set. * * @since API 2.0, 2008-04-09 */ //@Override public abstract void remove() throws UnsupportedOperationException, IllegalStateException; /*************************************************************************** * Retrieve the repository folder for this document set iterator. * * @return * The parent repository folder for this iterator, or null if it does not * have one. * * @throws IOException * Thrown if an error occurred while accessing the document. * * @since API 3.0, 2012-02-16 */ public abstract Folder getFolder() throws IOException; } // End DocumentIterator.java