Module storm.java
Package st.orm.repository

Interface ProjectionRepository<P extends Projection<ID>,ID>

Type Parameters:
P - the type of projection managed by this repository.
ID - the type of the primary key of the projection, or Void if the projection has no primary key.
All Superinterfaces:
Repository
public interface ProjectionRepository<P extends Projection<ID>,ID> extends Repository
ProjectionRepository relies on preview features of the Java platform:
  • ProjectionRepository refers to one or more preview APIs: StringTemplate.
Programs can only use ProjectionRepository 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 read operations for projections.

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

Since:
1.1
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    count()
    Returns the number of projections in the database of the projection type supported by this repository.
    default <V extends Data>
    long
    countBy(Metamodel<P,V> field, Ref<V> value)
    Counts projections matching the specified field and referenced value.
    default <V> long
    countBy(Metamodel<P,V> field, V value)
    Counts projections matching the specified field and value.
    long
    countById(Stream<ID> ids)
    Counts the number of projections identified by the provided stream of IDs using the default batch size.
    long
    countById(Stream<ID> ids, int chunkSize)
    Counts the number of projections identified by the provided stream of IDs, with the counting process divided into batches of the specified size.
    long
    countByRef(Stream<Ref<P>> refs)
    Counts the number of projections identified by the provided stream of refs using the default batch size.
    long
    countByRef(Stream<Ref<P>> refs, int chunkSize)
    Counts the number of projections identified by the provided stream of refs, with the counting process divided into batches of the specified size.
    boolean
    exists()
    Checks if any projection of the type managed by this repository exists in the database.
    default <V extends Data>
    boolean
    existsBy(Metamodel<P,V> field, Ref<V> value)
    Checks if any projection matching the specified field and referenced value exists.
    default <V> boolean
    existsBy(Metamodel<P,V> field, V value)
    Checks if any projection matching the specified field and value exists.
    boolean
    existsById(ID id)
    Checks if a projection with the specified primary key exists in the database.
    boolean
    existsByRef(Ref<P> ref)
    Checks if a projection with the specified primary key exists in the database.
    List<P>
    findAll()
    Returns a list of all projections of the type supported by this repository.
    default <V> List<P>
    findAllBy(Metamodel<P,V> field, Iterable<? extends V> values)
    Retrieves projections matching a single field against multiple values.
    default <V extends Data>
    List<P>
    findAllBy(Metamodel<P,V> field, Ref<V> value)
    Retrieves projections matching a single field and a single referenced value.
    default <V> List<P>
    findAllBy(Metamodel<P,V> field, V value)
    Retrieves projections matching a single field and a single value.
    List<P>
    findAllById(Iterable<ID> ids)
    Retrieves a list of projections based on their primary keys.
    List<P>
    findAllByRef(Iterable<Ref<P>> refs)
    Retrieves a list of projections based on their primary keys.
    default <V extends Data>
    List<P>
    findAllByRef(Metamodel<P,V> field, Iterable<? extends Ref<V>> values)
    Retrieves projections matching a single field against multiple referenced values.
    List<Ref<P>>
    findAllRef()
    Returns a list of refs to all projections of the type supported by this repository.
    default <V> List<Ref<P>>
    findAllRefBy(Metamodel<P,V> field, Iterable<? extends V> values)
    Retrieves refs to projections matching a single field against multiple values.
    default <V extends Data>
    List<Ref<P>>
    findAllRefBy(Metamodel<P,V> field, Ref<V> value)
    Retrieves refs to projections matching a single field and a single referenced value.
    default <V> List<Ref<P>>
    findAllRefBy(Metamodel<P,V> field, V value)
    Retrieves refs to projections matching a single field and a single value.
    default <V extends Data>
    List<Ref<P>>
    findAllRefByRef(Metamodel<P,V> field, Iterable<? extends Ref<V>> values)
    Retrieves refs to projections matching a single field against multiple referenced values.
    <V> Optional<P>
    findBy(Metamodel.Key<P,V> key, V value)
    Retrieves a projection by the value of a unique key field.
    default <V extends Data>
    Optional<P>
    findBy(Metamodel<P,V> field, Ref<V> value)
    Retrieves a projection based on a single field and its referenced value.
    default <V> Optional<P>
    findBy(Metamodel<P,V> field, V value)
    Retrieves a projection based on a single field and its value.
    Optional<P>
    findById(ID id)
    Retrieves a projection based on its primary key.
    <V extends Data>
    Optional<P>
    findByRef(Metamodel.Key<P,V> key, Ref<V> value)
    Retrieves a projection by the ref value of a unique key field that references another entity.
    Optional<P>
    findByRef(Ref<P> ref)
    Retrieves a projection based on its primary key.
    default <V extends Data>
    Optional<Ref<P>>
    findRefBy(Metamodel<P,V> field, Ref<V> value)
    Retrieves a ref to a projection based on a single field and its referenced value.
    default <V> Optional<Ref<P>>
    findRefBy(Metamodel<P,V> field, V value)
    Retrieves a ref to a projection based on a single field and its value.
    <V> P
    getBy(Metamodel.Key<P,V> key, V value)
    Retrieves a projection by the value of a unique key field.
    default <V extends Data>
    P
    getBy(Metamodel<P,V> field, Ref<V> value)
    Retrieves exactly one projection based on a single field and its referenced value.
    default <V> P
    getBy(Metamodel<P,V> field, V value)
    Retrieves exactly one projection based on a single field and its value.
    P
    getById(ID id)
    Retrieves a projection based on its primary key.
    <V extends Data>
    P
    getByRef(Metamodel.Key<P,V> key, Ref<V> value)
    Retrieves a projection by the ref value of a unique key field that references another entity.
    P
    getByRef(Ref<P> ref)
    Retrieves a projection based on its primary key.
    default <V extends Data>
    Ref<P>
    getRefBy(Metamodel<P,V> field, Ref<V> value)
    Retrieves a ref to exactly one projection based on a single field and its referenced value.
    default <V> Ref<P>
    getRefBy(Metamodel<P,V> field, V value)
    Retrieves a ref to exactly one projection based on a single field and its value.
    Model<P,ID>
    model()
    Returns the projection model associated with this repository.
    Page<P>
    page(int pageNumber, int pageSize)
    Returns a page of projections using offset-based pagination.
    Page<P>
    page(Pageable pageable)
    Returns a page of projections using offset-based pagination.
    Page<Ref<P>>
    pageRef(int pageNumber, int pageSize)
    Returns a page of projection refs using offset-based pagination.
    Page<Ref<P>>
    pageRef(Pageable pageable)
    Returns a page of projection refs using offset-based pagination.
    Ref<P>
    ref(ID id)
    Creates a new ref projection instance with the specified primary key.
    Ref<P>
    ref(P projection, ID id)
    Creates a new ref projection instance with the specified projection.
    default Window<P>
    scroll(Scrollable<P> scrollable)
    Executes a scroll request from a Scrollable token, typically obtained from Window.next() or Window.previous().
    QueryBuilder<P,P,ID>
    select()
    Creates a new query builder for the projection type managed by this repository.
    <R> QueryBuilder<P,R,ID>
    select(Class<R> selectType)
    Creates a new query builder for the custom selectType.
    <R> QueryBuilder<P,R,ID>
    select(Class<R> selectType, StringTemplatePREVIEW template)
    Creates a new query builder for the custom selectType and custom template for the select clause.
    Stream<P>
    selectById(Stream<ID> ids)
    Retrieves a stream of projections based on their primary keys.
    Stream<P>
    selectById(Stream<ID> ids, int chunkSize)
    Retrieves a stream of projections based on their primary keys.
    Stream<P>
    selectByRef(Stream<Ref<P>> refs)
    Retrieves a stream of projections based on their primary keys.
    Stream<P>
    selectByRef(Stream<Ref<P>> refs, int chunkSize)
    Retrieves a stream of projections based on their primary keys.
    QueryBuilder<P,Long,ID>
    selectCount()
    Creates a new query builder for the projection type managed by this repository.
    QueryBuilder<P,Ref<P>,ID>
    selectRef()
    Creates a new query builder for selecting refs to projections of the type managed by this repository.
    <R extends Data>
    QueryBuilder<P,Ref<R>,ID>
    selectRef(Class<R> refType)
    Creates a new query builder for selecting refs to projections of the type managed by this repository.

    Methods inherited from interface st.orm.repository.Repository

    orm

  • Method Details

    • model

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

    • ref

      Ref<P> ref(@Nonnull ID id)
      Creates a new ref projection instance with the specified primary key.
      Parameters:
      id - the primary key of the projection.
      Returns:
      a ref projection instance.

    • ref

      Ref<P> ref(@Nonnull P projection, @Nonnull ID id)
      Creates a new ref projection instance with the specified projection.
      Parameters:
      projection - the projection.
      Returns:
      a ref projection instance.

    • select

      QueryBuilder<P,P,ID> select()
      Creates a new query builder for the projection type managed by this repository.
      Returns:
      a new query builder for the projection type.

    • selectCount

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

    • select

      <R> QueryBuilder<P,R,ID> select(@Nonnull Class<R> selectType)
      Creates a new query builder for the custom 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 custom selectType.

    • selectRef

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

      This method is typically used when you only need the primary keys of the projection 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 projections.
      Since:
      1.3

    • select

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

    • selectRef

      <R extends Data> QueryBuilder<P,Ref<R>,ID> selectRef(@Nonnull Class<R> refType)
      Creates a new query builder for selecting refs to projections of the type managed by this repository.

      This method is typically used when you only need the primary keys of the projections 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 projection, 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 projections.
      Since:
      1.3

    • count

      long count()
      Returns the number of projections in the database of the projection type supported by this repository.
      Returns:
      the total number of projections 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 projection of the type managed by this repository exists in the database.
      Returns:
      true if at least one projection exists, false otherwise.
      Throws:
      PersistenceException - if there is an underlying database issue during the count operation.

    • existsById

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

      This method determines the presence of a projection by checking if the count of projections 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 projection to check for existence.
      Returns:
      true if a projection 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<P> ref)
      Checks if a projection with the specified primary key exists in the database.

      This method determines the presence of a projection by checking if the count of projections 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 projection to check for existence.
      Returns:
      true if a projection with the specified primary key exists, false otherwise.
      Throws:
      PersistenceException - if there is an underlying database issue during the count operation.

    • findById

      Optional<P> findById(@Nonnull ID id)
      Retrieves a projection based on its primary key.

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

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

    • findByRef

      Optional<P> findByRef(@Nonnull Ref<P> ref)
      Retrieves a projection based on its primary key.

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

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

    • getById

      P getById(@Nonnull ID id)
      Retrieves a projection based on its primary key.

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

      Parameters:
      id - the primary key of the projection to retrieve.
      Returns:
      the projection associated with the provided primary key. The returned projection encapsulates all relevant data as mapped by the projection model.
      Throws:
      NoResultException - if no projection 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

      P getByRef(@Nonnull Ref<P> ref)
      Retrieves a projection based on its primary key.

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

      Parameters:
      ref - the ref to match.
      Returns:
      the projection associated with the provided primary key. The returned projection encapsulates all relevant data as mapped by the projection model.
      Throws:
      NoResultException - if no projection 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<P> findBy(@Nonnull Metamodel.Key<P,V> key, @Nonnull V value)
      Retrieves a projection 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 projection 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> P getBy(@Nonnull Metamodel.Key<P,V> key, @Nonnull V value)
      Retrieves a projection 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 projection matching the given key value.
      Throws:
      NoResultException - if no projection 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<P> findByRef(@Nonnull Metamodel.Key<P,V> key, @Nonnull Ref<V> value)
      Retrieves a projection 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 projection 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> P getByRef(@Nonnull Metamodel.Key<P,V> key, @Nonnull Ref<V> value)
      Retrieves a projection 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 projection matching the given ref value.
      Throws:
      NoResultException - if no projection 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<P> findBy(@Nonnull Metamodel<P,V> field, @Nonnull V value)
      Retrieves a projection based on a single field and its value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the projection field.
      value - the value to match against.
      Returns:
      the projection 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<P> findBy(@Nonnull Metamodel<P,V> field, @Nonnull Ref<V> value)
      Retrieves a projection based on a single field and its referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the projection field.
      value - the referenced value to match against.
      Returns:
      the projection 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<P> findAllBy(@Nonnull Metamodel<P,V> field, @Nonnull V value)
      Retrieves projections matching a single field and a single value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the projection field.
      value - the value to match against.
      Returns:
      a list of matching projections, 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<P> findAllBy(@Nonnull Metamodel<P,V> field, @Nonnull Ref<V> value)
      Retrieves projections matching a single field and a single referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the projection field.
      value - the referenced value to match against.
      Returns:
      a list of matching projections, 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<P> findAllBy(@Nonnull Metamodel<P,V> field, @Nonnull Iterable<? extends V> values)
      Retrieves projections matching a single field against multiple values.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the projection field.
      values - the values to match against.
      Returns:
      a list of matching projections, 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<P> findAllByRef(@Nonnull Metamodel<P,V> field, @Nonnull Iterable<? extends Ref<V>> values)
      Retrieves projections matching a single field against multiple referenced values.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the projection field.
      values - the referenced values to match against.
      Returns:
      a list of matching projections, 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> P getBy(@Nonnull Metamodel<P,V> field, @Nonnull V value)
      Retrieves exactly one projection based on a single field and its value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the projection field.
      value - the value to match against.
      Returns:
      the matching projection.
      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> P getBy(@Nonnull Metamodel<P,V> field, @Nonnull Ref<V> value)
      Retrieves exactly one projection based on a single field and its referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the projection field.
      value - the referenced value to match against.
      Returns:
      the matching projection.
      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<P>> findRefBy(@Nonnull Metamodel<P,V> field, @Nonnull V value)
      Retrieves a ref to a projection based on a single field and its value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the projection field.
      value - the value to match against.
      Returns:
      a ref to the matching projection, 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<P>> findRefBy(@Nonnull Metamodel<P,V> field, @Nonnull Ref<V> value)
      Retrieves a ref to a projection based on a single field and its referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the projection field.
      value - the referenced value to match against.
      Returns:
      a ref to the matching projection, 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<P>> findAllRefBy(@Nonnull Metamodel<P,V> field, @Nonnull V value)
      Retrieves refs to projections matching a single field and a single value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the projection field.
      value - the value to match against.
      Returns:
      a list of refs to matching projections, 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<P>> findAllRefBy(@Nonnull Metamodel<P,V> field, @Nonnull Ref<V> value)
      Retrieves refs to projections matching a single field and a single referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the projection field.
      value - the referenced value to match against.
      Returns:
      a list of refs to matching projections, 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<P>> findAllRefBy(@Nonnull Metamodel<P,V> field, @Nonnull Iterable<? extends V> values)
      Retrieves refs to projections matching a single field against multiple values.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the projection field.
      values - the values to match against.
      Returns:
      a list of refs to matching projections, 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<P>> findAllRefByRef(@Nonnull Metamodel<P,V> field, @Nonnull Iterable<? extends Ref<V>> values)
      Retrieves refs to projections matching a single field against multiple referenced values.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the projection field.
      values - the referenced values to match against.
      Returns:
      a list of refs to matching projections, 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<P> getRefBy(@Nonnull Metamodel<P,V> field, @Nonnull V value)
      Retrieves a ref to exactly one projection based on a single field and its value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the projection field.
      value - the value to match against.
      Returns:
      a ref to the matching projection.
      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<P> getRefBy(@Nonnull Metamodel<P,V> field, @Nonnull Ref<V> value)
      Retrieves a ref to exactly one projection based on a single field and its referenced value.
      Type Parameters:
      V - the type of the referenced entity.
      Parameters:
      field - metamodel reference of the projection field.
      value - the referenced value to match against.
      Returns:
      a ref to the matching projection.
      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<P,V> field, @Nonnull V value)
      Counts projections matching the specified field and value.
      Type Parameters:
      V - the type of the field.
      Parameters:
      field - metamodel reference of the projection field.
      value - the value to match against.
      Returns:
      the count of matching projections.
      Throws:
      PersistenceException - if the count operation fails due to underlying database issues.
      Since:
      1.11

    • countBy

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

    • existsBy

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

    • page

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

      This method executes two queries: a SELECT COUNT(*) to determine the total number of projections, 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 projections per page.
      Returns:
      a page containing the results and pagination metadata.
      Since:
      1.10

    • page

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

      This method executes two queries: a SELECT COUNT(*) to determine the total number of projections, 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<P>> pageRef(int pageNumber, int pageSize)
      Returns a page of projection 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<P>> pageRef(@Nonnull Pageable pageable)
      Returns a page of projection refs using offset-based pagination.

      This method executes two queries: a SELECT COUNT(*) to determine the total number of projections, 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<P> scroll(@Nonnull Scrollable<P> 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<P> findAll()
      Returns a list of all projections of the type supported by this repository. Each element in the list represents a projection in the database, encapsulating all relevant data as mapped by the projection model.

      Note: Loading all projections 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<P>> findAllRef()
      Returns a list of refs to all projections of the type supported by this repository. Each element in the list represents a lightweight reference to a projection in the database, containing only the primary key.

      This method is useful when you need to retrieve all projection identifiers without loading the full projection data. The complete projection 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 projections 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<P> findAllById(@Nonnull Iterable<ID> ids)
      Retrieves a list of projections based on their primary keys.

      This method retrieves projections 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 projections 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 projections to retrieve, represented as an iterable collection.
      Returns:
      a list of projections corresponding to the provided primary keys. Projections are returned without any guarantee of order alignment with the input list. If an ID does not correspond to any projection in the database, no corresponding projection 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<P> findAllByRef(@Nonnull Iterable<Ref<P>> refs)
      Retrieves a list of projections based on their primary keys.

      This method retrieves projections 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 projections 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 projections to retrieve, represented as an iterable collection.
      Returns:
      a list of projections corresponding to the provided primary keys. Projections are returned without any guarantee of order alignment with the input list. If an ID does not correspond to any projection in the database, no corresponding projection 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.

    • selectById

      Stream<P> selectById(@Nonnull Stream<ID> ids)
      Retrieves a stream of projections 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 projections. The batching strategy enhances performance, particularly when dealing with large sets of primary keys.

      The resulting stream is lazily loaded, meaning that the projections 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 projections.

      Note: 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 projection IDs to retrieve from the repository.
      Returns:
      a stream of projections corresponding to the provided primary keys. The order of projections in the stream is not guaranteed to match the order of ids in the input stream. If an id does not correspond to any projection in the database, it will simply be skipped, and no corresponding projection will be included in the returned stream. If the same projection 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.

    • selectByRef

      Stream<P> selectByRef(@Nonnull Stream<Ref<P>> refs)
      Retrieves a stream of projections 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 projections. The batching strategy enhances performance, particularly when dealing with large sets of primary keys.

      The resulting stream is lazily loaded, meaning that the projections 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 projections.

      Note: 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 projections corresponding to the provided primary keys. The order of projections in the stream is not guaranteed to match the order of ids in the input stream. If an id does not correspond to any projection in the database, it will simply be skipped, and no corresponding projection will be included in the returned stream. If the same projection 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.

    • selectById

      Stream<P> selectById(@Nonnull Stream<ID> ids, int chunkSize)
      Retrieves a stream of projections 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 projections. The batching strategy enhances performance, particularly when dealing with large sets of primary keys.

      The resulting stream is lazily loaded, meaning that the projections 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 projections.

      Note: 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 projection IDs to retrieve from the repository.
      chunkSize - 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 projections corresponding to the provided primary keys. The order of projections in the stream is not guaranteed to match the order of ids in the input stream. If an id does not correspond to any projection in the database, it will simply be skipped, and no corresponding projection will be included in the returned stream. If the same projection 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.

    • selectByRef

      Stream<P> selectByRef(@Nonnull Stream<Ref<P>> refs, int chunkSize)
      Retrieves a stream of projections 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 projections. The batching strategy enhances performance, particularly when dealing with large sets of primary keys.

      The resulting stream is lazily loaded, meaning that the projections 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 projections.

      Note: 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.
      chunkSize - 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 projections corresponding to the provided primary keys. The order of projections in the stream is not guaranteed to match the order of refs in the input stream. If an id does not correspond to any projection in the database, it will simply be skipped, and no corresponding projection will be included in the returned stream. If the same projection 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 projections identified by the provided stream of IDs using the default batch size.

      This method calculates the total number of projections 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 projections.
      Returns:
      the total count of projections 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 projections 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 chunkSize 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 projections.
      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 projections 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<P>> refs)
      Counts the number of projections identified by the provided stream of refs using the default batch size.

      This method calculates the total number of projections 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 refs for which to count matching projections.
      Returns:
      the total count of projections 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<P>> refs, int chunkSize)
      Counts the number of projections 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 chunkSize 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 refs for which to count matching projections.
      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 projections matching the provided IDs.
      Throws:
      PersistenceException - if there is an error during the counting operation, such as connectivity issues.