Annotation Interface Insert
The Insert
annotation indicates that the annotated repository method requests that one or more entities
be inserted into the database. This method must have a single parameter whose type must be one of the following:
- The entity to be inserted.
- An
Iterable
of entities to be inserted. - An array of entities to be inserted.
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.
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 an Iterable<Car>
or an array of Car
, the return type can be
Iterable<Car>
.
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 insert. 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, it is recommended not to use the entity value supplied as a parameter, as this method makes no guarantees about the state of the entity value after insertion.
If an entity of this type with the same unique identifier already exists in the database
and the databases performs ACID (atomic, consistent, isolated, durable) transactions,
then annotated method raises EntityExistsException
.
In databases that follow the BASE model or use an append model to write data,
this exception is not thrown.
For example, consider an interface representing a garage:
@Repository interface Garage { @Insert Car park(Car car); }
The @Insert
annotation can be used to indicate that the park(Car)
method is responsible for inserting
a Car
entity into a database.
If this annotation is combined with other operation annotations (e.g., @Update
, @Delete
,
@Save
), 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.