Jakarta EE 11.0.0 · jakarta.data.repository.CrudRepository

A built-in repository supertype for performing Create, Read, Update, and Delete (CRUD) operations.

This repository extends the BasicRepository interface, adding insert and update operations in addition to basic retrieval and deletion. This interface combines the Data Access Object (DAO) aspect with the repository pattern, offering a versatile and complete solution for managing persistent entities within Java applications.

The type parameters of CrudRepository<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 Cars {
    @Id
    public long vin;
    public String make;
    public String model;
    public int year;
    ...
}

Example repository:

@Repository
public interface Cars extends CrudRepository<Car, Long> {

    List<Car> findByMakeAndModel(String make, String model, Sort<?>... sorts);

    ...
}

Example usage:

@Inject
Cars cars;

...

Car car1 = ...
car1 = cars.insert(car1);

List<Car> found = findByMakeAndModel(car1.make,
                                     car1.model,
                                     Sort.desc("year"),
                                     Sort.asc("vin"));

The module Javadoc provides an overview of Jakarta Data.

Method Summary

Modifier and Type	Method and Description
public < Type of the entity to insert. S extends T> S	Returns: the inserted entity, which may or may not be a different instance depending on whether the insert caused values to be generated or automatically incremented. insert(S the entity to insert. Must not be `null`. entity) Inserts an entity into the database.
public < Type of the entities to insert. S extends T> List<S>	Returns: an iterable containing the inserted entities, which may or may not be different instances depending on whether the insert caused values to be generated or automatically incremented. insertAll(List<S> entities to insert. entities) Inserts multiple entities into the database.
public < Type of the entity to update. S extends T> S	Returns: an updated entity instance including all automatically generated values, updated versions, and incremented values which changed as a result of the update. update(S the entity to update. Must not be `null`. entity) Modifies an entity that already exists in the database.
public < Type of the entities to update. S extends T> List<S>	Returns: updated entity instances, in the same order as the supplied entities, and including all automatically generated values, updated versions, and incremented values which changed as a result of the update. updateAll(List<S> entities to update. entities) Modifies entities that already exist in the database.

Inherited from jakarta.data.repository.BasicRepository:: delete deleteAll deleteById findAll findAll findById save saveAll

Method Detail

insert back to summary

insert	back to summary
public <S extends T> S insert(S entity) Inserts an entity into the database. If an entity of this type with the same unique identifier already exists in the database and the database supports ACID transactions, then this method raises `EntityExistsException`. In databases that follow the BASE model or use an append model to write data, this exception is not thrown. The entity instance returned as a result of this method must include all values that were written to the database, including all automatically generated values and incremented values that changed due to the insert. After invoking this method, do not continue to use the instance that is supplied as a parameter. This method makes no guarantees about the state of the instance that is supplied as a parameter. Parameters <S> Type of the entity to insert. entity:S the entity to insert. Must not be `null`. Returns:S the inserted entity, which may or may not be a different instance depending on whether the insert caused values to be generated or automatically incremented. Annotations @Insert Exceptions EntityExistsException: if the entity is already present in the database (in ACID-supported databases). NullPointerException: if the entity is null.

public <S extends T> S insert(S entity)

Inserts an entity into the database. If an entity of this type with the same unique identifier already exists in the database and the database supports ACID transactions, then this method raises EntityExistsException. In databases that follow the BASE model or use an append model to write data, this exception is not thrown.

The entity instance returned as a result of this method must include all values that were written to the database, including all automatically generated values and incremented values that changed due to the insert. After invoking this method, do not continue to use the instance that is supplied as a parameter. This method makes no guarantees about the state of the instance that is supplied as a parameter.

Parameters

<S>: Type of the entity to insert.
entity:S: the entity to insert. Must not be null.

Returns:S

the inserted entity, which may or may not be a different instance depending on whether the insert caused values to be generated or automatically incremented.

Annotations

@Insert

Exceptions

EntityExistsException:: if the entity is already present in the database (in ACID-supported databases).
NullPointerException:: if the entity is null.

insertAll back to summary

insertAll	back to summary
public <S extends T> List<S> insertAll(List<S> entities) Inserts multiple entities into the database. If any entity of this type with the same unique identifier as any of the given entities already exists in the database and the database supports ACID transactions, then this method raises `EntityExistsException`. In databases that follow the BASE model or use an append model to write data, this exception is not thrown. The entities within the returned `Iterable` must include all values that were written to the database, including all automatically generated values and incremented values that changed due to the insert. After invoking this method, do not continue to use the entity instances that are supplied in the parameter. This method makes no guarantees about the state of the entity instances that are supplied in the parameter. The position of entities within the `Iterable` return value must correspond to the position of entities in the parameter based on the unique identifier of the entity. Parameters <S> Type of the entities to insert. entities:List<S> entities to insert. Returns:List<S> an iterable containing the inserted entities, which may or may not be different instances depending on whether the insert caused values to be generated or automatically incremented. Annotations @Insert Exceptions EntityExistsException: if any of the entities are already present in the database (in ACID-supported databases). NullPointerException: if the iterable is null or any element is null.

