Module storm.java
Package st.orm.repository

Interface EntityRepository<E extends 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
public interface EntityRepository<E extends 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<Integer> {};

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

 record User(@PK int id,
             String email,
             LocalDate birthDate,
             @Inline Address address
 ) implements Entity<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

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


 User user = ...;
 userRepository.remove(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.
    default <V extends Data>
    long
    countBy(Metamodel<E,V> field, Ref<V> value)
    Counts entities matching the specified field and referenced value.
    default <V> long
    countBy(Metamodel<E,V> field, V value)
    Counts entities matching the specified field and value.
    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 chunkSize)
    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 chunkSize)
    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.
    boolean
    exists()
    Checks if any entity of the type managed by this repository exists in the database.
    default <V extends Data>
    boolean
    existsBy(Metamodel<E,V> field, Ref<V> value)
    Checks if any entity matching the specified field and referenced value exists.
    default <V> boolean
    existsBy(Metamodel<E,V> field, V value)
    Checks if any entity matching the specified field and value exists.
    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.
    default <V> List<E>
    findAllBy(Metamodel<E,V> field, Iterable<? extends V> values)
    Retrieves entities matching a single field against multiple values.
    default <V extends Data>
    List<E>
    findAllBy(Metamodel<E,V> field, Ref<V> value)
    Retrieves entities matching a single field and a single referenced value.
    default <V> List<E>
    findAllBy(Metamodel<E,V> field, V value)
    Retrieves entities matching a single field and a single value.
    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.
    default <V extends Data>
    List<E>
    findAllByRef(Metamodel<E,V> field, Iterable<? extends Ref<V>> values)
    Retrieves entities matching a single field against multiple referenced values.
    List<Ref<E>>
    findAllRef()
    Returns a list of refs to all entities of the type supported by this repository.
    default <V> List<Ref<E>>
    findAllRefBy(Metamodel<E,V> field, Iterable<? extends V> values)
    Retrieves refs to entities matching a single field against multiple values.
    default <V extends Data>
    List<Ref<E>>
    findAllRefBy(Metamodel<E,V> field, Ref<V> value)
    Retrieves refs to entities matching a single field and a single referenced value.
    default <V> List<Ref<E>>
    findAllRefBy(Metamodel<E,V> field, V value)
    Retrieves refs to entities matching a single field and a single value.
    default <V extends Data>
    List<Ref<E>>
    findAllRefByRef(Metamodel<E,V> field, Iterable<? extends Ref<V>> values)
    Retrieves refs to entities matching a single field against multiple referenced values.
    <V> Optional<E>
    findBy(Metamodel.Key<E,V> key, V value)
    Retrieves an entity by the value of a unique key field.
    default <V extends Data>
    Optional<E>
    findBy(Metamodel<E,V> field, Ref<V> value)
    Retrieves an entity based on a single field and its referenced value.
    default <V> Optional<E>
    findBy(Metamodel<E,V> field, V value)
    Retrieves an entity based on a single field and its value.
    Optional<E>
    findById(ID id)
    Retrieves an entity based on its primary key.
    <V extends Data>
    Optional<E>
    findByRef(Metamodel.Key<E,V> key, Ref<V> value)
    Retrieves an entity by the ref value of a unique key field that references another entity.
    Optional<E>
    findByRef(Ref<E> ref)
    Retrieves an entity based on its primary key, expressed by a ref.
    default <V extends Data>
    Optional<Ref<E>>
    findRefBy(Metamodel<E,V> field, Ref<V> value)
    Retrieves a ref to an entity based on a single field and its referenced value.
    default <V> Optional<Ref<E>>
    findRefBy(Metamodel<E,V> field, V value)
    Retrieves a ref to an entity based on a single field and its value.
    <V> E
    getBy(Metamodel.Key<E,V> key, V value)
    Retrieves an entity by the value of a unique key field.
    default <V extends Data>
    E
    getBy(Metamodel<E,V> field, Ref<V> value)
    Retrieves exactly one entity based on a single field and its referenced value.
    default <V> E
    getBy(Metamodel<E,V> field, V value)
    Retrieves exactly one entity based on a single field and its value.
    E
    getById(ID id)
    Retrieves an entity based on its primary key.
    <V extends Data>
    E
    getByRef(Metamodel.Key<E,V> key, Ref<V> value)
    Retrieves an entity by the ref value of a unique key field that references another entity.
    E
    getByRef(Ref<E> ref)
    Retrieves an entity based on its primary key, expressed by a ref.
    default <V extends Data>
    Ref<E>
    getRefBy(Metamodel<E,V> field, Ref<V> value)
    Retrieves a ref to exactly one entity based on a single field and its referenced value.
    default <V> Ref<E>
    getRefBy(Metamodel<E,V> field, V value)
    Retrieves a ref to exactly one entity based on a single field and its value.
    void
    insert(E entity)
    Inserts an entity into the database.
    void
    insert(E entity, boolean ignoreAutoGenerate)
    Inserts an entity into the database.
    void
    insert(Iterable<E> entities)
    Inserts a collection of entities into the database in batches.
    void
    insert(Iterable<E> entities, boolean ignoreAutoGenerate)
    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, boolean ignoreAutoGenerate)
    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.
    void
    insert(Stream<E> entities, int batchSize, boolean ignoreAutoGenerate)
    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.
    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.
    Model<E,ID>
    model()
    Returns the entity model associated with this repository.
    Page<E>
    page(int pageNumber, int pageSize)
    Returns a page of entities using offset-based pagination.
    Page<E>
    page(Pageable pageable)
    Returns a page of entities using offset-based pagination.
    Page<Ref<E>>
    pageRef(int pageNumber, int pageSize)
    Returns a page of entity refs using offset-based pagination.
    Page<Ref<E>>
    pageRef(Pageable pageable)
    Returns a page of entity refs using offset-based pagination.
    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.
    void
    remove(E entity)
    Removes an entity from the database.
    void
    remove(Iterable<E> entities)
    Removes a collection of entities from the database in batches.
    void
    remove(Stream<E> entities)
    Removes a stream of entities from the database in batches.
    void
    remove(Stream<E> entities, int batchSize)
    Removes a stream of entities from the database in configurable batch sizes.
    void
    removeAll()
    Removes all entities from the database.
    default <V> int
    removeAllBy(Metamodel<E,V> field, Iterable<? extends V> values)
    Removes entities matching the specified field against multiple values.
    default <V extends Data>
    int
    removeAllBy(Metamodel<E,V> field, Ref<V> value)
    Removes entities matching the specified field and referenced value.
    default <V> int
    removeAllBy(Metamodel<E,V> field, V value)
    Removes entities matching the specified field and value.
    default <V extends Data>
    int
    removeAllByRef(Metamodel<E,V> field, Iterable<? extends Ref<V>> values)
    Removes entities matching the specified field against multiple referenced values.
    void
    removeById(ID id)
    Removes an entity from the database based on its primary key.
    void
    removeByRef(Iterable<Ref<E>> refs)
    Removes a collection of entities from the database in batches.
    void
    removeByRef(Stream<Ref<E>> refs)
    Removes a stream of entities from the database in batches.
    void
    removeByRef(Stream<Ref<E>> refs, int batchSize)
    Removes a stream of entities from the database in configurable batch sizes.
    void
    removeByRef(Ref<E> ref)
    Removes an entity from the database by its reference.
    default Window<E>
    scroll(Scrollable<E> scrollable)
    Executes a scroll request from a Scrollable token, typically obtained from Window.next() or Window.previous().
    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.
    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 Data>
    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
    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.
    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.

    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 an attached 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.

      Unlike Ref.unload(), which returns a detached ref, this method returns an attached ref that can re-fetch the entity from the database.

      Parameters:
      entity - the entity to unload into a lightweight ref.
      Returns:
      an attached 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 Data> 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.

    • exists

      boolean exists()
      Checks if any entity of the type managed by this repository exists in the database.
      Returns:
      true if at least one entity exists, false otherwise.
      Throws:
      PersistenceException - if there is an underlying database issue during the count operation.

    • 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.

    • insert

      void insert(@Nonnull E entity, boolean ignoreAutoGenerate)
      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.
      ignoreAutoGenerate - true to ignore the auto-generate flag on the primary key and explicitly insert the provided primary key value. Use this flag only when intentionally providing the primary key value (e.g., migrations, data exports).
      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.

    • remove

      void remove(@Nonnull E entity)
      Removes an entity from the database.

      This method removes an existing entity from the database. The entity must exist in the database; if it does not, a PersistenceException is thrown. Unlike removeById(ID) and removeByRef(st.orm.Ref<E>), this method is strict rather than idempotent, because possessing the full entity implies the caller expects it to exist.

      Parameters:
      entity - the entity to remove. The entity must exist in the database and should be correctly identified by its primary key.
      Throws:
      PersistenceException - if the removal 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.

    • removeById

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

      This method ensures the entity with the given primary key is removed from the database. If the entity does not exist, the operation completes successfully without error (idempotent behavior).

      Parameters:
      id - the primary key of the entity to remove.
      Throws:
      PersistenceException - if the removal operation fails due to violations of database constraints, connectivity issues, or if the id parameter is null.

    • removeByRef

      void removeByRef(@Nonnull Ref<E> ref)
      Removes an entity from the database by its reference.

      This method ensures the entity identified by the given reference is removed from the database. If the entity does not exist, the operation completes successfully without error (idempotent behavior).

      Parameters:
      ref - the reference to the entity to remove.
      Throws:
      PersistenceException - if the removal operation fails due to violations of database constraints, connectivity issues, or if the ref parameter is null.

    • removeAll

      void removeAll()
      Removes all entities from the database.

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

      Throws:
      PersistenceException - if the bulk removal 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 removal 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.

    • findBy

      <V> Optional<E> findBy(@Nonnull Metamodel.Key<E,V> key, @Nonnull V value)
      Retrieves an entity by the value of a unique key field.
      Type Parameters:
      V - the type of the key field.
      Parameters:
      key - the metamodel key identifying a unique column.
      value - the value to match.
      Returns:
      the entity matching the given key value, or empty if none exists.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.9

    • getBy

      <V> E getBy(@Nonnull Metamodel.Key<E,V> key, @Nonnull V value)
      Retrieves an entity by the value of a unique key field.
      Type Parameters:
      V - the type of the key field.
      Parameters:
      key - the metamodel key identifying a unique column.
      value - the value to match.
      Returns:
      the entity matching the given key value.
      Throws:
      NoResultException - if no entity is found matching the given key value.
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.9

    • findByRef

      <V extends Data> Optional<E> findByRef(@Nonnull Metamodel.Key<E,V> key, @Nonnull Ref<V> value)
      Retrieves an entity by the ref value of a unique key field that references another entity.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      key - the metamodel key identifying a unique foreign key column.
      value - the ref value to match.
      Returns:
      the entity matching the given ref value, or empty if none exists.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.9

    • getByRef

      <V extends Data> E getByRef(@Nonnull Metamodel.Key<E,V> key, @Nonnull Ref<V> value)
      Retrieves an entity by the ref value of a unique key field that references another entity.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      key - the metamodel key identifying a unique foreign key column.
      value - the ref value to match.
      Returns:
      the entity matching the given ref value.
      Throws:
      NoResultException - if no entity is found matching the given ref value.
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.9

    • findBy

      default <V> Optional<E> findBy(@Nonnull Metamodel<E,V> field, @Nonnull V value)
      Retrieves an entity based on a single field and its value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      value - the value to match against.
      Returns:
      the entity matching the given field value, or empty if none exists.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • findBy

      default <V extends Data> Optional<E> findBy(@Nonnull Metamodel<E,V> field, @Nonnull Ref<V> value)
      Retrieves an entity based on a single field and its referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      value - the referenced value to match against.
      Returns:
      the entity matching the given ref value, or empty if none exists.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • findAllBy

      default <V> List<E> findAllBy(@Nonnull Metamodel<E,V> field, @Nonnull V value)
      Retrieves entities matching a single field and a single value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      value - the value to match against.
      Returns:
      a list of matching entities, or an empty list if none found.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • findAllBy

      default <V extends Data> List<E> findAllBy(@Nonnull Metamodel<E,V> field, @Nonnull Ref<V> value)
      Retrieves entities matching a single field and a single referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      value - the referenced value to match against.
      Returns:
      a list of matching entities, or an empty list if none found.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • findAllBy

      default <V> List<E> findAllBy(@Nonnull Metamodel<E,V> field, @Nonnull Iterable<? extends V> values)
      Retrieves entities matching a single field against multiple values.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      values - the values to match against.
      Returns:
      a list of matching entities, or an empty list if none found.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • findAllByRef

      default <V extends Data> List<E> findAllByRef(@Nonnull Metamodel<E,V> field, @Nonnull Iterable<? extends Ref<V>> values)
      Retrieves entities matching a single field against multiple referenced values.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      values - the referenced values to match against.
      Returns:
      a list of matching entities, or an empty list if none found.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • getBy

      default <V> E getBy(@Nonnull Metamodel<E,V> field, @Nonnull V value)
      Retrieves exactly one entity based on a single field and its value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      value - the value to match against.
      Returns:
      the matching entity.
      Throws:
      NoResultException - if there is no result.
      NonUniqueResultException - if more than one result.
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • getBy

      default <V extends Data> E getBy(@Nonnull Metamodel<E,V> field, @Nonnull Ref<V> value)
      Retrieves exactly one entity based on a single field and its referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      value - the referenced value to match against.
      Returns:
      the matching entity.
      Throws:
      NoResultException - if there is no result.
      NonUniqueResultException - if more than one result.
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • findRefBy

      default <V> Optional<Ref<E>> findRefBy(@Nonnull Metamodel<E,V> field, @Nonnull V value)
      Retrieves a ref to an entity based on a single field and its value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      value - the value to match against.
      Returns:
      a ref to the matching entity, or empty if none exists.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • findRefBy

      default <V extends Data> Optional<Ref<E>> findRefBy(@Nonnull Metamodel<E,V> field, @Nonnull Ref<V> value)
      Retrieves a ref to an entity based on a single field and its referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      value - the referenced value to match against.
      Returns:
      a ref to the matching entity, or empty if none exists.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • findAllRefBy

      default <V> List<Ref<E>> findAllRefBy(@Nonnull Metamodel<E,V> field, @Nonnull V value)
      Retrieves refs to entities matching a single field and a single value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      value - the value to match against.
      Returns:
      a list of refs to matching entities, or an empty list if none found.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • findAllRefBy

      default <V extends Data> List<Ref<E>> findAllRefBy(@Nonnull Metamodel<E,V> field, @Nonnull Ref<V> value)
      Retrieves refs to entities matching a single field and a single referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      value - the referenced value to match against.
      Returns:
      a list of refs to matching entities, or an empty list if none found.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • findAllRefBy

      default <V> List<Ref<E>> findAllRefBy(@Nonnull Metamodel<E,V> field, @Nonnull Iterable<? extends V> values)
      Retrieves refs to entities matching a single field against multiple values.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      values - the values to match against.
      Returns:
      a list of refs to matching entities, or an empty list if none found.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • findAllRefByRef

      default <V extends Data> List<Ref<E>> findAllRefByRef(@Nonnull Metamodel<E,V> field, @Nonnull Iterable<? extends Ref<V>> values)
      Retrieves refs to entities matching a single field against multiple referenced values.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      values - the referenced values to match against.
      Returns:
      a list of refs to matching entities, or an empty list if none found.
      Throws:
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • getRefBy

      default <V> Ref<E> getRefBy(@Nonnull Metamodel<E,V> field, @Nonnull V value)
      Retrieves a ref to exactly one entity based on a single field and its value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      value - the value to match against.
      Returns:
      a ref to the matching entity.
      Throws:
      NoResultException - if there is no result.
      NonUniqueResultException - if more than one result.
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • getRefBy

      default <V extends Data> Ref<E> getRefBy(@Nonnull Metamodel<E,V> field, @Nonnull Ref<V> value)
      Retrieves a ref to exactly one entity based on a single field and its referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      value - the referenced value to match against.
      Returns:
      a ref to the matching entity.
      Throws:
      NoResultException - if there is no result.
      NonUniqueResultException - if more than one result.
      PersistenceException - if the retrieval operation fails due to underlying database issues.
      Since:
      1.11

    • countBy

      default <V> long countBy(@Nonnull Metamodel<E,V> field, @Nonnull V value)
      Counts entities matching the specified field and value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      value - the value to match against.
      Returns:
      the count of matching entities.
      Throws:
      PersistenceException - if the count operation fails due to underlying database issues.
      Since:
      1.11

    • countBy

      default <V extends Data> long countBy(@Nonnull Metamodel<E,V> field, @Nonnull Ref<V> value)
      Counts entities matching the specified field and referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      value - the referenced value to match against.
      Returns:
      the count of matching entities.
      Throws:
      PersistenceException - if the count operation fails due to underlying database issues.
      Since:
      1.11

    • existsBy

      default <V> boolean existsBy(@Nonnull Metamodel<E,V> field, @Nonnull V value)
      Checks if any entity matching the specified field and value exists.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      value - the value to match against.
      Returns:
      true if any matching entities exist, false otherwise.
      Throws:
      PersistenceException - if the count operation fails due to underlying database issues.
      Since:
      1.11

    • existsBy

      default <V extends Data> boolean existsBy(@Nonnull Metamodel<E,V> field, @Nonnull Ref<V> value)
      Checks if any entity matching the specified field and referenced value exists.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      value - the referenced value to match against.
      Returns:
      true if any matching entities exist, false otherwise.
      Throws:
      PersistenceException - if the count operation fails due to underlying database issues.
      Since:
      1.11

    • removeAllBy

      default <V> int removeAllBy(@Nonnull Metamodel<E,V> field, @Nonnull V value)
      Removes entities matching the specified field and value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      value - the value to match against.
      Returns:
      the number of entities removed.
      Throws:
      PersistenceException - if the removal operation fails due to underlying database issues.
      Since:
      1.11

    • removeAllBy

      default <V extends Data> int removeAllBy(@Nonnull Metamodel<E,V> field, @Nonnull Ref<V> value)
      Removes entities matching the specified field and referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      value - the referenced value to match against.
      Returns:
      the number of entities removed.
      Throws:
      PersistenceException - if the removal operation fails due to underlying database issues.
      Since:
      1.11

    • removeAllBy

      default <V> int removeAllBy(@Nonnull Metamodel<E,V> field, @Nonnull Iterable<? extends V> values)
      Removes entities matching the specified field against multiple values.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the entity field.
      values - the values to match against.
      Returns:
      the number of entities removed.
      Throws:
      PersistenceException - if the removal operation fails due to underlying database issues.
      Since:
      1.11

    • removeAllByRef

      default <V extends Data> int removeAllByRef(@Nonnull Metamodel<E,V> field, @Nonnull Iterable<? extends Ref<V>> values)
      Removes entities matching the specified field against multiple referenced values.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the entity field.
      values - the referenced values to match against.
      Returns:
      the number of entities removed.
      Throws:
      PersistenceException - if the removal operation fails due to underlying database issues.
      Since:
      1.11

    • page

      Page<E> page(int pageNumber, int pageSize)
      Returns a page of entities using offset-based pagination.

      This method executes two queries: a SELECT COUNT(*) to determine the total number of entities, and a query with OFFSET and LIMIT to fetch the content for the requested page.

      Page numbers are zero-based: pass 0 for the first page.

      Parameters:
      pageNumber - the zero-based page index.
      pageSize - the maximum number of entities per page.
      Returns:
      a page containing the results and pagination metadata.
      Since:
      1.10

    • page

      Page<E> page(@Nonnull Pageable pageable)
      Returns a page of entities using offset-based pagination.

      This method executes two queries: a SELECT COUNT(*) to determine the total number of entities, and a query with OFFSET and LIMIT to fetch the content for the requested page.

      Use Pageable.ofSize(int) for the first page, then navigate with Page.nextPageable() or Page.previousPageable().

      Parameters:
      pageable - the pagination request specifying page number and page size.
      Returns:
      a page containing the results and pagination metadata.
      Since:
      1.10

    • pageRef

      Page<Ref<E>> pageRef(int pageNumber, int pageSize)
      Returns a page of entity refs using offset-based pagination.

      Page numbers are zero-based: pass 0 for the first page.

      Parameters:
      pageNumber - the zero-based page index.
      pageSize - the maximum number of refs per page.
      Returns:
      a page containing the ref results and pagination metadata.
      Since:
      1.10

    • pageRef

      Page<Ref<E>> pageRef(@Nonnull Pageable pageable)
      Returns a page of entity refs using offset-based pagination.

      This method executes two queries: a SELECT COUNT(*) to determine the total number of entities, and a query with OFFSET and LIMIT to fetch the refs for the requested page.

      Parameters:
      pageable - the pagination request specifying page number and page size.
      Returns:
      a page containing the ref results and pagination metadata.
      Since:
      1.10

    • scroll

      default Window<E> scroll(@Nonnull Scrollable<E> scrollable)
      Executes a scroll request from a Scrollable token, typically obtained from Window.next() or Window.previous().
      Parameters:
      scrollable - the scroll request containing cursor state, key, sort, size, and direction.
      Returns:
      a window containing the results and navigation tokens.
      Since:
      1.11

    • 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.

      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.

    • findAllRef

      List<Ref<E>> findAllRef()
      Returns a list of refs to all entities of the type supported by this repository. Each element in the list represents a lightweight reference to an entity in the database, containing only the primary key.

      This method is useful when you need to retrieve all entity identifiers without loading the full entity data. The complete entity can be fetched on demand by calling Ref.fetch() on any of the returned refs.

      Note: While this method is more memory-efficient than findAll() since it only loads primary keys, loading all refs into memory at once can still be memory-intensive for very large tables.

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

    • 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: 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: 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.

    • insert

      void insert(@Nonnull Iterable<E> entities, boolean ignoreAutoGenerate)
      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.
      ignoreAutoGenerate - true to ignore the auto-generate flag on the primary key and explicitly insert the provided primary key value. Use this flag only when intentionally providing the primary key value (e.g., migrations, data exports).
      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.

    • remove

      void remove(@Nonnull Iterable<E> entities)
      Removes 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 removals, particularly for large data sets.

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

    • removeByRef

      void removeByRef(@Nonnull Iterable<Ref<E>> refs)
      Removes 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 removals, particularly for large data sets.

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

    • 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 chunkSize)
      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.
      chunkSize - 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 chunkSize)
      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.
      chunkSize - 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, boolean ignoreAutoGenerate)
      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.
      ignoreAutoGenerate - true to ignore the auto-generate flag on the primary key and explicitly insert the provided primary key value. Use this flag only when intentionally providing the primary key value (e.g., migrations, data exports).
      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.

    • insert

      void insert(@Nonnull Stream<E> entities, int batchSize, boolean ignoreAutoGenerate)
      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.
      ignoreAutoGenerate - true to ignore the auto-generate flag on the primary key and explicitly insert the provided primary key value. Use this flag only when intentionally providing the primary key value (e.g., migrations, data exports).
      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.

    • 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.

    • 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.

    • remove

      void remove(@Nonnull Stream<E> entities)
      Removes a stream of entities from the database in batches.
      Parameters:
      entities - a stream of entities to be removed.
      Throws:
      PersistenceException - if the removal operation fails.

    • remove

      void remove(@Nonnull Stream<E> entities, int batchSize)
      Removes a stream of entities from the database in configurable batch sizes.
      Parameters:
      entities - a stream of entities to be removed.
      batchSize - the number of entities to process in each batch.
      Throws:
      PersistenceException - if the removal operation fails.

    • removeByRef

      void removeByRef(@Nonnull Stream<Ref<E>> refs)
      Removes a stream of entities from the database in batches.
      Parameters:
      refs - a stream of entities to be removed.
      Throws:
      PersistenceException - if the removal operation fails.

    • removeByRef

      void removeByRef(@Nonnull Stream<Ref<E>> refs, int batchSize)
      Removes a stream of entities from the database in configurable batch sizes.
      Parameters:
      refs - a stream of entities to be removed.
      batchSize - the number of entities to process in each batch.
      Throws:
      PersistenceException - if the removal operation fails.