Module jpastreamer.application

Package com.speedment.jpastreamer.application

Interface StreamSupplier<T>

All Superinterfaces:

AutoCloseable

public interface StreamSupplier<T>
extends AutoCloseable

A Stream Supplier is responsible for creating Streams from a data source An entity source can be RDBMSes, files or other data sources. A Stream Supplier must be thread safe and be able to handle several reading and writing threads at the same time.

Since:

3.0.1

Author:

Per Minborg, Julia Gustafsson

Method Summary

Modifier and Type	Method	Description
void	close()	Closes this Stream Supplier and releases any resources potentially held, such as the underlying Entity Manager.
StreamConfiguration<T>	configuration()	Returns the StreamConfiguration that describes the stream source of the Streams generated by this Supplier.
Stream<T>	stream()	Creates and returns a new Stream over all entities in the underlying data source (e.g database) according to the streamConfiguration associated with this Streamer.

Method Details

stream

Stream<T> stream()

Creates and returns a new Stream over all entities in the underlying data source (e.g database) according to the streamConfiguration associated with this Streamer.

The order in which elements are returned when the stream is eventually consumed is unspecified. The order may even change from one invocation to another. Thus, it is an error to assume any particular element order even though is might appear, for some stream sources, that there is a de-facto order.

If a deterministic order is required, then make sure to invoke the Stream.sorted(java.util.Comparator) method on the Stream returned.

Mutable elements are not reused within the stream. More formally, there are no pair of mutable stream elements e1 and e2 such that e1 == e2.

The Stream will never contain null elements.

This is an inexpensive O(1) operation that will complete in constant time regardless of the number of entities in the underlying database.

The returned stream is aware of its own pipeline and will optionally optimize its own pipeline whenever it encounters a Terminal Operation so that it will only iterate over a minimum set of matching entities.

When a Terminal Operation is eventually called on the Stream, that execution time of the Terminal Operation will depend on the optimized pipeline and the entities in the underlying database.

The Stream will be automatically closed after the Terminal Operation is completed or if an Exception is thrown during the Terminal Operation.

Some of the Terminal Operations are:

• forEach(Consumer)
• forEachOrdered(Consumer)
• toArray()
• toArray(IntFunction)
• reduce(BinaryOperation
• reduce(Object, BinaryOperator)
• reduce(Object, BiFunction, BinaryOperator)
• collect(Collector)
• collect(Supplier, BiConsumer, BiConsumer)
• min(Comparator)
• min(Comparator)
• count()
• anyMatch(Predicate)
• noneMatch(Predicate)
• findFirst()
• findAny()
• iterator()

Any Terminating Operation may throw an Exception if the underlying database throws an Exception (e.g. an SqlException)

Because the Stream may short-circuit operations in the Stream pipeline, methods having side-effects (like peek(Consumer) will potentially be affected by the optimization.

Here are some examples of how the stream optimization might work:

• stream(Film.class)
     .filter(Film$.name.equal("Casablanca"))
     .collect(toList());

  -> select * from film where name='Casablanca'

• stream.count();

  -> select count(*) from film

• stream(Film.class)
     .filter(Film$.name.startsWith("A"))
     .count();

  -> select count(*) from hares where
     name LIKE 'A%'

• stream.stream(Film.class)
     .filter(Film$.rating.equal("G")
     .filter(Film$.length.greaterThan(100)
     .count();

  -> select count(*) from hares where
            rating ='G'
          and
            length > 100

Returns:

a new stream over all entities in this table in unspecified order

Throws:

RuntimeException - if an error occurs during a Terminal Operation (e.g. an SqlException is thrown by the underlying database)

See Also:

• java.util.stream
• Stream

close

void close()

Closes this Stream Supplier and releases any resources potentially held, such as the underlying Entity Manager.

Specified by:

close in interface AutoCloseable

configuration

StreamConfiguration<T> configuration()

Returns the StreamConfiguration that describes the stream source of the Streams generated by this Supplier.

Returns:

the configuration of the Streams generated by this Supplier