org.kitesdk.data
Interface DatasetReader<E>

Type Parameters:

E - The type of entity produced by this reader.

All Superinterfaces:

Closeable, Iterable<E>, Iterator<E>

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

A stream-oriented dataset reader.

Subsystem-specific implementations of this interface are used to read data from a Dataset. Readers are use-once objects that produce entities of type E. Normally, users are not expected to instantiate implementations directly. Instead, use the containing dataset's Dataset#getReader() method to get an appropriate implementation. Normally, users receive an instance of this interface from a dataset, call open() to prepare for IO operations, invoke hasNext() and next() as necessary, and close() when they are done or no more data exists.

Implementations may hold system resources until the close() method is called, so users 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 may be subsequently called is close().

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

Method Summary

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	open() Open the reader, allocating any necessary resources required to produce entities.
void	remove() Remove the last entity from the reader (OPTIONAL).

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

open

void open()

Open the reader, allocating any necessary resources required to produce entities.

This method must be invoked prior to any calls of hasNext() or next().

Throws:

UnknownFormatException

DatasetReaderException

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:

DatasetReaderException

next

E next()

Fetch the next entity from the reader.

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

Specified by:

next in interface Iterator<E>

Returns:

An entity of type E.

Throws:

DatasetReaderException

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) may be performed, however implementations may choose to permit other method calls. See implementation documentation for details.

Specified by:

close in interface Closeable

Throws:

DatasetReaderException

isOpen

boolean isOpen()