Module jakarta.data
Package jakarta.data.repository

Interface BasicRepository<T,K>

Type Parameters:
T - the type of the primary entity class of the repository.
K - the type of the Id attribute of the primary entity.
All Superinterfaces:
DataRepository<T,K>
All Known Subinterfaces:
CrudRepository<T,K>, PageableRepository<T,K>
public interface BasicRepository<T,K> extends DataRepository<T,K>

A built-in repository supertype for performing basic operations on entities.

The type parameters of BasicRepository<T,K> capture the primary entity type (T) for the repository and the type of the Id entity attribute (K) that uniquely identifies each entity of that type.

The primary entity type is used for repository methods, such as countBy... and deleteBy..., which do not explicitly specify an entity type.

Example entity:

 @Entity
 public class Employee {
     @Id
     public int badgeNumber;
     public String firstName;
     public String lastName;
     ...
 }

Example repository:

 @Repository
 public interface Employees extends BasicRepository<Employee, Integer> {

     boolean deleteByBadgeNumber(int badgeNum);

     ...
 }

Example usage:

 @Inject
 Employees employees;

 ...

 Employee emp = ...
 emp = employees.save(emp);

 boolean deleted = employees.deleteByBadgeNumber(emp.badgeNum);

The module JavaDoc provides an overview of Jakarta Data.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    count()
    Retrieves the total number of persistent entities of the specified type in the database.
    void
    delete(T entity)
    Deletes a given entity.
    void
    deleteAll()
    Deletes all persistent entities managed by the repository.
    void
    deleteAll(Iterable<? extends T> entities)
    Deletes the given entities.
    void
    deleteById(K id)
    Deletes the entity with the given Id.
    void
    deleteByIdIn(Iterable<K> ids)
    Deletes all instances of the type T with the given Ids.
    boolean
    existsById(K id)
    Returns whether an entity with the given Id exists.
    Stream<T>
    findAll()
    Retrieves all persistent entities of the specified type from the database.
    Optional<T>
    findById(K id)
    Retrieves an entity by its Id.
    Stream<T>
    findByIdIn(Iterable<K> ids)
    Returns all instances of the type T with the given Ids.
    <S extends T>
    S
    save(S entity)
    Saves a given entity to the database.
    <S extends T>
    Iterable<S>
    saveAll(Iterable<S> entities)
    Saves all given entities to the database.

  • Method Details

    • save

      @Save <S extends T> S save(S entity)
      Saves a given entity to the database. If the entity has an Id or key that exists in the database, the method will update the existing record. Otherwise, it will insert a new record.

      If the entity has a non-null Id, the method will attempt to update the existing record in the database. If the entity does not exist in the database or has a null Id, then this method will insert a new record into the database.

      The entity instance that is returned as a result value of this method must be updated with all automatically generated values and incremented values that changed due to the save. After invoking this method, do not continue to use the entity value that is supplied as a parameter. This method makes no guarantees about the state of the entity value that is supplied as a parameter.

      If the entity uses optimistic locking and the version differs from the version in the database, an OptimisticLockingFailureException will be thrown.

      Type Parameters:
      S - Type of the entity to save.
      Parameters:
      entity - The entity to be saved. Must not be null.
      Returns:
      The saved entity; never null.
      Throws:
      OptimisticLockingFailureException - If the entity uses optimistic locking and the version in the database differs from the version in the entity.
      NullPointerException - If the provided entity is null.

    • saveAll

      @Save <S extends T> Iterable<S> saveAll(Iterable<S> entities)
      Saves all given entities to the database. If an entity has a non-null Id that exists in the database, the method will update the existing record. Otherwise, it will insert a new record.

      If an entity has a non-null Id, this method will attempt to update the existing record in the database. If an entity does not exist in the database or has a null Id, then this method inserts a new record into the database.

      The entity instances that are returned as a result of this method must be updated with all automatically generated values and incremented values that changed due to the save. After invoking this method, do not continue to use the entity values that are supplied in the parameter. This method makes no guarantees about the state of the entity values that are supplied in the parameter.

      Type Parameters:
      S - Type of entity to save.
      Parameters:
      entities - An iterable of entities.
      Returns:
      The saved entities; will never be null.
      Throws:
      OptimisticLockingFailureException - If an entity has a version for optimistic locking that differs from the version in the database.
      NullPointerException - If either the iterable is null or any element is null.

    • findById

      Optional<T> findById(K id)
      Retrieves an entity by its Id.
      Parameters:
      id - must not be null.
      Returns:
      the entity with the given Id or Optional.empty() if none is found.
      Throws:
      NullPointerException - when the Id is null.

    • existsById

      boolean existsById(K id)
      Returns whether an entity with the given Id exists.
      Parameters:
      id - must not be null.
      Returns:
      true if an entity with the given Id exists, false otherwise.
      Throws:
      NullPointerException - when the Id is null.

    • findAll

      Stream<T> findAll()
      Retrieves all persistent entities of the specified type from the database.
      Returns:
      a stream of all entities; will never be null.
      Throws:
      UnsupportedOperationException - for Key-Value and Wide-Column databases that are not capable of the findAll operation.

    • findByIdIn

      Stream<T> findByIdIn(Iterable<K> ids)
      Returns all instances of the type T with the given Ids.

      If some or all Ids are not found, no entities are returned for these Ids.

      Note that the order of elements in the result is not guaranteed.

      Parameters:
      ids - must not be null nor contain any null values.
      Returns:
      guaranteed to be not null. The size can be equal or less than the number of given ids.
      Throws:
      NullPointerException - in case the given ids or one of its items is null.

    • count

      long count()
      Retrieves the total number of persistent entities of the specified type in the database.
      Returns:
      the total number of entities.
      Throws:
      UnsupportedOperationException - for Key-Value and Wide-Column databases that are not capable of the count operation.

    • deleteById

      void deleteById(K id)
      Deletes the entity with the given Id.

      If the entity is not found in the persistence store it is silently ignored.

      Parameters:
      id - must not be null.
      Throws:
      NullPointerException - when the Id is null.

    • delete

      @Delete void delete(T entity)
      Deletes a given entity. Deletion is performed by matching the Id, and if the entity is versioned (for example, with jakarta.persistence.Version), then also the version. Other properties of the entity do not need to match.
      Parameters:
      entity - must not be null.
      Throws:
      OptimisticLockingFailureException - if the entity is not found in the database for deletion or has a version for optimistic locking that is inconsistent with the version in the database.
      NullPointerException - when the entity is null

    • deleteByIdIn

      void deleteByIdIn(Iterable<K> ids)
      Deletes all instances of the type T with the given Ids.

      Entities that are not found in the persistent store are silently ignored.

      Parameters:
      ids - must not be null. Must not contain null elements.
      Throws:
      NullPointerException - when the iterable is null or contains null elements.

    • deleteAll

      @Delete void deleteAll(Iterable<? extends T> entities)
      Deletes the given entities. Deletion of each entity is performed by matching the Id, and if the entity is versioned (for example, with jakarta.persistence.Version), then also the version. Other properties of the entity do not need to match.
      Parameters:
      entities - Must not be null. Must not contain null elements.
      Throws:
      OptimisticLockingFailureException - If an entity is not found in the database for deletion or has a version for optimistic locking that is inconsistent with the version in the database.
      NullPointerException - If the iterable is null or contains null elements.

    • deleteAll

      void deleteAll()
      Deletes all persistent entities managed by the repository.
      Throws:
      UnsupportedOperationException - for Key-Value and Wide-Column databases that are not capable of the deleteAll operation.