org.gcube.data.streams
Interface Stream<E>

Type Parameters:

E - the type of elements iterated over

All Superinterfaces:

Iterator<E>

All Known Implementing Classes:

FoldedStream, GuardedStream, IteratorStream, LookAheadStream, MonitoredStream, PipedStream, ResultsetStream, UnfoldedStream

public interface Stream<E>
extends Iterator<E>

An iterator over the elements of a dataset of arbitrary origin, including memory, secondary storage, and network.

Streams are:

• addressable, i.e. return a locator that references their address. The use of locators is implementation-dependent;
• close-able, i.e. their implementation may release resources;

Streams may raise a broader range of failures than plain Iterators, including StreamExceptions. Independently from failure handling strategies, the recommended idiom for stream consumption is the following:

 Stream<T> stream = ...
 try {
   while (stream.hasNext())
     ....stream.next()...
 }
 finally {
  stream.close();
 }
 

Author:

Fabio Simeoni

Method Summary

void	close() Closes the stream unconditionally, releasing any resources that it may be using.
boolean	hasNext() Returns true if the stream has more elements.
URI	locator() Returns the stream locator.
E	next()

Methods inherited from interface java.util.Iterator

remove

Method Detail

hasNext

boolean hasNext()

Returns true if the stream has more elements.

Specified by:

hasNext in interface Iterator<E>

Returns:

true if the stream has more elements and has not been closed.

next

E next()
       throws StreamException

Specified by:

next in interface Iterator<E>

Throws:

NoSuchElementException - if the stream has no more elements or it has been closed.

StreamContingencyException - if the element cannot be returned due to a recoverable error

StreamOpenException - if the stream cannot be opened for iteration (unrecoverable)

RuntimeException - if the element cannot be returned due to a generic unrecoverable outage or error

StreamException

locator

URI locator()
            throws IllegalStateException

Returns the stream locator.

Returns:

the locator

Throws:

IllegalStateException - if the stream is no longer addressable at the time of invocation.

close

void close()

Closes the stream unconditionally, releasing any resources that it may be using.

Subsequent invocations of this method have no effect.
Subsequents invocations of hasNext() return false.
Subsequent invocations of next() throw NoSuchElementExceptions.

Failures are logged by implementations and are otherwise suppressed.