Jakarta EE 11.0.0 · jakarta.data.repository.BasicRepository

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 unique identifier attribute (K) of the primary entity 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);

PageRequest pageRequest = PageRequest.ofSize(25);
Order<Employee> sorts = Order.by(Sort.asc("name"));
Page<Employee> page = people.findAll(pageRequest, sorts);

The module Javadoc provides an overview of Jakarta Data.

Method Summary

Modifier and Type	Method and Description
public void	delete(T must not be `null`. entity) Deletes a given entity.
public void	deleteAll(List<? extends T> Must not be `null`. Must not contain `null` elements. entities) Deletes the given entities.
public void	deleteById(K must not be `null`. id) Deletes the entity with the given Id. If the entity is not found in the persistence store it is silently ignored.
public Stream<T>	Returns: a stream of all entities; will never be `null`. findAll() Retrieves all persistent entities of the specified type from the database.
public Page<T>	Returns: a page of entities; will never be `null`. findAll(PageRequest the request for a paginated result; must not be `null`. pageRequest, Order<T> sort criteria that must deterministically order the results; must not be `null`. sortBy) Returns a `Page` of entities according to the page request that is provided as the `PageRequest` parameter.
public Optional<T>	Returns: the entity with the given Id or `Optional#empty()` if none is found. findById(K must not be `null`. id) Retrieves an entity by its Id.
public < Type of the entity to save. S extends T> S	Returns: The saved entity; never `null`. save(S The entity to be saved. Must not be `null`. entity) Saves a given entity to the database.
public < Type of entity to save. S extends T> List<S>	Returns: The saved entities; will never be `null`. saveAll(List<S> An iterable of entities. entities) Saves all given entities to the database.

Method Detail

delete back to summary

delete	back to summary
public 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:T must not be `null`. Annotations @Delete Exceptions 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

public 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:T: must not be null.

Annotations

@Delete

Exceptions

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

deleteAll back to summary

deleteAll	back to summary
public void deleteAll(List<? extends T> entities) Deletes the given entities. Deletion of each entity is performed by matching the unique identifier, 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:List<? extends T> Must not be `null`. Must not contain `null` elements. Annotations @Delete Exceptions 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.

public void deleteAll(List<? extends T> entities)

Deletes the given entities. Deletion of each entity is performed by matching the unique identifier, 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:List<? extends T>: Must not be null. Must not contain null elements.

Annotations

@Delete

Exceptions

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.

deleteById back to summary

deleteById	back to summary
public 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:K must not be `null`. Annotations @Delete Exceptions NullPointerException: when the Id is `null`.

public 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:K: must not be null.

Annotations

@Delete

Exceptions

NullPointerException:: when the Id is null.

findAll back to summary

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

public Stream<T> findAll()

Retrieves all persistent entities of the specified type from the database.

Returns:Stream<T>

a stream of all entities; will never be null.

Annotations

@Find

Exceptions

UnsupportedOperationException:: for Key-Value and Wide-Column databases that are not capable of the findAll operation.

findAll	back to summary
public Page<T> findAll(PageRequest pageRequest, Order<T> sortBy) Returns a `Page` of entities according to the page request that is provided as the `PageRequest` parameter. Parameters pageRequest:PageRequest the request for a paginated result; must not be `null`. sortBy:Order<T> sort criteria that must deterministically order the results; must not be `null`. Returns:Page<T> a page of entities; will never be `null`. Annotations @Find Exceptions NullPointerException: when `pageRequest` or `sortBy` is `null`. UnsupportedOperationException: for Key-Value and Wide-Column databases when the `PageRequest.Mode#CURSOR_NEXT` or `PageRequest.Mode#CURSOR_PREVIOUS` pagination mode is selected. See Also `PageRequest.Mode`

findById back to summary

findById	back to summary
public Optional<T> findById(K id) Retrieves an entity by its Id. Parameters id:K must not be `null`. Returns:Optional<T> the entity with the given Id or `Optional#empty()` if none is found. Annotations @Find Exceptions NullPointerException: when the Id is `null`.

public Optional<T> findById(K id)

Retrieves an entity by its Id.

Parameters

id:K: must not be null.

Returns:Optional<T>

the entity with the given Id or Optional#empty() if none is found.

Annotations

@Find

Exceptions

NullPointerException:: when the Id is null.

save back to summary

save	back to summary
public <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. Parameters <S> Type of the entity to save. entity:S The entity to be saved. Must not be `null`. Returns:S The saved entity; never `null`. Annotations @Save Exceptions 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`.

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

Parameters

<S>: Type of the entity to save.
entity:S: The entity to be saved. Must not be null.

Returns:S

The saved entity; never null.

Annotations

@Save

Exceptions

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 back to summary

saveAll	back to summary
public <S extends T> List<S> saveAll(List<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. Parameters <S> Type of entity to save. entities:List<S> An iterable of entities. Returns:List<S> The saved entities; will never be `null`. Annotations @Save Exceptions 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.

public <S extends T> List<S> saveAll(List<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.

Parameters

<S>: Type of entity to save.
entities:List<S>: An iterable of entities.

Returns:List<S>

The saved entities; will never be null.

Annotations

@Save

Exceptions

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.

public Interface BasicRepository<T, K>

Method Summary

Method Detail