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

Interface JPAStreamer

public interface JPAStreamer
A JPAStreamer is responsible for creating Streams from data sources, alternatively for creating StreamSuppliers that can be reused to create Streams of the same Entity source, see createStreamSupplier(StreamConfiguration)

Entity sources can be RDBMSes, files or other data sources. A JPAStreamer must be thread safe and be able to handle several reading and writing threads at the same time.

Since:
0.1.0
Author:
Per Minborg

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes this JPAStreamer and releases any resources potentially held.
    static JPAStreamerBuilder
    createJPAStreamerBuilder(jakarta.persistence.EntityManagerFactory entityManagerFactory)
    Creates and returns a new JPAStreamerBuilder that will use the provided entityManagerFactory.
    static JPAStreamerBuilder
    createJPAStreamerBuilder(String persistenceUnitName)
    Creates and returns a new JPAStreamerBuilder that will create a new EntityManagerFactory using the provided persistenceUnitName.
    static JPAStreamerBuilder
    createJPAStreamerBuilder(Supplier<jakarta.persistence.EntityManager> entityManagerSupplier)
    Creates and returns a new JPAStreamerBuilder that will use the provided entityManagerSupplier.
    default <T> StreamSupplier<T>
    createStreamSupplier(Projection<T> projection)
    Creates and returns a new StreamSupplier that can create Streams over all entities in the underlying data source (e.g database) of the entity specified by the provided projection.
    <T> StreamSupplier<T>
    createStreamSupplier(StreamConfiguration<T> streamConfiguration)
    Creates and returns a new StreamSupplier that can create Streams over all entities in the underlying data source (e.g database) of the provided type entityClass.
    default <T> StreamSupplier<T>
    createStreamSupplier(Class<T> entityClass)
    Creates and returns a new StreamSupplier that can create Streams over all entities in the underlying data source (e.g database) of the provided type entityClass.
    static JPAStreamer
    of(jakarta.persistence.EntityManagerFactory entityManagerFactory)
    Creates and returns a new JPAStreamer that will use the provided entityManagerFactory.
    static JPAStreamer
    of(String persistenceUnitName)
    Creates and returns a new JPAStreamer that will create a new EntityManagerFactory using the provided persistenceUnitName.
    static JPAStreamer
    of(Supplier<jakarta.persistence.EntityManager> entityManagerSupplier)
    Creates and returns a new JPAStreamer that will use the provided entityManagerSupplier.
    void
    resetStreamer(Class<?>... entityClasses)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 3.0.2, JPAStreamer no longer caches Streamers thus there is no need for a method that resets the cache.
    default <T> Stream<T>
    stream(Projection<T> projection)
    Creates and returns a new Stream over all entities in the underlying data source (e.g database) of the entity specified by the provided projection.
    <T> Stream<T>
    stream(StreamConfiguration<T> streamConfiguration)
    Creates and returns a new Stream over all entities in the underlying data source (e.g database) according to the provided streamConfiguration.
    default <T> Stream<T>
    stream(Class<T> entityClass)
    Creates and returns a new Stream over all entities in the underlying data source (e.g database) of the provided type entityClass.

  • Method Details

    • stream

      <T> Stream<T> stream(StreamConfiguration<T> streamConfiguration)
      Creates and returns a new Stream over all entities in the underlying data source (e.g database) according to the provided streamConfiguration. This is the main query API for JPAstreamer.

      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
      Type Parameters:
      T - The element type (type of a class token)
      Parameters:
      streamConfiguration - a configuration including an entity class (annotated with @Entity)
      Returns:
      a new Stream over all entities in the underlying data source (e.g database) described by the provided streamConfiguration
      Throws:
      RuntimeException - if an error occurs during a Terminal Operation (e.g. an SqlException is thrown by the underlying database)
      See Also:

    • stream

      default <T> Stream<T> stream(Class<T> entityClass)
      Creates and returns a new Stream over all entities in the underlying data source (e.g database) of the provided type entityClass.

      This method is a convenience method equivalent to: 

      stream(StreamConfiguration.of(entityClass))
      Type Parameters:
      T - The element type (type of a class token)
      Parameters:
      entityClass - to use
      Returns:
      a new Stream over all entities in the underlying data source (e.g database) of the provided type entityClass
      See Also:

    • stream

      default <T> Stream<T> stream(Projection<T> projection)
      Creates and returns a new Stream over all entities in the underlying data source (e.g database) of the entity specified by the provided projection.

      This method is a convenience method equivalent to: 

      stream(StreamConfiguration.of(projection.entityClass()).select(projection))
      Type Parameters:
      T - The element type (type of a class token)
      Parameters:
      projection - to use
      Returns:
      a new Stream over all entities in the underlying data source (e.g database) of the entity specified by the provided projection.
      See Also:

    • createStreamSupplier

      <T> StreamSupplier<T> createStreamSupplier(StreamConfiguration<T> streamConfiguration)
      Creates and returns a new StreamSupplier that can create Streams over all entities in the underlying data source (e.g database) of the provided type entityClass.

      The provided StreamSupplier will not be closed whenever the generated Stream instance is closed.

      If you are using the same Stream source frequently e.g. Film.class, consider configuring a StreamSupplier that can supply Streams from the same source over and over again. This save resources and avoids instantiating a new EntityManager for each new Stream.

      Here is an example of using a StreamSupplier: 

      
    final StreamSupplier<Film> streamSupplier = jpaStreamer.createStreamSupplier(Film.class);
    List<Film> longFilms = streamSupplier.stream()
       .filter(Film$.name.equal("Casablanca"))
       .collect(toList()); // the terminal operation does not close the Stream Supplier and its Entity Manager
     
    // ... repeated uses of the supplier 
      
    streamSupplier.close(); // closes the Entity Manager
      The above is equal to: 
      
    List<Film> films = jpaStreamer.stream(Film.class) 
       .filter(Film$.name.equal("Casablanca"))
       .collect(toList()); // the terminal operation closes the underlying StreamSupplier and its Entity Manager

      Type Parameters:
      T - The element type (type of a class token)
      Parameters:
      streamConfiguration - a configuration including an entity class (annotated with @Entity)
      Returns:
      a new StreamSupplier that can create Streams over all entities in the underlying data source (e.g database) described by the provided streamConfiguration

    • createStreamSupplier

      default <T> StreamSupplier<T> createStreamSupplier(Class<T> entityClass)
      Creates and returns a new StreamSupplier that can create Streams over all entities in the underlying data source (e.g database) of the provided type entityClass.

      This method is a convenience method equivalent to: 

      createStreamer(StreamConfiguration.of(entityClass))
      Type Parameters:
      T - The element type (type of a class token)
      Parameters:
      entityClass - to use in generated Streams
      Returns:
      a new StreamSupplier that can create Streams over all entities in the underlying data source (e.g database) of the provided type entityClass
      See Also:

    • createStreamSupplier

      default <T> StreamSupplier<T> createStreamSupplier(Projection<T> projection)
      Creates and returns a new StreamSupplier that can create Streams over all entities in the underlying data source (e.g database) of the entity specified by the provided projection.

      This method is a convenience method equivalent to: 

      createStreamer(StreamConfiguration.of(entityClass))
      Type Parameters:
      T - The element type (type of a class token)
      Parameters:
      projection - to use
      Returns:
      a new StreamSupplier that can create Streams over all entities in the underlying data source (e.g database) of the entity specified by the provided projection.
      See Also:

    • resetStreamer

      @Deprecated(since="3.0.2", forRemoval=true) void resetStreamer(Class<?>... entityClasses)
      Deprecated, for removal: This API element is subject to removal in a future version.
      since 3.0.2, JPAStreamer no longer caches Streamers thus there is no need for a method that resets the cache. If you wish to manage the Streamer lifecycle manually, see createStreamSupplier(StreamConfiguration)
      Resets the Streamer associated with the provided Entity classes.

      This will create a new instance of the underlying jakarta.persistence.EntityManager, removing all entries of the associated Entity class from the first-level cache. The old jakarta.persistence.EntityManager is closed upon removal from the cache. In case JPAStreamer was configured with a Supplier<EntityManager> the lifecycle of the Entity Managers is not managed by JPAStreamer, thus use of the method is not permitted and will result in an UnsupportedOperationException.

      Parameters:
      entityClasses - of the streamer
      Throws:
      UnsupportedOperationException - if JPAStreamer is configured with a Supplier, see com.speedment.jpastreamer.application.JPAStreamer#of(java.util.function.Supplier)

    • close

      void close()
      Closes this JPAStreamer and releases any resources potentially held.

      If and only if this JPAStreamer was created using a persistenceUnitName, the underlying EntityManagerFactory will be closed.

    • createJPAStreamerBuilder

      static JPAStreamerBuilder createJPAStreamerBuilder(String persistenceUnitName)
      Creates and returns a new JPAStreamerBuilder that will create a new EntityManagerFactory using the provided persistenceUnitName.

      Call the JPAStreamerBuilder::build method to create a new JPAStreamer instance.

      The newly created EntityManagerFactory will be closed whenever a built JPAStreamer instance is closed.

      Parameters:
      persistenceUnitName - of the persistence unit as per the persistence.xml file
      Returns:
      a new JPAStreamerBuilder

    • createJPAStreamerBuilder

      static JPAStreamerBuilder createJPAStreamerBuilder(jakarta.persistence.EntityManagerFactory entityManagerFactory)
      Creates and returns a new JPAStreamerBuilder that will use the provided entityManagerFactory.

      Call the JPAStreamerBuilder::build method to create a new JPAStreamer instance.

      The provided entityManagerFactory will not be closed whenever a built JPAStreamer instance is closed.

      Parameters:
      entityManagerFactory - to be used by the JPAStreamer
      Returns:
      a new JPAStreamerBuilder

    • createJPAStreamerBuilder

      static JPAStreamerBuilder createJPAStreamerBuilder(Supplier<jakarta.persistence.EntityManager> entityManagerSupplier)
      Creates and returns a new JPAStreamerBuilder that will use the provided entityManagerSupplier.

      Call the JPAStreamerBuilder::build method to create a new JPAStreamer instance.

      EntityManagers provided by the entityManagerSupplier will not be closed whenever a built JPAStreamer instance is closed.

      This is a preview and may be subject to change.

      Parameters:
      entityManagerSupplier - to be used by the JPAStreamer
      Returns:
      a new JPAStreamerBuilder
      Since:
      1.1.1

    • of

      static JPAStreamer of(String persistenceUnitName)
      Creates and returns a new JPAStreamer that will create a new EntityManagerFactory using the provided persistenceUnitName.

      The newly created EntityManagerFactory will be closed whenever the returned JPAStreamer instance is closed.

      Parameters:
      persistenceUnitName - of the persistence unit as per the persistence.xml file
      Returns:
      a new JPAStreamer
      See Also:

    • of

      static JPAStreamer of(jakarta.persistence.EntityManagerFactory entityManagerFactory)
      Creates and returns a new JPAStreamer that will use the provided entityManagerFactory.

      The provided entityManagerFactory will not be closed whenever the returned JPAStreamer instance is closed.

      Parameters:
      entityManagerFactory - to be used by the JPAStreamer
      Returns:
      a new JPAStreamerBuilder

    • of

      static JPAStreamer of(Supplier<jakarta.persistence.EntityManager> entityManagerSupplier)
      Creates and returns a new JPAStreamer that will use the provided entityManagerSupplier.

      EntityManagers provided by the entityManagerSupplier will not be closed whenever the returned JPAStreamer instance is closed.

      Parameters:
      entityManagerSupplier - to be used by the JPAStreamer
      Returns:
      a new JPAStreamerBuilder