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.

Properties

Streams are:

• addressable: clients may invoke locator() to obtain a reference to their address. The use and syntax of locators is implementation-dependent.
• closeable: clients may invoke close() to allow implementations to release resources. Clients should invoke close() if they do not consume streams in their entirety. Implementations must automatically release their resources when they have been consumed in their entirety.
• fallible: invoking next() over streams that originate from secondary storage and remote locations may raise a wide range failures. Some failures may be recoverable, in that subsequent invocations of next() may still succeed. Other failures may be unrecoverable, in that subsequent invocations of next() are guaranteed to fail too.

Implementations

There are predefined implementations that adapt the Stream interface to existing Iterators and remote gRS2 resultsets (cf. IteratorStream and ResultsetStream).

Other predefined implementations transform, fold, and unfold the elements of existing streams (cf. PipedStream, FoldedStream, UnfoldedStream).

Additional implementations allow modular handling of stream faults and notify interested listeners of stream iteration events (cf. GuardedStream, MonitoredStream).

Finally, streams may be published outside the current runtime by implementations of the StreamPublisher interface. A predefined implementation supports publication of streams as gRS2 resultsets (cf. RsPublisher).

All the available implementations can be fluently instantiated and configured with an embedded DSL (cf. Streams).

Fault Handling

Clients can implement FaultHandlers to specify fault handling policies over streams, and then wrap streams in GuardedStreams that apply they policies:

 import static ....Streams.*; 
 ...
 Stream<T> stream = ...
 
 FaultHandler handler = new FaultHandler() {
   public void handle(RuntimeException fault) {
    ...
   }
 };
 
 Stream<T> guarded = guard(stream).with(handler);
 

FaultHandlers can ignore faults, rethrow them, rethrow different faults, or use the constant FaultHandler.iteration to stop the iteration of the underlying stream (cf. Iteration.stop())

Faults are unchecked exceptions thrown by next(), often wrappers around an original cause. FaultHandlers can use a fluent API to simplify the task of analysing fault causes (cf. Faults):

 FaultHandler handler = new FaultHandler() {
        public void handle(RuntimeException fault) {
           try {
                throw causeOf(fault).as(SomeException.class,SomeOtherException.class);
           }
           catch(SomeException e) {...}
           catch(SomeOtherException e) {...}
        }
 };
 

Consumption

Clients may consume streams by explicitly iterating over their elements. Since streams are fallible and closeable, the recommended idiom is the following:

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

Alternatively, clients may provide Callbacks to generic StreamConsumers that iterate on behalf of clients. Using the simplifications of the DSL:

 Stream<T> stream = ...
 
 Callback<T> callback = new Callback<T>() {
        public void consume(T element) {
           ...element...
        }
 };
 
 consume(stream).with(callback);
 

Callbacks can control iteration through the Iteration constant (cf. Callback.iteration):

 Callback<T> callback = new Callback<T>() {
        public void consume(T element) {
            ...iteration.stop()...
                ...
        }
 };
 

Author:

Fabio Simeoni

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes the stream unconditionally, releasing any resources that it may be using.
boolean	hasNext()
boolean	isClosed() Returns true if the stream has been closed.
URI	locator() Returns the stream locator.
E	next()

Methods inherited from interface java.util.Iterator

remove

Method Detail

hasNext

boolean hasNext()

Specified by:

hasNext in interface Iterator<E>

next

E next()

Specified by:

next in interface Iterator<E>

Throws:

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

StreamOpenException - if the stream cannot be opened

RuntimeException - if the element cannot be returned

locator

URI locator()

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 suppressed otherwise.

isClosed

boolean isClosed()

Returns true if the stream has been closed.

Returns:

true if the stream has been closed