Lifecycle annotation for repository methods which perform update operations.
The Update
annotation indicates that the annotated repository method updates the state of one or more
entities already held in the database.
An Update
method accepts an instance or instances of an entity class. The method must
have exactly one parameter whose type is either:
- the class of the entity to be updated, or
List<E>
orE[]
whereE
is the class of the entities to be updated.
The annotated method must either be declared void
, or have a return type that is the same as the type of
its parameter.
All Jakarta Data providers are required to accept an Update
method which conforms to this signature.
For example, consider an interface representing a garage:
@Repository interface Garage { @Update Car update(Car car); }
When the annotated method is non-void
, it must return an updated entity instance for each entity instance
passed as an argument. Instances returned by the annotated method must include all values that were written to the
database, including all automatically generated values, updated versions, and incremented values which changed as a
result of the update. The order of entities within an Iterable
or array return value must match the position
of entities in the argument, based on the unique identifier of the entity. After the annotated method returns, an
original entity instance supplied as an argument might not accurately reflect the updated state.
Updates are performed by matching the unique identifier of the entity. If the entity is versioned, for example,
with jakarta.persistence.Version
, the version is also checked for consistency. Attributes other than the
identifier and version do not need to match. If no entity with a matching identifier is found in the database, or
if the entity with a matching identifier does not have a matching version, the annotated method must raise
OptimisticLockingFailureException
.
If the database follows the BASE model, or uses an append model to write data, the annotated method behaves the same
as the @Insert
method.
Annotations such as @Find
, @Query
, @Insert
, @Update
, @Delete
, and
@Save
are mutually-exclusive. A given method of a repository interface may have at most one @Find
annotation, lifecycle annotation, or query annotation.