Module storm
Package st.orm.repository

Interface EntityRepository<E extends Record & Entity<ID>,ID>

Type Parameters:
E - the type of entity managed by this repository.
ID - the type of the primary key of the entity.
All Superinterfaces:
Repository
All Known Implementing Classes:
EntityRepositoryImpl
public interface EntityRepository<E extends Record & Entity<ID>,ID> extends Repository
EntityRepository relies on preview features of the Java platform:
  • EntityRepository refers to one or more preview APIs: StringTemplate.
Programs can only use EntityRepository when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
Provides a generic interface with CRUD operations for entities.

Using Entity Repositories

Entity repositories provide a high-level abstraction for managing entities in the database. They offer a set of methods for creating, reading, updating, and deleting entities, as well as querying and filtering entities based on specific criteria. The EntityRepository interface is designed to work with entity records that implement the Entity interface, providing a consistent and type-safe way to interact with the database.

Entity Definition

Define the entity records to use them to in combination with repositories. The Entity interface is a marker interface that indicates that the record is an entity and has a primary key of type ID. The PK annotation is used to mark the primary key field of the entity record. The FK annotation is used to mark the foreign key field of the entity record. The Inline annotation (optional) is used to mark the record component that is inlined in the entity record.

Example:


 record City(@PK int id,
             String name,
             long population
 ) implements Entity<City, Integer> {};

 record Address(String street, String postalCode, @FK City city)

 record User(@PK int id,
             String email,
             LocalDate birthDate,
             @Inline Address address
 ) implements Entity<User, Integer> {};

Repository Lookup

An entity repository can be obtained by invoking entity on an ORMTemplate with the desired entity class. The orm template can be requested as demonstrated below. Note that orm templates are supported for Data Sources, JDBC Connections and JPA Entity Managers.


 ORMTemplate orm = Templates.ORM(dataSource);
 EntityRepository<User> userRepository = orm.entity(User.class);

Alternatively, a specialized repository can be requested by calling the repository method with the repository class. Specialized repositories allow specialized repository methods to be defined in the repository interface. The specialized repository can be used to implement specialized queries or operations that are specific to the entity type. The specialized logic can utilize the QueryBuilder interface to build SELECT and DELETE statements.


 interface UserRepository extends EntityRepository<User> {

     // Specialized repository methods go here:

     default Optional<User> findByEmail(String email) {
         return select()
                 .where(User_.email, EQUALS, email)
                 .getOptionalResult();
     }
 }

 UserRepository userRepository = orm.repository(UserRepository.class)

Repository Injection

A specialized repository can also be injected using Spring's dependency injection mechanism when the storm-spring package is included in the project. Check the storm-spring package to lean how to make repositories available to the application for dependency injection.

CRUD Operations

Entity repositories provide a set of methods for creating, reading, updating, and deleting entities in the database. The following sections provide examples of how to use these methods to interact with the database.

Create

Insert a user into the database. The template engine also supports insertion of multiple entries in batch mode by passing a list of entities. Alternatively, insertion can also be executed using a stream of entities.


 User user = ...;
 userRepository.insert(user);

Read

Select all users from the database that are linked to cities with the name "Sunnyvale". The static metamodel is used to specify the City entity in the QueryBuilder's entity graph.


 List<City> cities = cityRepository.findByName("Sunnyvale")
 List<User> users = userRepository
         .select()
         .where(User_.address.city, cities) // Type-safe metamodel.
         .getResultList();

Alternatively, getResultStream() can be invoked to load the users lazily.

The QueryBuilder also allows the previous queries to be combined into a single select query, using the User's static metamodel to specify the city name field in the QueryBuilder's entity graph.


 List<User> users = userRepository
         .select()
         .where(User_.address.city.name, EQUALS, "Sunnyvale") // Type-safe metamodel.
         .getResultList();

Update

Update a user in the database. The repository also supports updates for multiple entries in batch model by passing a list of entities. Alternatively, updates can also be executed using a stream of entities.


 User user = ...;
 userRepository.update(user);

Delete

Delete user in the database. The repository also supports updates for multiple entries in batch mode by passing a list entities or primary keys. Alternatively, deletion can be executed in using a stream of entities. 


 User user = ...;
 userRepository.delete(user);

