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

Lifecycle annotation for repository methods which perform insert operations.

The Insert annotation indicates that the annotated repository method adds the state of one or more entities to the database.

An Insert 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
List<E> or E[] where E is the class of the entities to be inserted.

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 Insert method which conforms to this signature. Application of the Insert annotation to a method with any other signature is not portable between Jakarta Data providers.

For example, if the method is annotated with @Insert and takes a parameter of type Car car, the return type can be Car. Similarly, if the parameter is of type Iterable<Car>, the return type can be Iterable<Car>. Consider an interface representing a garage:

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

When the annotated method is non-void, it must return an inserted 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 identifiers, initial versions, and other values which changed as a result of the insert. The order of entities within an Iterable or array return value must match the position of entities in the argument. After the annotated method returns, an original entity instance supplied as an argument might not accurately reflect the inserted state.

If an entity of the given type, and with the same unique identifier already exists in the database when the annotated method is called, and if the databases uses ACID (atomic, consistent, isolated, durable) transactions, then the annotated method must raise EntityExistsException. If the database follows the BASE model, or uses an append model to write data, this exception is not thrown.

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.

Annotation Interface Insert