Lifecycle annotation for repository methods which conditionally perform insert or update operations.

The Save annotation indicates that the annotated repository method accepts one or more entities and, for each entity, either adds its state to the database, or updates state already held in the database.

A Save 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 inserted or updated, or
• List<E> or E[] where E is the class of the entities to be inserted or 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 a Save method which conforms to this signature. Application of the Save annotation to a method with any other signature is not portable between Jakarta Data providers.

For example, consider an interface representing a garage:

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

The operation performed by the annotated method depends on whether the database already holds an entity with the unique identifier of an entity passed as an argument:

• If there is such an entity already held in the database, the annotated method must behave as if it were annotated @Update.
• Otherwise, if there is no such entity in the database, the annotated method must behave as if it were annotated @Insert.

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.