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

The Save annotation indicates that the annotated repository method updates one or more entities if found in the database and inserts entities into the database that are not found. This method must have a single parameter whose type must be one of the following:

The entity to be saved.
An Iterable of entities to be saved.
An array of entities to be saved.

The return type of an annotated method that requires a single entity as the parameter must have a return type that is void, Void, or the same type as the parameter. The return type of an annotated method that accepts an Iterable or array of entities as the parameter must have a return type that is void, Void, or an Iterable or array of the entity.

Saving an entity involves persisting it in the database. If the entity has an ID or key that already exists in the database, the method will update the existing record. If the entity does not exist in the database or has a null ID, this method will insert a new record. The entity instance returned by this method will be updated with any automatically generated or incremented values that changed due to the save operation.

Entities that are returned by the annotated method must include all values that were written to the database, including all automatically generated values and incremented values that changed due to the save. The position of entities within an Iterable or array return value must correspond to the position of entities in the parameter based on the unique identifier of the entity.

After invoking this method, avoid using the entity value that was supplied as a parameter, because it might not accurately reflect the changes made during the save process. If the entity uses optimistic locking and its version differs from the version in the database, an OptimisticLockingFailureException will be thrown.

For example, consider an interface representing a garage:

 @Repository
 interface Garage {
     @Save
     Car park(Car car);
 }

The @Save annotation can be used to indicate that the park(Car) method is responsible for updating the entity in the database if it already exists there and otherwise inserting a car entity into a database.

If this annotation is combined with other operation annotations (e.g., @Update, @Delete, @Insert), it will throw an UnsupportedOperationException because only one operation type can be specified. A Jakarta Data provider implementation must detect (and report) this error at compile time or at runtime.

See Also:

Annotation Interface Save