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>
orE[]
whereE
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.