public static interface Source.Reader<T> extends AutoCloseable
This interface is deliberately distinct from Iterator because
the current model tends to be easier to program and more efficient in practice
for iterating over sources such as files, databases etc. (rather than pure collections).
Reader implementations do not need to be thread-safe; they may only be accessed
by a single thread at once.
Callers of Readers must obey the following access pattern:
start()
start() returned true, any number of calls to getCurrent*
methodsadvance(). This may be called regardless
of what the previous start()/advance() returned.
advance() returned true, any number of calls to getCurrent*
methodsFor example, if the reader is reading a fixed set of data:
for (boolean available = reader.start(); available; available = reader.advance()) {
T item = reader.getCurrent();
Instant timestamp = reader.getCurrentTimestamp();
...
}
If the set of data being read is continually growing:
boolean available = reader.start();
while (true) {
if (available) {
T item = reader.getCurrent();
Instant timestamp = reader.getCurrentTimestamp();
...
resetExponentialBackoff();
} else {
exponentialBackoff();
}
available = reader.advance();
}
Note: this interface is a work-in-progress and may change.
| Modifier and Type | Method and Description |
|---|---|
boolean |
advance()
Advances the reader to the next valid record.
|
void |
close()
Closes the reader.
|
T |
getCurrent()
|
Source<T> |
getCurrentSource()
Returns a
Source describing the same input that this Reader reads
(including items already read). |
org.joda.time.Instant |
getCurrentTimestamp()
Returns the timestamp associated with the current data item.
|
boolean |
start()
Initializes the reader and advances the reader to the first record.
|
boolean start()
throws IOException
This method should be called exactly once. The invocation should occur prior to calling
advance() or getCurrent(). This method may perform expensive operations that
are needed to initialize the reader.
true if a record was read, false if there is no more input available.IOExceptionboolean advance()
throws IOException
true if a record was read, false if there is no more input available.IOExceptionT getCurrent() throws NoSuchElementException
start() or
advance() call. The returned value must be effectively immutable and remain valid
indefinitely.
Multiple calls to this method without an intervening call to advance() should
return the same result.
NoSuchElementException - if the reader is at the beginning of the input and
start() or advance() wasn't called, or if the last start() or
advance() returned false.org.joda.time.Instant getCurrentTimestamp()
throws NoSuchElementException
If the source does not support timestamps, this should return
BoundedWindow.TIMESTAMP_MIN_VALUE.
Multiple calls to this method without an intervening call to advance() should
return the same result.
NoSuchElementException - if the reader is at the beginning of the input and
start() or advance() wasn't called, or if the last start() or
advance() returned false.void close()
throws IOException
close in interface AutoCloseableIOException