Package org.apache.sis.internal.stream

Class DeferredStream<T>

java.lang.Object
org.apache.sis.internal.stream.BaseStreamWrapper<T,Stream<T>>
org.apache.sis.internal.stream.StreamWrapper<T>
org.apache.sis.internal.stream.DeferredStream<T>
Type Parameters:
T - the type of objects contained in the stream, as specified in Stream interface.
All Implemented Interfaces:
AutoCloseable, BaseStream<T,Stream<T>>, Stream<T>
public abstract class DeferredStream<T> extends StreamWrapper<T>
A stream which delay the creation of the source stream as long as possible. This stream gives to subclasses an opportunity to collect more information before to create the source. The source stream is implemented by a Spliterator created by createSourceIterator(). The call to that method is deferred until a terminal operation is invoked.
Example: if a stream can count its elements efficiently (e.g. using a COUNT query on SQL databases), a DeferredStream subclass can override the StreamWrapper.count() method for running the count query instead of counting elements of the stream manually.

Deferred streams are also useful with intermediate operations. For example, a subclass can override the StreamWrapper.skip(long) and StreamWrapper.limit(long) methods for modifying the SQL query with addition of OFFSET and FETCH NEXT clauses before the worker stream is created.

Since:
1.1
Version:
1.1
Author:
Alexis Manin (Geomatys), Martin Desruisseaux (Geomatys)

  • Constructor Details

    • DeferredStream

      protected DeferredStream(int characteristics, boolean parallel)
      Creates a new deferred stream.
      Parameters:
      characteristics - characteristics of the iterator to be created by createSourceIterator().
      parallel - whether the stream is initially parallel.

  • Method Details

    • createSourceIterator

      protected abstract Spliterator<T> createSourceIterator() throws Exception
      Creates the iterator which will provide the actual data. The characteristics of the returned iterator must be the characteristics argument given to the DeferredStream constructor.

      This method is invoked at most once, generally when a stream terminal operation is invoked. After this method is invoked, this stream will not be active anymore. The stream returned by the public methods should be used instead.

      Returns:
      an iterator over the elements.
      Throws:
      Exception - if the iterator cannot be created.

    • setCloseHandler

      protected final void setCloseHandler(AutoCloseable handler)
      Registers a handler to run for releasing resources created by the worker. This method can be invoked by the createSourceIterator() implementation. The specified handler will be executed exactly once, unless it is discarded by a subsequent call to setCloseHandler(…).

      This method can be invoked many times, each invocation replacing the previous handler. The following example uses JDBC connection and assumes that MyIterator implements AutoCloseable, and that the resource disposal done by that method includes closing the JDBC connection:

      Parameters:
      handler - the action to execute for releasing resources, includes the case when createSourceIterator() fails. Can be null for no action,