org.kitesdk.data

Interface DatasetReader<E>

Type Parameters:

E - The type of entity produced by this reader.

All Superinterfaces:

AutoCloseable, Closeable, Iterable<E>, Iterator<E>

@NotThreadSafe
public interface DatasetReader<E>
extends Iterator<E>, Iterable<E>, Closeable

A stream-oriented dataset reader.

Implementations of this interface read data from a Dataset. Readers are use-once objects that read from the underlying storage system to produce deserialized entities of type E. Normally, you are not expected to instantiate implementations directly. Instead, use the containing dataset's View.newReader() method to get an appropriate implementation. Normally, you receive an instance of this interface from a dataset, invoke hasNext() and next() as necessary, and close() when you are done or no more data exists.

Implementations can hold system resources until the close() method is called, so you must follow the normal try / finally pattern to ensure these resources are properly freed when the reader is exhausted or no longer useful. Do not rely on implementations automatically invoking the close() method upon object finalization (although implementations are free to do so, if they choose). All implementations must silently ignore multiple invocations of close() as well as a close of an unopened reader.

If any method throws an exception, the reader is no longer valid, and the only method that can be subsequently called is close().

Implementations of DatasetReader are not required to be thread-safe; that is, the behavior when accessing a single instance from multiple threads is undefined.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Close the reader and release any system resources.
boolean	hasNext() Tests the reader to see if additional entities can be read.
boolean	isOpen()
E	next() Fetch the next entity from the reader.
void	remove() Remove the last entity from the reader (OPTIONAL).

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

hasNext

boolean hasNext()

Tests the reader to see if additional entities can be read.

Specified by:

hasNext in interface Iterator<E>

Returns:

true if additional entities exist, false otherwise.

Throws:

DatasetOperationException - If the operation did not succeed.

DatasetIOException - To wrap an internal IOException

next

E next()

Fetch the next entity from the reader.

Calling this method when no additional data exists is illegal; you should use hasNext() to test if a call to read() will succeed. Implementations of this method can block.

Specified by:

next in interface Iterator<E>

Returns:

An entity of type E.

Throws:

DatasetOperationException - If the operation did not succeed.

DatasetIOException - To wrap an internal IOException

NoSuchElementException

Since:

0.7.0

remove

void remove()

Remove the last entity from the reader (OPTIONAL).

This has the same semantics as Iterator.remove(), but is unlikely to be implemented.

Specified by:

remove in interface Iterator<E>

Since:

0.7.0

close

void close()

Close the reader and release any system resources.

No further operations of this interface (other than additional calls of this method) can be performed, however implementations can choose to permit other method calls. See implementation documentation for details.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

DatasetOperationException - If the operation did not succeed.

DatasetIOException - To wrap an internal IOException

isOpen

boolean isOpen()