Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

clarify semantics of StatelessSession.upsert() in javadoc 

Signed-off-by: Gavin King <gavin@hibernate.org>
This commit is contained in:
Gavin King 2024-06-02 13:48:47 +02:00
parent e895283c53
commit cf0b9089a4
1 changed files with 18 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
hibernate-core/src/main/java/org/hibernate/StatelessSession.java
View File

@ -72,6 +72,10 @@ public interface StatelessSession extends SharedSessionContract {
/** /**
* Insert a record. * Insert a record.
* <p> * <p>
* If the entity {@code @Id} field is declared to be generated,
* for example, if it is annotated {@code @GeneratedId}, the id
* is generated and assigned to the given instance.
* <p>
* The {@link jakarta.persistence.PostPersist} callback will be * The {@link jakarta.persistence.PostPersist} callback will be
* triggered if the operation is successful. * triggered if the operation is successful.
* *
@ -140,9 +144,20 @@ public interface StatelessSession extends SharedSessionContract {
* Use a SQL {@code merge into} statement to perform an upsert, * Use a SQL {@code merge into} statement to perform an upsert,
* that is, to insert the record if it does not exist, or update * that is, to insert the record if it does not exist, or update
* it if it already exists. * it if it already exists.
* <p>
* This method never performs id generation, and does not accept
* an entity instance with a null identifier. When id generation
* is required, use {@link #insert(Object)}.
* <p>
* On the other hand, {@code upsert()} does accept an entity
* instance with an assigned identifier value, even if the entity
* {@code @Id} field is declared to be generated, for example, if
* it is annotated {@code @GeneratedId}. Thus, this method may be
* used to import data from an external source.
* *
* @param entity a detached entity instance * @param entity a detached entity instance, or a new instance
* @throws TransientObjectException is the entity is transient * with an assigned identifier
* @throws TransientObjectException is the entity has a null id
* *
* @since 6.3 * @since 6.3
*/ */
@ -154,7 +169,7 @@ public interface StatelessSession extends SharedSessionContract {
* *
* @param entityName The entityName for the entity to be merged * @param entityName The entityName for the entity to be merged
* @param entity a detached entity instance * @param entity a detached entity instance
* @throws TransientObjectException is the entity is transient * @throws TransientObjectException is the entity has a null id
* *
* @since 6.3 * @since 6.3
*/ */