Interface that represents a list of documents to be traversed. Documents are accessed through an iterator-like method: {@link #nextDocument()}, which returns the next available {@link Document} or {@code null} if there are no more.
Important: a {@link Document} object obtainedby calling {@link #nextDocument()} is invalidated by the nextcall to {@link #nextDocument()}. Typically, the caller will store the current Document in a loop variable, so that it is clear that this rule is observed; see the example code below.
In addition, a this interface has a special method {@link #checkpoint()}, which produces a String that encapsulates the traversal state. The consumer may call {@link #checkpoint()} at any time. The implementation shouldreturn a non-null String that, if supplied to {@link TraversalManager#resumeTraversal(String)}, would cause traversal to resume from the next unprocessed document. Boundary cases are important for {@link #checkpoint()}:
- If {@link #checkpoint()} is called before any calls to{@link #nextDocument()}, then traversal should resume with the Document that would have been returned by the first call to {@link #nextDocument()}.
- If {@link #checkpoint()} is called after a call to{@link #nextDocument()} that returns a valid document, thentraversal should resume with the Document that would have been returned by the next call to {@link #nextDocument()}.
- If {@link #checkpoint()} is not called, then traversal shouldresume from the previous checkpoint, as if none of the documents in this {@code DocumentList} had been processed.
The typical pattern for consuming an object that implements this interface is as follows (disregarding exception handling):
DocumentList docList = ... Document doc; while (doc = docList.nextDocument()) { handleDoc(doc); if (whatever reason) break; } String check = doclist.checkpoint();
Note: because of the restriction that the next call to {@link #nextDocument()} invalidates the previous Document, and thereare similar restrictions in the {@link Document} interface, it is possibleto provide a single stateful object that implements {@link DocumentList}, {@link Document} and {@link Property}, by returning {@code this}(or {@code null}) to all calls to {@link #nextDocument()} and{@link Document#findProperty(String)}. However, if preferred, the implementor may also use separate objects for each of those interfaces.
@since 1.0