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 able to handle several reading and writing threads at the same time.

JPAStreamer can be instantiated using different approaches depending on your requirements. 1. Using the persistence unit name The persistence unit name can be used to initialize JPAStreamer as follows:

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

Replace "sakila" with the name of your persistence unit as specified in the JPA configuration file. JPAStreamer will establish a database connection based on the provided persistence unit name. This method creates a new jakarta.persistence.EntityManagerFactory managed by JPAStreamer. 2. Using an existing EntityManagerFactory If you already have an existing EntityManagerFactory, you can initialize JPAStreamer as follows:

 final EntityManagerFactory emf = Persistence.createEntityManagerFactory("sakila");
 final JPAStreamer jpaStreamer = JPAStreamer.of(emf);
 

In this case, JPAStreamer will not manage the lifecycle of the EntityManagerFactory. The provided EntityManagerFactory will be used to obtain EntityManagers, which will be managed by JPAStreamer. 3. Using a Supplier of EntityManagers Another third option is to provide a Supplier of EntityManagers:

 final EntityManagerFactory emf = Persistence.createEntityManagerFactory("sakila");
 final JPAStreamer jpaStreamer = JPAStreamer.of(emf::createEntityManager);
 

This approach is useful when you want to supply your own EntityManagers. JPAStreamer will not manage the lifecycle of the EntityManagers supplied through the Supplier.

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.

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 it might appear that there is a de-facto order for some stream sources. 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. Thus, the execution time of the Terminal Operation will depend on the optimized pipeline and the entities in the underlying database. 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.

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 an Exception if the underlying database throws an Exception (e.g. an SqlException)

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()

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 Film where
     name LIKE 'A%'

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

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

Type Parameters:

T - the type of the stream elements

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:

• java.util.stream
• Stream

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 type of the stream elements

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:

• for further details

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 type of the stream elements

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:

• for further details

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 type of the stream elements

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 type of the stream elements

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:

• (StreamConfiguration) for further details

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 type of the stream elements

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:

• (StreamConfiguration) for further details

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:

• createJPAStreamerBuilder(String)

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