Skip to content

Commit cc05847

Browse files
committed
improve explanation of whole transient vs detached stuff
include mention of workarounds
1 parent 7f8fbb5 commit cc05847

File tree

1 file changed

+8
-2
lines changed

1 file changed

+8
-2
lines changed

documentation/src/main/asciidoc/introduction/Interacting.adoc

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -111,13 +111,19 @@ The two most useful heuristics are:
111111
1. If the entity has a <<generated-identifiers,generated identifier>>, the value of the id field is inspected: if the value currently assigned to the id field is the default value for the type of the field, then the object is transient; otherwise, the object is detached.
112112
2. If the entity has a <<version-attributes,version>>, the value of the version field is inspected: if the value currently assigned to the version field is the default value, or a negative number, then the object is transient; otherwise, the object is detached.
113113

114-
If the entity has neither a generated id, nor a version, Hibernate falls back to just doing something reasonable.
114+
If the entity has neither a generated id, nor a version, Hibernate usually falls back to just doing something reasonable.
115+
In extreme cases a `SELECT` query will be issued to determine whether a matching row exists in the database.
115116

116117
[WARNING]
117118
These heuristics aren't perfect.
118-
It's quite easy to confuse Hibernate by assigning a value to the id field or version field that makes a new transient instance look like it's detached.
119+
It's quite easy to confuse Hibernate by assigning a value to the id field or version field, makeing a new transient instance look like it's detached.
119120
We therefore strongly discourage assigning values to fields annotated `@GeneratedValue` or `@Version` before passing an entity to Hibernate.
120121

122+
[TIP]
123+
If the heuristics ever happen cause a real problem, you may implement your own Post-it tagging via link:{doc-javadoc-url}org/hibernate/Interceptor.html#isTransient(java.lang.Object)[`Interceptor.isTransient()`].
124+
The `Interceptor` interface -- along with its friend link:{doc-javadoc-url}org/hibernate/CustomEntityDirtinessStrategy.html[`CustomEntityDirtinessStrategy`] -- allows advanced users to augment the built-in handling of managed entities with custom behavior.
125+
These interfaces are very useful if you're building your own persistence framework with Hibernate as the foundation.
126+
121127
[[creating-session]]
122128
=== Creating a session
123129

0 commit comments

Comments
 (0)