com.speedment.runtime.join

Interface Join<T>

Type Parameters:

T - the composite type of entity types

public interface Join<T>

This interface represent a Join operation from which Streams of the joined tables can be obtained.

Since:

3.1.0

Author:

Per Minborg

Method Summary

Modifier and Type	Method and Description
Stream<T>	stream() Creates and returns a new Stream over joined Tuples of entities in the underlying data source (e.g database).

Method Detail

stream

Stream<T> stream()

Creates and returns a new Stream over joined Tuples of entities in the underlying data source (e.g database).

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.

For Joins obtained via the default HasDefaultBuild.build() method, elements appearing in the stream may be deeply immutable meaning that Tuples in the stream are immutable and that entities contained in these Tuples may also be immutable. Thus, it is an error to invoke setters on any objects obtained directly or indirectly from the stream elements. If mutable objects are needed, the immutable objects must be used to create a new mutable object.

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.

Any Terminating Operation may throw a SpeedmentException 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.

Returns:

a new Stream over Tuples of entities in this table in unspecified order

Throws:

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

See Also:

java.util.stream, Stream