public <S extends T> List<S> insertAll(List<S> entities)

Inserts multiple entities into the database. If any entity of this type with the same unique identifier as any of the given entities already exists in the database and the database supports ACID transactions, then this method raises EntityExistsException. In databases that follow the BASE model or use an append model to write data, this exception is not thrown.

The entities within the returned Iterable must include all values that were written to the database, including all automatically generated values and incremented values that changed due to the insert. After invoking this method, do not continue to use the entity instances that are supplied in the parameter. This method makes no guarantees about the state of the entity instances that are supplied in the parameter. The position of entities within the Iterable return value must correspond to the position of entities in the parameter based on the unique identifier of the entity.

Parameters

<S>: Type of the entities to insert.
entities:List<S>: entities to insert.

Returns:List<S>

an iterable containing the inserted entities, which may or may not be different instances depending on whether the insert caused values to be generated or automatically incremented.

Annotations

@Insert

Exceptions

EntityExistsException:: if any of the entities are already present in the database (in ACID-supported databases).
NullPointerException:: if the iterable is null or any element is null.

update back to summary

update	back to summary
public <S extends T> S update(S entity) Modifies an entity that already exists in the database. For an update to be made, a matching entity with the same unique identifier must be present in the database. In databases that use an append model to write data or follow the BASE model, this method behaves the same as the `insert` method. If the entity is versioned (for example, with `jakarta.persistence.Version` or by another convention from the entity model such as having an attribute named `version`), then the version must also match. The version is automatically incremented when making the update. Parameters <S> Type of the entity to update. entity:S the entity to update. Must not be `null`. Returns:S an updated entity instance including all automatically generated values, updated versions, and incremented values which changed as a result of the update. Annotations @Update Exceptions OptimisticLockingFailureException: the entity is not found in the database or has a version that differs from the version in the database. NullPointerException: if the entity is null.

public <S extends T> S update(S entity)

Modifies an entity that already exists in the database.

For an update to be made, a matching entity with the same unique identifier must be present in the database. In databases that use an append model to write data or follow the BASE model, this method behaves the same as the insert method.

If the entity is versioned (for example, with jakarta.persistence.Version or by another convention from the entity model such as having an attribute named version), then the version must also match. The version is automatically incremented when making the update.

Parameters

<S>: Type of the entity to update.
entity:S: the entity to update. Must not be null.

Returns:S

an updated entity instance including all automatically generated values, updated versions, and incremented values which changed as a result of the update.

Annotations

@Update

Exceptions

OptimisticLockingFailureException:: the entity is not found in the database or has a version that differs from the version in the database.
NullPointerException:: if the entity is null.

updateAll back to summary

updateAll	back to summary
public <S extends T> List<S> updateAll(List<S> entities) Modifies entities that already exist in the database. For an update to be made to an entity, a matching entity with the same unique identifier must be present in the database. In databases that use an append model to write data or follow the BASE model, this method behaves the same as the `insertAll` method. If the entity is versioned (for example, with `jakarta.persistence.Version` or by another convention from the entity model such as having an attribute named `version`), then the version must also match. The version is automatically incremented when making the update. Parameters <S> Type of the entities to update. entities:List<S> entities to update. Returns:List<S> updated entity instances, in the same order as the supplied entities, and including all automatically generated values, updated versions, and incremented values which changed as a result of the update. Annotations @Update Exceptions OptimisticLockingFailureException: If any of the supplied entities is not found in the database or has a version that differs from the version in the database. NullPointerException: if either the supplied `Iterable` is null or any element is null.

public <S extends T> List<S> updateAll(List<S> entities)

Modifies entities that already exist in the database.

For an update to be made to an entity, a matching entity with the same unique identifier must be present in the database. In databases that use an append model to write data or follow the BASE model, this method behaves the same as the insertAll method.

Parameters

<S>: Type of the entities to update.
entities:List<S>: entities to update.

Returns:List<S>

updated entity instances, in the same order as the supplied entities, and including all automatically generated values, updated versions, and incremented values which changed as a result of the update.

Annotations

@Update

Exceptions

OptimisticLockingFailureException:: If any of the supplied entities is not found in the database or has a version that differs from the version in the database.
NullPointerException:: if either the supplied Iterable is null or any element is null.

public Interface CrudRepository<T, K>

Method Summary

Method Detail