Module jpastreamer.application
Package com.speedment.jpastreamer.application

Interface StreamSupplier<T>

Type Parameters:
T - the type of the stream elements
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.

It provides methods to obtain a Stream instance that corresponds to the configured stream source. The StreamSupplier is responsible for managing the lifecycle of the underlying EntityManager.

A StreamSupplier is associated with a particular Stream source and cannot be reconfigured. This ensures thread-safety to allows concurrent reads and writes via the same StreamSupplier. The StreamSupplier is typically obtained by calling JPAStreamer.createStreamSupplier(Class) ()}. It allows for the creation of multiple streams using the same EntityManager, potentially saving resources.

To create a Stream, call the stream() method, providing the desired entity class as the type parameter. The resulting Stream will correspond to the specified entity class and the configured StreamConfiguration.

The execution of a terminal operation on the Stream will not close the StreamSupplier and its associated EntityManager. This allows for repeated calls to stream() on the same StreamSupplier, reusing the same EntityManager.

The EntityManager associated with the StreamSupplier has a first-level cache to optimize query performance. By default, database changes performed by another application or made directly on the database may not be detected between calls to stream(). To ensure that the cache is cleared between each fetch, use JPAStreamer.stream(StreamConfiguration) instead.

It is important to manage the lifecycle of the StreamSupplier and close it when it is no longer needed. Closing the StreamSupplier will also close the associated EntityManager, releasing any acquired resources. The recommended approach is to use a try-with-resources block to automatically close the StreamSupplier: 


 final JPAStreamer jpaStreamer = JPAStreamer.of("sakila");

 try (final StreamSupplier<Film> streamSupplier = jpaStreamer.createStreamSupplier()) {
     // Use the StreamSupplier to create and process streams
     Stream<Film> stream = streamSupplier.stream(Film.class);
     // Perform stream operations...
 }

Note that if JPAStreamer is instantiated with a Supplier<EntityManager> via JPAStreamer.of(Supplier), JPAStreamer will not close the underlying EntityManager. In that case, the lifecycle of the obtained EntityManagers is managed by the supplier.

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:

      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:

    • 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