Annotation Interface Update


@Documented @Retention(RUNTIME) @Target(METHOD) public @interface Update

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> or E[] where E 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.