public interface DocumentList
nextDocument()
, which returns the next available
Document
or null
if there are no more.
Important: a Document
object obtained
by calling nextDocument()
is invalidated by the next
call to 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
checkpoint()
, which produces a String that
encapsulates the traversal state. The consumer may call
checkpoint()
at any time. The implementation should
return a non-null String that, if supplied to
TraversalManager.resumeTraversal(String)
, would cause
traversal to resume from the next unprocessed document.
Boundary cases are important for checkpoint()
:
checkpoint()
is called before any calls to
nextDocument()
, then traversal should resume with
the Document that would have been returned by the first call to
nextDocument()
.checkpoint()
is called after a call to
nextDocument()
that returns a valid document, then
traversal should resume with the Document that would have been
returned by the next call to nextDocument()
.checkpoint()
is not called, then traversal should
resume from the previous checkpoint, as if none of the documents
in this DocumentList
had been processed.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
nextDocument()
invalidates the previous Document, and there
are similar restrictions in the Document
interface, it is possible
to provide a single stateful object that implements DocumentList
,
Document
and Property
, by returning this
(or null
) to all calls to nextDocument()
and
Document.findProperty(String)
. However, if preferred, the
implementor may also use separate objects for each of those interfaces.Modifier and Type | Method and Description |
---|---|
java.lang.String |
checkpoint()
Provides a checkpoint that can be used to control traversal.
|
Document |
nextDocument()
Returns the next
Document in this document list, if there is one. |
Document nextDocument() throws RepositoryException
Document
in this document list, if there is one.null
otherwiseRepositoryException
- if a repository access error occurs
The Connector Manager will stop processing the
DocumentList
, call checkpoint()
, and wait
a short period of time before resuming traversal.RepositoryDocumentException
- if this specific document
has unrecoverable errors. This document will be skipped,
and nextDocument()
or checkpoint()
may be subsequently called.java.lang.String checkpoint() throws RepositoryException
TraversalManager.resumeTraversal(String)
.
If null
is returned, then no new checkpoint will be saved,
and the existing checkpoint will be supplied to
TraversalManager.startTraversal()
or
TraversalManager.resumeTraversal(String)
,
in effect, restarting the traversal from the last saved checkpoint.
null
String
that can be supplied
subsequently to TraversalManager.resumeTraversal(String)
RepositoryException
- if a repository access error occurs or if
there is insufficient information to create a checkpoint string.
If checkpoint()
throws an exception, a subsequent
call to TraversalManager.resumeTraversal(String)
will be
supplied the last known good checkpoint string.