Also here, the QueryBuilder can be used to create specialized statement, for instance, to delete all users where the email field IS NULL.


 repository
         .delete()
         .where(User_.email, IS_NULL) // Type-safe metamodel.
         .executeUpdate();
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    count()
    Returns the number of entities in the database of the entity type supported by this repository.
    long
    countById(Stream<ID> ids)
    Counts the number of entities identified by the provided stream of IDs using the default batch size.
    long
    countById(Stream<ID> ids, int batchSize)
    Counts the number of entities identified by the provided stream of IDs, with the counting process divided into batches of the specified size.
    long
    countByRef(Stream<Ref<E>> refs)
    Counts the number of entities identified by the provided stream of refs using the default batch size.
    long
    countByRef(Stream<Ref<E>> refs, int batchSize)
    Counts the number of entities identified by the provided stream of refs, with the counting process divided into batches of the specified size.
    QueryBuilder<E,?,ID>
    delete()
    Creates a new query builder for delete entities of the type managed by this repository.
    void
    delete(E entity)
    Deletes an entity from the database.
    void
    delete(ID id)
    Deletes an entity from the database based on its primary key.
    void
    delete(Iterable<E> entities)
    Deletes a collection of entities from the database in batches.
    void
    delete(Stream<E> entities)
    Deletes a stream of entities from the database in batches.
    void
    delete(Stream<E> entities, int batchSize)
    Deletes a stream of entities from the database in configurable batch sizes.
    void
    deleteAll()
    Deletes all entities from the database.
    boolean
    existsById(ID id)
    Checks if an entity with the specified primary key exists in the database.
    boolean
    existsByRef(Ref<E> ref)
    Checks if an entity with the specified primary key exists in the database.
    List<E>
    findAll()
    Returns a list of all entities of the type supported by this repository.
    List<E>
    findAllById(Iterable<ID> ids)
    Retrieves a list of entities based on their primary keys.
    List<E>
    findAllByRef(Iterable<Ref<E>> refs)
    Retrieves a list of entities based on their primary keys.
    Optional<E>
    findById(ID id)
    Retrieves an entity based on its primary key.
    Optional<E>
    findByRef(Ref<E> ref)
    Retrieves an entity based on its primary key, expressed by a ref.
    E
    getById(ID id)
    Retrieves an entity based on its primary key.
    E
    getByRef(Ref<E> ref)
    Retrieves an entity based on its primary key, expressed by a ref.
    void
    insert(E entity)
    Inserts an entity into the database.
    void
    insert(Iterable<E> entities)
    Inserts a collection of entities into the database in batches.
    void
    insert(Stream<E> entities)
    Inserts entities in a batch mode to optimize performance and reduce database load.
    void
    insert(Stream<E> entities, int batchSize)
    Inserts a stream of entities into the database, with the insertion process divided into batches of the specified size.
    E
    insertAndFetch(E entity)
    Inserts a single entity into the database and returns the inserted entity with its current state.
    List<E>
    insertAndFetch(Iterable<E> entities)
    Inserts a collection of entities into the database in batches.
    void
    insertAndFetch(Stream<E> entities, int batchSize, BatchCallback<E> callback)
    Inserts a stream of entities into the database with the insertion process divided into batches of the specified size, and returns a stream of the inserted entities.
    void
    insertAndFetch(Stream<E> entities, BatchCallback<E> callback)
    Inserts a stream of entities into the database using the default batch size and returns a stream of the inserted entities.
    ID
    insertAndFetchId(E entity)
    Inserts an entity into the database and returns its primary key.
    List<ID>
    insertAndFetchIds(Iterable<E> entities)
    Inserts a collection of entities into the database in batches.
    void
    insertAndFetchIds(Stream<E> entities, int batchSize, BatchCallback<ID> callback)
    Inserts a stream of entities into the database with the insertion process divided into batches of the specified size, and returns a stream of their generated primary keys.
    void
    insertAndFetchIds(Stream<E> entities, BatchCallback<ID> callback)
    Inserts a stream of entities into the database using the default batch size and returns a stream of their generated primary keys.
    Model<E,ID>
    model()
    Returns the entity model associated with this repository.
    Ref<E>
    ref(E entity)
    Creates a new ref entity instance for the specified entity.
    Ref<E>
    ref(ID id)
    Creates a new ref entity instance with the specified primary key.
    QueryBuilder<E,E,ID>
    select()
    Creates a new query builder for selecting entities of the type managed by this repository.
    <R> QueryBuilder<E,R,ID>
    select(Class<R> selectType)
    Creates a new query builder for the specialized selectType.
    <R> QueryBuilder<E,R,ID>
    select(Class<R> selectType, StringTemplatePREVIEW template)
    Creates a new query builder for the specialized selectType and specialized template for the select clause.
    Stream<E>
    selectAll()
    Returns a stream of all entities of the type supported by this repository.
    default <R> R
    selectAll(ResultCallback<E,R> callback)
    Processes a stream of all entities of the type supported by this repository using the specified callback.
    Stream<E>
    selectAllById(Stream<ID> ids)
    Retrieves a stream of entities based on their primary keys.
    Stream<E>
    selectAllById(Stream<ID> ids, int batchSize)
    Retrieves a stream of entities based on their primary keys.
    default <R> R
    selectAllById(Stream<ID> ids, int batchSize, ResultCallback<E,R> callback)
    Retrieves a stream of entities based on their primary keys.
    default <R> R
    selectAllById(Stream<ID> ids, ResultCallback<E,R> callback)
    Processes a stream of entities corresponding to the provided IDs using the specified callback.
    Stream<E>
    selectAllByRef(Stream<Ref<E>> refs)
    Retrieves a stream of entities based on their primary keys.
    Stream<E>
    selectAllByRef(Stream<Ref<E>> refs, int batchSize)
    Retrieves a stream of entities based on their primary keys.
    default <R> R
    selectAllByRef(Stream<Ref<E>> refs, int batchSize, ResultCallback<E,R> callback)
    Retrieves a stream of entities based on their primary keys.
    default <R> R
    selectAllByRef(Stream<Ref<E>> refs, ResultCallback<E,R> callback)
    Processes a stream of entities corresponding to the provided IDs using the specified callback.
    QueryBuilder<E,Long,ID>
    selectCount()
    Creates a new query builder for the entity type managed by this repository.
    QueryBuilder<E,Ref<E>,ID>
    selectRef()
    Creates a new query builder for selecting refs to entities of the type managed by this repository.
    <R extends Record & Entity<?>>
    QueryBuilder<E,Ref<R>,ID>
    selectRef(Class<R> refType)
    Creates a new query builder for selecting refs to entities of the type managed by this repository.
    Ref<E>
    unload(E entity)
    Unloads the given entity from memory by converting it into a lightweight ref containing only its primary key.
    void
    update(E entity)
    Updates a single entity in the database.
    void
    update(Iterable<E> entities)
    Updates a collection of entities in the database in batches.
    void
    update(Stream<E> entities)
    Updates a stream of entities in the database using the default batch size.
    void
    update(Stream<E> entities, int batchSize)
    Updates a stream of entities in the database, with the update process divided into batches of the specified size.
    E
    updateAndFetch(E entity)
    Updates a single entity in the database and returns the updated entity with its current state.
    List<E>
    updateAndFetch(Iterable<E> entities)
    Updates a collection of entities in the database in batches and returns a list of the updated entities.
    void
    updateAndFetch(Stream<E> entities, int batchSize, BatchCallback<E> callback)
    Updates a stream of entities in the database, with the update process divided into batches of the specified size, and returns a stream of the updated entities.
    void
    updateAndFetch(Stream<E> entities, BatchCallback<E> callback)
    Updates a stream of entities in the database using the default batch size and returns a stream of the updated entities.
    void
    upsert(E entity)
    Inserts or updates a single entity in the database.
    void
    upsert(Iterable<E> entities)
    Inserts or updates a collection of entities in the database in batches.
    void
    upsert(Stream<E> entities)
    Inserts or updates a stream of entities in the database in batches.
    void
    upsert(Stream<E> entities, int batchSize)
    Inserts or updates a stream of entities in the database in configurable batch sizes.
    E
    upsertAndFetch(E entity)
    Inserts or updates a single entity in the database and returns the entity with its current state.
    List<E>
    upsertAndFetch(Iterable<E> entities)
    Inserts or updates a collection of entities in the database in batches and returns a list of the upserted entities.
    void
    upsertAndFetch(Stream<E> entities, int batchSize, BatchCallback<E> callback)
    Inserts or updates a stream of entities in the database in configurable batch sizes and retrieves the updated entities through a callback.
    void
    upsertAndFetch(Stream<E> entities, BatchCallback<E> callback)
    Inserts or updates a stream of entities in the database in batches and retrieves the updated entities through a callback.
    ID
    upsertAndFetchId(E entity)
    Inserts or updates a single entity in the database and returns its ID.
    List<ID>
    upsertAndFetchIds(Iterable<E> entities)
    Inserts or updates a collection of entities in the database in batches and returns a list of their IDs.
    void
    upsertAndFetchIds(Stream<E> entities, int batchSize, BatchCallback<ID> callback)
    Inserts or updates a stream of entities in the database in configurable batch sizes and retrieves their IDs through a callback.
    void
    upsertAndFetchIds(Stream<E> entities, BatchCallback<ID> callback)
    Inserts or updates a stream of entities in the database in batches and retrieves their IDs through a callback.

    Methods inherited from interface st.orm.repository.Repository

    orm

  • Method Details

    • model

      Model<E,ID> model()
      Returns the entity model associated with this repository.
      Returns:
      the entity model.

    • ref

      Ref<E> ref(@Nonnull ID id)
      Creates a new ref entity instance with the specified primary key.

      This method creates a lightweight reference that encapsulates only the primary key of an entity, without loading the full entity data into memory. The complete record can be fetched on demand by invoking Ref.fetch(), which will trigger a separate database call.

      Parameters:
      id - the primary key of the entity.
      Returns:
      a ref entity instance containing only the primary key.
      Since:
      1.3

    • ref

      Ref<E> ref(@Nonnull E entity)
      Creates a new ref entity instance for the specified entity.

      This method wraps a fully loaded entity in a lightweight reference. Although the complete entity is provided, the returned ref retains only the primary key for identification. In this case, calling Ref.fetch() will return the full entity (which is already loaded), ensuring a consistent API for accessing entity records on demand. This approach supports lazy-loading scenarios where only the identifier is needed initially.

      Parameters:
      entity - the entity to wrap in a ref.
      Returns:
      a ref entity instance containing the primary key of the provided entity.
      Since:
      1.3

    • unload

      Ref<E> unload(@Nonnull E entity)
      Unloads the given entity from memory by converting it into a lightweight ref containing only its primary key.

      This method discards the full entity data and returns a ref that encapsulates just the primary key. The actual record is not retained in memory, but can be retrieved on demand by calling Ref.fetch(), which will trigger a new database call. This approach is particularly useful when you need to minimize memory usage while keeping the option to re-fetch the complete record later.

      Parameters:
      entity - the entity to unload into a lightweight ref.
      Returns:
      a ref containing only the primary key of the entity, allowing the full record to be fetched again when needed.
      Since:
      1.3

    • select

      QueryBuilder<E,E,ID> select()
      Creates a new query builder for selecting entities of the type managed by this repository.
      Returns:
      a new query builder for the entity type.

    • selectCount

      QueryBuilder<E,Long,ID> selectCount()
      Creates a new query builder for the entity type managed by this repository.
      Returns:
      a new query builder for the entity type.

    • select

      <R> QueryBuilder<E,R,ID> select(@Nonnull Class<R> selectType)
      Creates a new query builder for the specialized selectType.
      Type Parameters:
      R - the result type of the query.
      Parameters:
      selectType - the result type of the query.
      Returns:
      a new query builder for the specialized selectType.

    • selectRef

      QueryBuilder<E,Ref<E>,ID> selectRef()
      Creates a new query builder for selecting refs to entities of the type managed by this repository.

      This method is typically used when you only need the primary keys of the entities initially, and you want to defer fetching the full data until it is actually required. The query builder will return ref instances that encapsulate the primary key. To retrieve the full entity, call Ref.fetch(), which will perform an additional database query on demand.

      Returns:
      a new query builder for selecting refs to entities.
      Since:
      1.3

    • select

      <R> QueryBuilder<E,R,ID> select(@Nonnull Class<R> selectType, @Nonnull StringTemplatePREVIEW template)
      Creates a new query builder for the specialized selectType and specialized template for the select clause.
      Type Parameters:
      R - the result type of the query.
      Parameters:
      selectType - the result type of the query.
      template - the specialized template for the select clause.
      Returns:
      a new query builder for the specialized selectType.

    • selectRef

      <R extends Record & Entity<?>> QueryBuilder<E,Ref<R>,ID> selectRef(@Nonnull Class<R> refType)
      Creates a new query builder for selecting refs to entities of the type managed by this repository.

      This method is typically used when you only need the primary keys of the entities initially, and you want to defer fetching the full data until it is actually required. The query builder will return ref instances that encapsulate the primary key. To retrieve the full entity, call Ref.fetch(), which will perform an additional database query on demand.

      Parameters:
      refType - the type that is selected as ref.
      Returns:
      a new query builder for selecting refs to entities.
      Since:
      1.3

    • delete

      QueryBuilder<E,?,ID> delete()
      Creates a new query builder for delete entities of the type managed by this repository.
      Returns:
      a new query builder for the entity type.

    • count

      long count()
      Returns the number of entities in the database of the entity type supported by this repository.
      Returns:
      the total number of entities in the database as a long value.
      Throws:
      PersistenceException - if the count operation fails due to underlying database issues, such as connectivity.

    • existsById

      boolean existsById(@Nonnull ID id)
      Checks if an entity with the specified primary key exists in the database.

      This method determines the presence of an entity by checking if the count of entities with the given primary key is greater than zero. It leverages the selectCount method, which performs a count operation on the database.

      Parameters:
      id - the primary key of the entity to check for existence.
      Returns:
      true if an entity with the specified primary key exists, false otherwise.
      Throws:
      PersistenceException - if there is an underlying database issue during the count operation.

    • existsByRef

      boolean existsByRef(@Nonnull Ref<E> ref)
      Checks if an entity with the specified primary key exists in the database.

      This method determines the presence of an entity by checking if the count of entities with the given primary key is greater than zero. It leverages the selectCount method, which performs a count operation on the database.

      Parameters:
      ref - the primary key of the entity to check for existence, expressed as a ref.
      Returns:
      true if an entity with the specified primary key exists, false otherwise.
      Throws:
      PersistenceException - if there is an underlying database issue during the count operation.

    • insert

      void insert(@Nonnull E entity)
      Inserts an entity into the database.

      This method adds a new entity to the database. It ensures that the entity is persisted according to the defined database constraints and entity model. It's critical for the entity to be fully initialized as per the entity model requirements.

      Parameters:
      entity - the entity to insert. The entity must satisfy all model constraints.
      Throws:
      PersistenceException - if the insert operation fails. This can happen due to a variety of reasons, including database constraints violations, connectivity issues, or if the entity parameter is null.

    • insertAndFetchId

      ID insertAndFetchId(@Nonnull E entity)
      Inserts an entity into the database and returns its primary key.

      This method adds a new entity to the database and upon successful insertion, returns the primary key assigned to the entity when the primary key is generated by the database (e.g., auto-incremented). Otherwise, if the primary key is not generated by the database, the method returns an empty optional.

      Parameters:
      entity - the entity to insert. The entity must satisfy all model constraints.
      Returns:
      the generated primary key of the successfully inserted entity.
      Throws:
      PersistenceException - if the insert operation fails for reasons such as database constraints violations, connectivity issues, or if the entity parameter is null.

    • insertAndFetch

      E insertAndFetch(@Nonnull E entity)
      Inserts a single entity into the database and returns the inserted entity with its current state.

      This method inserts the provided entity into the database. Upon successful insertion, it returns the entity as it exists in the database after the operation. This ensures that the returned entity includes any modifications applied during the insertion process, such as generated primary keys, default values, or other automatic changes triggered by the database.

      Parameters:
      entity - the entity to be inserted. The entity must be non-null and contain valid data for insertion into the database.
      Returns:
      the inserted entity, reflecting its state in the database after insertion. This includes any database-applied changes such as primary key assignments or default values.
      Throws:
      PersistenceException - if the insertion operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • update

      void update(@Nonnull E entity)
      Updates a single entity in the database.

      This method updates the provided entity in the database, modifying its existing record to reflect the current state of the entity. It is intended for cases where only one entity needs to be updated.

      Parameters:
      entity - the entity to be updated. The entity must be non-null and contain valid data for updating its corresponding record in the database.
      Throws:
      PersistenceException - if the update operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • updateAndFetch

      E updateAndFetch(@Nonnull E entity)
      Updates a single entity in the database and returns the updated entity with its current state.

      This method updates the provided entity in the database and, upon successful completion, returns the entity as it exists in the database after the update operation. This ensures that the returned entity reflects any modifications applied during the update process, such as updated timestamps, versioning, or other automatic changes triggered by the database.

      Parameters:
      entity - the entity to be updated. The entity must be non-null and contain valid data for updating its corresponding record in the database.
      Returns:
      the updated entity, reflecting its state in the database after the update. This includes any database-applied changes such as modified timestamps or version numbers.
      Throws:
      PersistenceException - if the update operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • upsert

      void upsert(@Nonnull E entity)
      Inserts or updates a single entity in the database.

      This method performs an "upsert" operation on the provided entity. If the entity does not already exist in the database, it will be inserted. If it does exist, it will be updated to reflect the current state of the entity. This approach ensures that the entity is either created or brought up-to-date, depending on its existence in the database.

      Parameters:
      entity - the entity to be inserted or updated. The entity must be non-null and contain valid data for insertion or update in the database.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • upsertAndFetchId

      ID upsertAndFetchId(@Nonnull E entity)
      Inserts or updates a single entity in the database and returns its ID.

      This method performs an "upsert" operation on the provided entity. If the entity does not already exist in the database, it will be inserted; if it exists, it will be updated. Upon successful completion, the method returns the ID of the entity as stored in the database. This approach ensures that the entity is either created or brought up-to-date, depending on its existence in the database.

      Parameters:
      entity - the entity to be inserted or updated. The entity must be non-null and contain valid data for insertion or update in the database.
      Returns:
      the ID of the upserted entity, reflecting its identifier in the database.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • upsertAndFetch

      E upsertAndFetch(@Nonnull E entity)
      Inserts or updates a single entity in the database and returns the entity with its current state.

      This method performs an "upsert" operation on the provided entity. If the entity does not already exist in the database, it will be inserted; if it exists, it will be updated. Upon successful completion, the method returns the entity as it exists in the database after the upsert operation. This ensures that the returned entity reflects any modifications applied during the upsert process, such as generated primary keys, updated timestamps, or default values set by the database.

      Parameters:
      entity - the entity to be inserted or updated. The entity must be non-null and contain valid data for insertion or update in the database.
      Returns:
      the upserted entity, reflecting its current state in the database. This includes any database-applied changes, such as primary key assignments, default values, or timestamp updates.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • delete

      void delete(@Nonnull ID id)
      Deletes an entity from the database based on its primary key.

      This method removes an existing entity from the database. It is important to ensure that the entity passed for deletion exists in the database.

      Parameters:
      id - the primary key of the entity to delete.
      Throws:
      PersistenceException - if the deletion operation fails. Reasons for failure might include the entity not being found in the database, violations of database constraints, connectivity issues, or if the entity parameter is null.

    • delete

      void delete(@Nonnull E entity)
      Deletes an entity from the database.

      This method removes an existing entity from the database. It is important to ensure that the entity passed for deletion exists in the database and is correctly identified by its primary key.

      Parameters:
      entity - the entity to delete. The entity must exist in the database and should be correctly identified by its primary key.
      Throws:
      PersistenceException - if the deletion operation fails. Reasons for failure might include the entity not being found in the database, violations of database constraints, connectivity issues, or if the entity parameter is null.

    • deleteAll

      void deleteAll()
      Deletes all entities from the database.

      This method performs a bulk deletion operation, removing all instances of the entities managed by this repository from the database.

      Throws:
      PersistenceException - if the bulk deletion operation fails. Failure can occur for several reasons, including but not limited to database access issues, transaction failures, or underlying database constraints that prevent the deletion of certain records.

    • findById

      Optional<E> findById(@Nonnull ID id)
      Retrieves an entity based on its primary key.

      This method performs a lookup in the database, returning the corresponding entity if it exists.

      Parameters:
      id - the primary key of the entity to retrieve.
      Returns:
      the entity associated with the provided primary key. The returned entity encapsulates all relevant data as mapped by the entity model.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues, such as connectivity problems or query execution errors.

    • findByRef

      Optional<E> findByRef(@Nonnull Ref<E> ref)
      Retrieves an entity based on its primary key, expressed by a ref.

      This method performs a lookup in the database, returning the corresponding entity if it exists.

      Parameters:
      ref - the ref to match.
      Returns:
      the entity associated with the provided primary key. The returned entity encapsulates all relevant data as mapped by the entity model.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues, such as connectivity problems or query execution errors.

    • getById

      E getById(@Nonnull ID id)
      Retrieves an entity based on its primary key.

      This method performs a lookup in the database, returning the corresponding entity if it exists.

      Parameters:
      id - the primary key of the entity to retrieve.
      Returns:
      the entity associated with the provided primary key. The returned entity encapsulates all relevant data as mapped by the entity model.
      Throws:
      NoResultException - if no entity is found matching the given primary key, indicating that there's no corresponding data in the database.
      PersistenceException - if the retrieval operation fails due to underlying database issues, such as connectivity problems or query execution errors.

    • getByRef

      E getByRef(@Nonnull Ref<E> ref)
      Retrieves an entity based on its primary key, expressed by a ref.

      This method performs a lookup in the database, returning the corresponding entity if it exists.

      Parameters:
      ref - the ref to match.
      Returns:
      the entity associated with the provided primary key. The returned entity encapsulates all relevant data as mapped by the entity model.
      Throws:
      NoResultException - if no entity is found matching the given primary key, indicating that there's no corresponding data in the database.
      PersistenceException - if the retrieval operation fails due to underlying database issues, such as connectivity problems or query execution errors.

    • findAll

      List<E> findAll()
      Returns a list of all entities of the type supported by this repository. Each element in the list represents an entity in the database, encapsulating all relevant data as mapped by the entity model.

      Please note: loading all entities into memory at once can be very memory-intensive if your table is large.

      Returns:
      a stream of all entities of the type supported by this repository.
      Throws:
      PersistenceException - if the selection operation fails due to underlying database issues, such as connectivity.

    • findAllById

      List<E> findAllById(@Nonnull Iterable<ID> ids)
      Retrieves a list of entities based on their primary keys.

      This method retrieves entities matching the provided IDs in batches, consolidating them into a single list. The batch-based retrieval minimizes database overhead, allowing efficient handling of larger collections of IDs. Note that the order of entities in the returned list is not guaranteed to match the order of IDs in the input collection, as the database may not preserve insertion order during retrieval.

      Parameters:
      ids - the primary keys of the entities to retrieve, represented as an iterable collection.
      Returns:
      a list of entities corresponding to the provided primary keys. Entities are returned without any guarantee of order alignment with the input list. If an ID does not correspond to any entity in the database, no corresponding entity will be included in the returned list.
      Throws:
      PersistenceException - if the selection operation fails due to database issues, such as connectivity problems or invalid input parameters.

    • findAllByRef

      List<E> findAllByRef(@Nonnull Iterable<Ref<E>> refs)
      Retrieves a list of entities based on their primary keys.

      This method retrieves entities matching the provided IDs in batches, consolidating them into a single list. The batch-based retrieval minimizes database overhead, allowing efficient handling of larger collections of IDs. Note that the order of entities in the returned list is not guaranteed to match the order of IDs in the input collection, as the database may not preserve insertion order during retrieval.

      Parameters:
      refs - the primary keys of the entities to retrieve, represented as an iterable collection.
      Returns:
      a list of entities corresponding to the provided primary keys. Entities are returned without any guarantee of order alignment with the input list. If an ID does not correspond to any entity in the database, no corresponding entity will be included in the returned list.
      Throws:
      PersistenceException - if the selection operation fails due to database issues, such as connectivity problems or invalid input parameters.

    • insert

      void insert(@Nonnull Iterable<E> entities)
      Inserts a collection of entities into the database in batches.

      This method processes the provided entities in batches, optimizing insertion for larger collections by reducing database overhead. Batch processing helps ensure that even large numbers of entities can be inserted efficiently and minimizes potential memory and performance issues.

      Parameters:
      entities - an iterable collection of entities to be inserted. Each entity in the collection must be non-null and contain valid data for insertion.
      Throws:
      PersistenceException - if the insertion operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • insertAndFetchIds

      List<ID> insertAndFetchIds(@Nonnull Iterable<E> entities)
      Inserts a collection of entities into the database in batches.

      This method processes the provided entities in batches, optimizing insertion for larger collections by reducing database overhead. Batch processing helps ensure that even large numbers of entities can be inserted efficiently and minimizes potential memory and performance issues.

      Upon successful insertion, it returns the primary keys assigned to the entities when the primary keys are generated by the database (e.g., auto-incremented). Otherwise, if the primary keys are not generated by the database, the method returns an empty list.

      Parameters:
      entities - an iterable collection of entities to be inserted. Each entity in the collection must be non-null and contain valid data for insertion.
      Returns:
      the primary keys assigned to the entities when the primary keys are generated by the database,
      Throws:
      PersistenceException - if the insertion operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • insertAndFetch

      List<E> insertAndFetch(@Nonnull Iterable<E> entities)
      Inserts a collection of entities into the database in batches.

      This method processes the provided entities in batches, optimizing insertion for larger collections by reducing database overhead. Batch processing helps ensure that even large numbers of entities can be inserted efficiently and minimizes potential memory and performance issues.

      Upon successful insertion, it returns the entities that were inserted. The returned entities reflect the state of the entities as they exist in the database after the insertion operation. This ensures that the returned entities include any changes that might have been applied during the insertion process, such as primary key, default values or triggers.

      Parameters:
      entities - an iterable collection of entities to be inserted. Each entity in the collection must be non-null and contain valid data for insertion.
      Returns:
      the entities that were inserted into the database.
      Throws:
      PersistenceException - if the insertion operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • update

      void update(@Nonnull Iterable<E> entities)
      Updates a collection of entities in the database in batches.

      This method processes the provided entities in batches to optimize updating of larger collections, reducing database overhead and improving performance. Batch processing allows efficient handling of bulk updates, minimizing memory and processing costs.

      Parameters:
      entities - an iterable collection of entities to be updated. Each entity in the collection must be non-null and contain valid, up-to-date data for modification in the database.
      Throws:
      PersistenceException - if the update operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • updateAndFetch

      List<E> updateAndFetch(@Nonnull Iterable<E> entities)
      Updates a collection of entities in the database in batches and returns a list of the updated entities.

      This method processes the provided entities in batches, optimizing performance for larger collections by reducing database overhead. Upon successful update, it returns the entities as they exist in the database after the update operation. This ensures that the returned entities reflect any modifications applied during the update process, such as updated timestamps, versioning, or other automatic changes made by the database.

      Parameters:
      entities - an iterable collection of entities to be updated. Each entity in the collection must be non-null and contain valid data for modification in the database.
      Returns:
      a list of entities reflecting their state in the database after the update. The order of entities in the returned list is not guaranteed to match the order of the input collection.
      Throws:
      PersistenceException - if the update operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • upsert

      void upsert(@Nonnull Iterable<E> entities)
      Inserts or updates a collection of entities in the database in batches.

      This method processes the provided entities in batches, optimizing performance for larger collections by reducing database overhead. For each entity, the method performs an "upsert" operation, meaning it will insert the entity if it does not already exist in the database, or update it if it does. This approach ensures that the entities are either created or brought up-to-date, depending on their existence in the database.

      Parameters:
      entities - an iterable collection of entities to be inserted or updated. Each entity in the collection must be non-null and contain valid data for insertion or update in the database.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • upsertAndFetchIds

      List<ID> upsertAndFetchIds(@Nonnull Iterable<E> entities)
      Inserts or updates a collection of entities in the database in batches and returns a list of their IDs.

      This method processes the provided entities in batches to optimize performance for larger collections, reducing database overhead. For each entity, the method performs an "upsert" operation, inserting the entity if it does not already exist in the database, or updating it if it does. Upon successful completion, the method returns a list of the IDs of the upserted entities, reflecting their identifiers as stored in the database.

      Parameters:
      entities - an iterable collection of entities to be inserted or updated. Each entity in the collection must be non-null and contain valid data for insertion or update in the database.
      Returns:
      a list of IDs corresponding to the upserted entities. The order of IDs in the returned list is not guaranteed to match the order of the input collection.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • upsertAndFetch

      List<E> upsertAndFetch(@Nonnull Iterable<E> entities)
      Inserts or updates a collection of entities in the database in batches and returns a list of the upserted entities.

      This method processes the provided entities in batches, optimizing performance for larger collections by reducing database overhead. For each entity, it performs an "upsert" operation, inserting the entity if it does not already exist in the database, or updating it if it does. Upon successful completion, it returns the entities as they exist in the database after the operation. This ensures that the returned entities reflect any changes applied during the upsert process, such as generated primary keys, updated timestamps, or default values set by the database.

      Parameters:
      entities - an iterable collection of entities to be inserted or updated. Each entity in the collection must be non-null and contain valid data for insertion or update in the database.
      Returns:
      a list of upserted entities reflecting their current state in the database. The order of entities in the returned list is not guaranteed to match the order of the input collection.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • delete

      void delete(@Nonnull Iterable<E> entities)
      Deletes a collection of entities from the database in batches.

      This method processes the provided entities in batches to optimize performance when handling larger collections, reducing database overhead. For each entity in the collection, the method removes the corresponding record from the database, if it exists. Batch processing ensures efficient handling of deletions, particularly for large data sets.

      Parameters:
      entities - an iterable collection of entities to be deleted. Each entity in the collection must be non-null and represent a valid database record for deletion.
      Throws:
      PersistenceException - if the deletion operation fails due to database issues, such as connectivity problems or constraints violations.

    • selectAll

      Stream<E> selectAll()
      Returns a stream of all entities of the type supported by this repository. Each element in the stream represents an entity in the database, encapsulating all relevant data as mapped by the entity model.

      The resulting stream is lazily loaded, meaning that the entities are only retrieved from the database as they are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when dealing with large volumes of entities.

      Note that calling this method does trigger the execution of the underlying query, so it should only be invoked when the query is intended to run. Since the stream holds resources open while in use, it must be closed after usage to prevent resource leaks. As the stream is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Returns:
      a stream of all entities of the type supported by this repository.
      Throws:
      PersistenceException - if the selection operation fails due to underlying database issues, such as connectivity.

    • selectAll

      default <R> R selectAll(@Nonnull ResultCallback<E,R> callback)
      Processes a stream of all entities of the type supported by this repository using the specified callback. This method retrieves the entities and applies the provided callback to process them, returning the result produced by the callback.

      This method ensures efficient handling of large data sets by loading entities only as needed. It also manages lifecycle of the callback stream, automatically closing the stream after processing to prevent resource leaks.

      Type Parameters:
      R - the type of result produced by the callback after processing the entities.
      Parameters:
      callback - a ResultCallback defining how to process the stream of entities and produce a result.
      Returns:
      the result produced by the callback's processing of the entity stream.
      Throws:
      PersistenceException - if the operation fails due to underlying database issues, such as connectivity.

    • selectAllById

      Stream<E> selectAllById(@Nonnull Stream<ID> ids)
      Retrieves a stream of entities based on their primary keys.

      This method executes queries in batches, depending on the number of primary keys in the specified ids stream. This optimization aims to reduce the overhead of executing multiple queries and efficiently retrieve entities. The batching strategy enhances performance, particularly when dealing with large sets of primary keys.

      The resulting stream is lazily loaded, meaning that the entities are only retrieved from the database as they are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when dealing with large volumes of entities.

      Note that calling this method does trigger the execution of the underlying query, so it should only be invoked when the query is intended to run. Since the stream holds resources open while in use, it must be closed after usage to prevent resource leaks. As the stream is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Parameters:
      ids - a stream of entity IDs to retrieve from the repository.
      Returns:
      a stream of entities corresponding to the provided primary keys. The order of entities in the stream is not guaranteed to match the order of ids in the input stream. If an id does not correspond to any entity in the database, it will simply be skipped, and no corresponding entity will be included in the returned stream. If the same entity is requested multiple times, it may be included in the stream multiple times if it is part of a separate batch.
      Throws:
      PersistenceException - if the selection operation fails due to underlying database issues, such as connectivity.

    • selectAllById

      default <R> R selectAllById(@Nonnull Stream<ID> ids, @Nonnull ResultCallback<E,R> callback)
      Processes a stream of entities corresponding to the provided IDs using the specified callback. This method retrieves entities matching the given IDs and applies the callback to process the results, returning the outcome produced by the callback.

      This method is designed for efficient data handling by only retrieving specified entities as needed. It also manages the lifecycle of the callback stream, automatically closing the stream after processing to prevent resource leaks.

      Type Parameters:
      R - the type of result produced by the callback after processing the entities.
      Parameters:
      ids - a stream of entity IDs to retrieve from the repository.
      callback - a ResultCallback defining how to process the stream of entities and produce a result.
      Returns:
      the result produced by the callback's processing of the entity stream.
      Throws:
      PersistenceException - if the operation fails due to underlying database issues, such as connectivity.

    • selectAllByRef

      Stream<E> selectAllByRef(@Nonnull Stream<Ref<E>> refs)
      Retrieves a stream of entities based on their primary keys.

      This method executes queries in batches, depending on the number of primary keys in the specified ids stream. This optimization aims to reduce the overhead of executing multiple queries and efficiently retrieve entities. The batching strategy enhances performance, particularly when dealing with large sets of primary keys.

      The resulting stream is lazily loaded, meaning that the entities are only retrieved from the database as they are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when dealing with large volumes of entities.

      Note that calling this method does trigger the execution of the underlying query, so it should only be invoked when the query is intended to run. Since the stream holds resources open while in use, it must be closed after usage to prevent resource leaks. As the stream is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Parameters:
      refs - a stream of refs to retrieve from the repository.
      Returns:
      a stream of entities corresponding to the provided primary keys. The order of entities in the stream is not guaranteed to match the order of ids in the input stream. If an id does not correspond to any entity in the database, it will simply be skipped, and no corresponding entity will be included in the returned stream. If the same entity is requested multiple times, it may be included in the stream multiple times if it is part of a separate batch.
      Throws:
      PersistenceException - if the selection operation fails due to underlying database issues, such as connectivity.

    • selectAllByRef

      default <R> R selectAllByRef(@Nonnull Stream<Ref<E>> refs, @Nonnull ResultCallback<E,R> callback)
      Processes a stream of entities corresponding to the provided IDs using the specified callback. This method retrieves entities matching the given IDs and applies the callback to process the results, returning the outcome produced by the callback.

      This method is designed for efficient data handling by only retrieving specified entities as needed. It also manages the lifecycle of the callback stream, automatically closing the stream after processing to prevent resource leaks.

      Type Parameters:
      R - the type of result produced by the callback after processing the entities.
      Parameters:
      refs - a stream of refs to retrieve from the repository.
      callback - a ResultCallback defining how to process the stream of entities and produce a result.
      Returns:
      the result produced by the callback's processing of the entity stream.
      Throws:
      PersistenceException - if the operation fails due to underlying database issues, such as connectivity.

    • selectAllById

      Stream<E> selectAllById(@Nonnull Stream<ID> ids, int batchSize)
      Retrieves a stream of entities based on their primary keys.

      This method executes queries in batches, with the batch size determined by the provided parameter. This optimization aims to reduce the overhead of executing multiple queries and efficiently retrieve entities. The batching strategy enhances performance, particularly when dealing with large sets of primary keys.

      The resulting stream is lazily loaded, meaning that the entities are only retrieved from the database as they are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when dealing with large volumes of entities.

      Note that calling this method does trigger the execution of the underlying query, so it should only be invoked when the query is intended to run. Since the stream holds resources open while in use, it must be closed after usage to prevent resource leaks. As the stream is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Parameters:
      ids - a stream of entity IDs to retrieve from the repository.
      batchSize - the number of primary keys to include in each batch. This parameter determines the size of the batches used to execute the selection operation. A larger batch size can improve performance, especially when dealing with large sets of primary keys.
      Returns:
      a stream of entities corresponding to the provided primary keys. The order of entities in the stream is not guaranteed to match the order of refs in the input stream. If an id does not correspond to any entity in the database, it will simply be skipped, and no corresponding entity will be included in the returned stream. If the same entity is requested multiple times, it may be included in the stream multiple times if it is part of a separate batch.
      Throws:
      PersistenceException - if the selection operation fails due to underlying database issues, such as connectivity.

    • selectAllById

      default <R> R selectAllById(@Nonnull Stream<ID> ids, int batchSize, @Nonnull ResultCallback<E,R> callback)
      Retrieves a stream of entities based on their primary keys.

      This method executes queries in batches, with the batch size determined by the provided parameter. This optimization aims to reduce the overhead of executing multiple queries and efficiently retrieve entities. The batching strategy enhances performance, particularly when dealing with large sets of primary keys.

      The resulting stream is lazily loaded, meaning that the entities are only retrieved from the database as they are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when dealing with large volumes of entities.

      Note that calling this method does trigger the execution of the underlying query, so it should only be invoked when the query is intended to run. Since the stream holds resources open while in use, it must be closed after usage to prevent resource leaks. As the stream is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Parameters:
      ids - a stream of entity IDs to retrieve from the repository.
      batchSize - the number of primary keys to include in each batch. This parameter determines the size of the batches used to execute the selection operation. A larger batch size can improve performance, especially when dealing with large sets of primary keys.
      Returns:
      a stream of entities corresponding to the provided primary keys. The order of entities in the stream is not guaranteed to match the order of refs in the input stream. If an id does not correspond to any entity in the database, it will simply be skipped, and no corresponding entity will be included in the returned stream. If the same entity is requested multiple times, it may be included in the stream multiple times if it is part of a separate batch.
      Throws:
      PersistenceException - if the selection operation fails due to underlying database issues, such as connectivity.

    • selectAllByRef

      Stream<E> selectAllByRef(@Nonnull Stream<Ref<E>> refs, int batchSize)
      Retrieves a stream of entities based on their primary keys.

      This method executes queries in batches, with the batch size determined by the provided parameter. This optimization aims to reduce the overhead of executing multiple queries and efficiently retrieve entities. The batching strategy enhances performance, particularly when dealing with large sets of primary keys.

      The resulting stream is lazily loaded, meaning that the entities are only retrieved from the database as they are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when dealing with large volumes of entities.

      Note that calling this method does trigger the execution of the underlying query, so it should only be invoked when the query is intended to run. Since the stream holds resources open while in use, it must be closed after usage to prevent resource leaks. As the stream is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Parameters:
      refs - a stream of refs to retrieve from the repository.
      batchSize - the number of primary keys to include in each batch. This parameter determines the size of the batches used to execute the selection operation. A larger batch size can improve performance, especially when dealing with large sets of primary keys.
      Returns:
      a stream of entities corresponding to the provided primary keys. The order of entities in the stream is not guaranteed to match the order of refs in the input stream. If an id does not correspond to any entity in the database, it will simply be skipped, and no corresponding entity will be included in the returned stream. If the same entity is requested multiple times, it may be included in the stream multiple times if it is part of a separate batch.
      Throws:
      PersistenceException - if the selection operation fails due to underlying database issues, such as connectivity.

    • selectAllByRef

      default <R> R selectAllByRef(@Nonnull Stream<Ref<E>> refs, int batchSize, @Nonnull ResultCallback<E,R> callback)
      Retrieves a stream of entities based on their primary keys.

      This method executes queries in batches, with the batch size determined by the provided parameter. This optimization aims to reduce the overhead of executing multiple queries and efficiently retrieve entities. The batching strategy enhances performance, particularly when dealing with large sets of primary keys.

      The resulting stream is lazily loaded, meaning that the entities are only retrieved from the database as they are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when dealing with large volumes of entities.

      Note that calling this method does trigger the execution of the underlying query, so it should only be invoked when the query is intended to run. Since the stream holds resources open while in use, it must be closed after usage to prevent resource leaks. As the stream is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Parameters:
      batchSize - the number of primary keys to include in each batch. This parameter determines the size of the batches used to execute the selection operation. A larger batch size can improve performance, especially when dealing with large sets of primary keys.
      Returns:
      a stream of entities corresponding to the provided primary keys. The order of entities in the stream is not guaranteed to match the order of refs in the input stream. If an id does not correspond to any entity in the database, it will simply be skipped, and no corresponding entity will be included in the returned stream. If the same entity is requested multiple times, it may be included in the stream multiple times if it is part of a separate batch.
      Throws:
      PersistenceException - if the selection operation fails due to underlying database issues, such as connectivity.

    • countById

      long countById(@Nonnull Stream<ID> ids)
      Counts the number of entities identified by the provided stream of IDs using the default batch size.

      This method calculates the total number of entities that match the provided primary keys. The counting is performed in batches, which helps optimize performance and manage database load when dealing with large sets of IDs.

      Parameters:
      ids - a stream of IDs for which to count matching entities.
      Returns:
      the total count of entities matching the provided IDs.
      Throws:
      PersistenceException - if there is an error during the counting operation, such as connectivity issues.

    • countById

      long countById(@Nonnull Stream<ID> ids, int batchSize)
      Counts the number of entities identified by the provided stream of IDs, with the counting process divided into batches of the specified size.

      This method performs the counting operation in batches, specified by the batchSize parameter. This batching approach is particularly useful for efficiently handling large volumes of IDs, reducing the overhead on the database and improving performance.

      Parameters:
      ids - a stream of IDs for which to count matching entities.
      batchSize - the size of the batches to use for the counting operation. A larger batch size can improve performance but may also increase the load on the database.
      Returns:
      the total count of entities matching the provided IDs.
      Throws:
      PersistenceException - if there is an error during the counting operation, such as connectivity issues.

    • countByRef

      long countByRef(@Nonnull Stream<Ref<E>> refs)
      Counts the number of entities identified by the provided stream of refs using the default batch size.

      This method calculates the total number of entities that match the provided primary keys. The counting is performed in batches, which helps optimize performance and manage database load when dealing with large sets of IDs.

      Parameters:
      refs - a stream of IDs for which to count matching entities.
      Returns:
      the total count of entities matching the provided IDs.
      Throws:
      PersistenceException - if there is an error during the counting operation, such as connectivity issues.

    • countByRef

      long countByRef(@Nonnull Stream<Ref<E>> refs, int batchSize)
      Counts the number of entities identified by the provided stream of refs, with the counting process divided into batches of the specified size.

      This method performs the counting operation in batches, specified by the batchSize parameter. This batching approach is particularly useful for efficiently handling large volumes of IDs, reducing the overhead on the database and improving performance.

      Parameters:
      refs - a stream of IDs for which to count matching entities.
      batchSize - the size of the batches to use for the counting operation. A larger batch size can improve performance but may also increase the load on the database.
      Returns:
      the total count of entities matching the provided IDs.
      Throws:
      PersistenceException - if there is an error during the counting operation, such as connectivity issues.

    • insert

      void insert(@Nonnull Stream<E> entities)
      Inserts entities in a batch mode to optimize performance and reduce database load.

      For large volumes of entities, this method processes the inserts in multiple batches to ensure efficient handling and minimize the impact on database resources. This structured approach facilitates the management of large-scale insert operations.

      Parameters:
      entities - the entities to insert. Must not be null.
      Throws:
      PersistenceException - if the insert fails due to database constraints, connectivity issues, or if the entities parameter is null.

    • insert

      void insert(@Nonnull Stream<E> entities, int batchSize)
      Inserts a stream of entities into the database, with the insertion process divided into batches of the specified size.

      This method inserts entities provided in a stream and uses the specified batch size for the insertion operation. Batching the inserts can greatly enhance performance by minimizing the number of database interactions, especially useful when dealing with large volumes of data.

      Parameters:
      entities - a stream of entities to insert. Each entity must not be null and must conform to the model constraints.
      batchSize - the size of the batches to use for the insertion operation. A larger batch size can improve performance but may also increase the load on the database.
      Throws:
      PersistenceException - if there is an error during the insertion operation, such as a violation of database constraints, connectivity issues, or if any entity in the stream is null.

    • insertAndFetchIds

      void insertAndFetchIds(@Nonnull Stream<E> entities, @Nonnull BatchCallback<ID> callback)
      Inserts a stream of entities into the database using the default batch size and returns a stream of their generated primary keys.

      This method facilitates the insertion of entities and fetches their primary keys immediately after insertion. This is particularly useful when the primary keys are generated by the database (e.g., auto-increment fields). It uses the default batch size to optimize the number of database interactions.

      Parameters:
      entities - a stream of entities to insert. Each entity must not be null and must conform to the model constraints.
      callback - the callback to process the IDs of the inserted entities in batches.
      Throws:
      PersistenceException - if there is an error during the insertion or key retrieval operation, such as a violation of database constraints, connectivity issues, or if any entity in the stream is null.

    • insertAndFetch

      void insertAndFetch(@Nonnull Stream<E> entities, @Nonnull BatchCallback<E> callback)
      Inserts a stream of entities into the database using the default batch size and returns a stream of the inserted entities.

      This method inserts entities into the database and retrieves them immediately after insertion. It is useful for ensuring that the returned entities reflect any database-generated values or defaults. The insertion and retrieval are performed using the default batch size to optimize database performance.

      Parameters:
      entities - a stream of entities to insert. Each entity must not be null and must conform to the model constraints.
      callback - the callback to process the inserted entities, reflecting their new state in the database, in batches.
      Throws:
      PersistenceException - if there is an error during the insertion or retrieval operation, such as a violation of database constraints, connectivity issues, or if any entity in the stream is null.

    • insertAndFetchIds

      void insertAndFetchIds(@Nonnull Stream<E> entities, int batchSize, @Nonnull BatchCallback<ID> callback)
      Inserts a stream of entities into the database with the insertion process divided into batches of the specified size, and returns a stream of their generated primary keys.

      This method allows for efficient insertion of a large number of entities by batching them according to the specified batch size. It also fetches the primary keys immediately after insertion, useful for entities with database-generated keys.

      Parameters:
      entities - a stream of entities to insert. Each entity must not be null and must conform to the model constraints.
      batchSize - the size of the batches to use for the insertion operation. A larger batch size can improve performance but may also increase the load on the database.
      callback - the callback to process the IDs of the inserted entities in batches.
      Throws:
      PersistenceException - if there is an error during the insertion or key retrieval operation, such as a violation of database constraints, connectivity issues, or if any entity in the stream is null.

    • insertAndFetch

      void insertAndFetch(@Nonnull Stream<E> entities, int batchSize, @Nonnull BatchCallback<E> callback)
      Inserts a stream of entities into the database with the insertion process divided into batches of the specified size, and returns a stream of the inserted entities.

      This method provides an efficient way to insert a large number of entities by batching them according to the specified batch size. It fetches the inserted entities immediately after insertion to ensure that the returned entities reflect any database-generated values or defaults. This is particularly useful when database triggers or default values are involved.

      Parameters:
      entities - a stream of entities to insert. Each entity must not be null and must conform to the model constraints.
      batchSize - the size of the batches to use for the insertion operation. A larger batch size can improve performance but may also increase the load on the database.
      callback - the callback to process the inserted entities, reflecting their new state in the database, in batches.
      Throws:
      PersistenceException - if there is an error during the insertion or retrieval operation, such as a violation of database constraints, connectivity issues, or if any entity in the stream is null.

    • update

      void update(@Nonnull Stream<E> entities)
      Updates a stream of entities in the database using the default batch size.

      This method updates entities provided in a stream, optimizing the update process by batching them with a default size. This helps to reduce the number of database operations and can significantly improve performance when updating large numbers of entities.

      Parameters:
      entities - a stream of entities to update. Each entity must not be null, must already exist in the database, and must conform to the model constraints.
      Throws:
      PersistenceException - if there is an error during the update operation, such as a violation of database constraints, connectivity issues, or if any entity in the stream is null.

    • update

      void update(@Nonnull Stream<E> entities, int batchSize)
      Updates a stream of entities in the database, with the update process divided into batches of the specified size.

      This method updates entities provided in a stream and uses the specified batch size for the update operation. Batching the updates can greatly enhance performance by minimizing the number of database interactions, especially useful when dealing with large volumes of data.

      Parameters:
      entities - a stream of entities to update. Each entity must not be null, must already exist in the database, and must conform to the model constraints.
      batchSize - the size of the batches to use for the update operation. A larger batch size can improve performance but may also increase the load on the database.
      Throws:
      PersistenceException - if there is an error during the update operation, such as a violation of database constraints, connectivity issues, or if any entity in the stream is null.

    • updateAndFetch

      void updateAndFetch(@Nonnull Stream<E> entities, @Nonnull BatchCallback<E> callback)
      Updates a stream of entities in the database using the default batch size and returns a stream of the updated entities.

      This method updates entities provided in a stream, optimizing the update process by batching them with the default size. It fetches the updated entities immediately after updating to ensure that the returned entities reflect any database-generated values or defaults. This is particularly useful when database triggers or default values are involved.

      Parameters:
      entities - a stream of entities to update. Each entity must not be null, must already exist in the database, and must conform to the model constraints.
      callback - the callback to process the updated entities, reflecting their new state in the database, in batches.
      Throws:
      PersistenceException - if there is an error during the update or retrieval operation, such as a violation of database constraints, connectivity issues, or if any entity in the stream is null.

    • updateAndFetch

      void updateAndFetch(@Nonnull Stream<E> entities, int batchSize, @Nonnull BatchCallback<E> callback)
      Updates a stream of entities in the database, with the update process divided into batches of the specified size, and returns a stream of the updated entities.

      This method updates entities provided in a stream and uses the specified batch size for the update operation. Batching the updates can greatly enhance performance by minimizing the number of database interactions, especially useful when dealing with large volumes of data. It fetches the updated entities immediately after updating to ensure that the returned entities reflect any database-generated values or defaults.

      Parameters:
      entities - a stream of entities to update. Each entity must not be null, must already exist in the database, and must conform to the model constraints.
      batchSize - the size of the batches to use for the update operation. A larger batch size can improve performance but may also increase the load on the database.
      callback - the callback to process the updated entities, reflecting their new state in the database, in batches.
      Throws:
      PersistenceException - if there is an error during the update or retrieval operation, such as a violation of database constraints, connectivity issues, or if any entity in the stream is null.

    • upsert

      void upsert(@Nonnull Stream<E> entities)
      Inserts or updates a stream of entities in the database in batches.

      This method processes the provided stream of entities in batches, performing an "upsert" operation on each. For each entity, it will be inserted into the database if it does not already exist; if it does exist, it will be updated to reflect the current state of the entity. Batch processing optimizes the performance of the upsert operation for larger data sets by reducing database overhead.

      Parameters:
      entities - a stream of entities to be inserted or updated. Each entity in the stream must be non-null and contain valid data for insertion or update in the database.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • upsert

      void upsert(@Nonnull Stream<E> entities, int batchSize)
      Inserts or updates a stream of entities in the database in configurable batch sizes.

      This method processes the provided stream of entities in batches, performing an "upsert" operation on each. For each entity, it will be inserted if it does not already exist in the database, or updated if it does. The batch size can be configured to control the number of entities processed in each database operation, allowing for optimized performance and memory management based on system requirements.

      Parameters:
      entities - a stream of entities to be inserted or updated. Each entity in the stream must be non-null and contain valid data for insertion or update in the database.
      batchSize - the number of entities to process in each batch. A larger batch size may improve performance but increase memory usage, while a smaller batch size may reduce memory usage but increase the number of database operations.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • upsertAndFetchIds

      void upsertAndFetchIds(@Nonnull Stream<E> entities, @Nonnull BatchCallback<ID> callback)
      Inserts or updates a stream of entities in the database in batches and retrieves their IDs through a callback.

      This method processes the provided stream of entities in batches, performing an "upsert" operation on each entity. For each entity, it will be inserted if it does not already exist in the database or updated if it does. After each batch operation, the IDs of the upserted entities are passed to the provided callback, allowing for specializedized handling of the IDs as they are retrieved.

      Parameters:
      entities - a stream of entities to be inserted or updated. Each entity in the stream must be non-null and contain valid data for insertion or update in the database.
      callback - the callback to process the IDs of the upserted entities in batches.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • upsertAndFetch

      void upsertAndFetch(@Nonnull Stream<E> entities, @Nonnull BatchCallback<E> callback)
      Inserts or updates a stream of entities in the database in batches and retrieves the updated entities through a callback.

      This method processes the provided stream of entities in batches, performing an "upsert" operation on each entity. For each entity, it will be inserted if it does not already exist in the database or updated if it does. After each batch operation, the updated entities are passed to the provided callback, allowing for specializedized handling of the entities as they are retrieved. The entities returned reflect their current state in the database, including any changes such as generated primary keys, timestamps, or default values set by the database during the upsert process.

      Parameters:
      entities - a stream of entities to be inserted or updated. Each entity in the stream must be non-null and contain valid data for insertion or update in the database.
      callback - the callback to process the upserted entities, reflecting their new state in the database, in batches.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • upsertAndFetchIds

      void upsertAndFetchIds(@Nonnull Stream<E> entities, int batchSize, @Nonnull BatchCallback<ID> callback)
      Inserts or updates a stream of entities in the database in configurable batch sizes and retrieves their IDs through a callback.

      This method processes the provided stream of entities in batches, performing an "upsert" operation on each entity. For each entity, it will be inserted if it does not already exist in the database or updated if it does. The batch size parameter allows control over the number of entities processed in each batch, optimizing memory and performance based on system requirements. After each batch operation, the IDs of the upserted entities are passed to the provided callback, allowing for specializedized handling of the IDs as they are retrieved.

      Parameters:
      entities - a stream of entities to be inserted or updated. Each entity in the stream must be non-null and contain valid data for insertion or update in the database.
      batchSize - the number of entities to process in each batch. Adjusting the batch size can optimize performance and memory usage, with larger sizes potentially improving performance but using more memory.
      callback - the callback to process the IDs of the upserted entities in batches.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • upsertAndFetch

      void upsertAndFetch(@Nonnull Stream<E> entities, int batchSize, @Nonnull BatchCallback<E> callback)
      Inserts or updates a stream of entities in the database in configurable batch sizes and retrieves the updated entities through a callback.

      This method processes the provided stream of entities in batches, performing an "upsert" operation on each entity. For each entity, it will be inserted if it does not already exist in the database or updated if it does. The `batchSize` parameter allows control over the number of entities processed in each batch, optimizing performance and memory usage based on system requirements. After each batch operation, the updated entities are passed to the provided callback, allowing for specializedized handling of the entities as they are retrieved. The entities returned reflect their current state in the database, including any changes such as generated primary keys, timestamps, or default values applied during the upsert process.

      Parameters:
      entities - a stream of entities to be inserted or updated. Each entity in the stream must be non-null and contain valid data for insertion or update in the database.
      batchSize - the number of entities to process in each batch. Adjusting the batch size can optimize performance and memory usage, with larger sizes potentially improving performance but using more memory.
      callback - the callback to process the upserted entities, reflecting their new state in the database, in batches.
      Throws:
      PersistenceException - if the upsert operation fails due to database issues, such as connectivity problems, constraints violations, or invalid entity data.

    • delete

      void delete(@Nonnull Stream<E> entities)
      Deletes a stream of entities from the database in batches.

      This method processes the provided stream of entities in batches to optimize performance for larger data sets, reducing database overhead during deletion. For each entity in the stream, the method removes the corresponding record from the database, if it exists. Batch processing allows efficient handling of deletions, particularly for large collections of entities.

      Parameters:
      entities - a stream of entities to be deleted. Each entity in the stream must be non-null and represent a valid database record for deletion.
      Throws:
      PersistenceException - if the deletion operation fails due to database issues, such as connectivity problems or constraints violations.

    • delete

      void delete(@Nonnull Stream<E> entities, int batchSize)
      Deletes a stream of entities from the database in configurable batch sizes.

      This method processes the provided stream of entities in batches, with the size of each batch specified by the `batchSize` parameter. This allows for control over the number of entities deleted in each database operation, optimizing performance and memory usage based on system requirements. For each entity in the stream, the method removes the corresponding record from the database, if it exists.

      Parameters:
      entities - a stream of entities to be deleted. Each entity in the stream must be non-null and represent a valid database record for deletion.
      batchSize - the number of entities to process in each batch. Larger batch sizes may improve performance but require more memory, while smaller batch sizes may reduce memory usage but increase the number of database operations.
      Throws:
      PersistenceException - if the deletion operation fails due to database issues, such as connectivity problems or constraints violations.