diff --git a/reference/en/modules/architecture.xml b/reference/en/modules/architecture.xml
index 1cad8b7806..5cf244fe59 100644
--- a/reference/en/modules/architecture.xml
+++ b/reference/en/modules/architecture.xml
@@ -83,7 +83,7 @@
- Persistent Objects and Collections
+ Persistent objects and collections
Short-lived, single threaded objects containing persistent state and business
@@ -96,7 +96,7 @@
- Transient Objects and Collections
+ Transient and detached objects and collections
Instances of persistent classes that are not currently associated with a
@@ -157,6 +157,55 @@
+
+ Instance states
+
+ An instance of a persistent classes may be in one of three different states,
+ which are defined with respect to a persistence context.
+ The Hibernate Session object is the persistence context:
+
+
+
+
+ transient
+
+
+ The instance is not, and has never been associated with
+ any persistence context. It has no persistent identity
+ (primary key value).
+
+
+
+
+ persistent
+
+
+ The instance is currently associated with a persistence
+ context. It has a persistent identity (primary key value)
+ and, perhaps, a corresponding row in the database. For a
+ particular persistence context, Hibernate
+ guarantees that persistent identity
+ is equivalent to Java identity.
+
+
+
+
+ detached
+
+
+ The instance is was once associated with a persistence
+ context, but that context was closed, or the instance
+ was serialized to another process. It has a persistent
+ identity and, perhaps, a corrsponding row in the database.
+ For detached instances, Hibernate makes no guarantees
+ about the relationship between persistent identity and
+ Java identity.
+
+
+
+
+
+
JMX Integration
diff --git a/reference/en/modules/basic_mapping.xml b/reference/en/modules/basic_mapping.xml
index a3a1a72037..069d1a4872 100644
--- a/reference/en/modules/basic_mapping.xml
+++ b/reference/en/modules/basic_mapping.xml
@@ -459,10 +459,7 @@
We very strongly recommend that you use version/timestamp
columns for optimistic locking with Hibernate. This is the optimal strategy with
respect to performance and is the only strategy that correctly handles modifications
- made outside of the session (ie. when Session.update() is used).
- Keep in mind that a version or timestamp property should never be null, no matter
- what unsaved-value strategy, or an instance will be detected as
- transient.
+ made to detached instances (ie. when Session.update() is used).
@@ -475,71 +472,6 @@
-
- join
-
-
- Using the <join> element, it is possible to map
- properties of one class to several tables.
-
-
-
-
-
-
-
-
-
-
- ]]>
-
-
-
-
- tabe: The name of the joined table.
-
-
-
-
- schema (optional): Override the schema name specified by
- the root <hibernate-mapping> element.
-
-
-
-
- catalog (optional): Override the catalog name specified by
- the root <hibernate-mapping> element.
-
-
-
-
- sequential-select (optional - defaults to false):
- If enabled for a join defined on a subclass, then rather than joining, a sequential
- select will be issued if a row turns out to represent an instance of the subclass.
-
-
-
-
- inverse (optional - defaults to false):
- If enabled, Hibernate will not try to insert or update the properties defined
- by this join.
-
-
-
-
-
-
- TODO: Document join with an example
-
-
-
-
id
@@ -840,14 +772,17 @@
object's identifier property. Be very careful when using this feature to assign
keys with business meaning (almost always a terrible design decision).
-
- Due to its inherent nature, entities that use this generator cannot be saved
- via the Session's saveOrUpdate() method. Instead you have to explicitly specify to
- Hibernate if the object should be saved or updated by calling either the
- save() or update() method of the Session.
-
+
+ If an entity uses an assigned identifier or composite identifier (below), Hibernate
+ cannot use the value of the identifier property to distinguish between transient
+ and detached instances. In this case, you have three options. Either map a version
+ or timestamp property, implement Interceptor.isUnsaved() (see
+ later), or simply disable cascades and explicitly save and update individual instances
+ using Session.save() and Session.update()
+ This is a common "gotcha" for new users!
+
@@ -1067,7 +1002,15 @@
Version numbers may be of type long, integer,
short, timestamp or calendar.
-
+
+
+ A version or timestamp property should never be null for a detached instance, so
+ Hibernate will detact any instance with a null version or timestamp as transient,
+ no matter what other unsaved-value strategies are specified.
+ Declaring a nullable version or timestamp property is an easy way to avoid
+ any problems with transitive reattachment in Hibernate, especially useful for people
+ using assigned identiifers or composite keys!
+
@@ -1151,7 +1094,9 @@
-
+
+
+
]]>
@@ -1173,7 +1120,8 @@
column (optional - defaults to the property name): the name
- of the mapped database table column.
+ of the mapped database table column. This may also be specified by nested
+ <column> element(s).
@@ -1206,10 +1154,23 @@
lazy (optional - defaults to false): Specifies
- that this property should be fetched lazily when the instance variable is first
- accessed (requires build-time bytecode instrumentation).
+ that this property should be fetched lazily when the instance variable is first
+ accessed (requires build-time bytecode instrumentation).
+
+
+ unique (optional): Enable the DDL generation of a unique
+ constraint for the columns. Also, allow this to be the target of
+ a property-ref.
+
+
+
+
+ not-null (optional): Enable the DDL generation of a nullability
+ constraint for the columns.
+
+
@@ -1290,6 +1251,7 @@
+
]]>
@@ -1311,7 +1274,10 @@
- column (optional): The name of the column.
+ column (optional): The name of the foreign key column.
+ This may also be specified by nested <column>
+ element(s).
+
@@ -1356,10 +1322,17 @@
-
- unique (optional): Enable the DDL generation of a unique
- constraint for the foreign-key column.
-
+
+ unique (optional): Enable the DDL generation of a unique
+ constraint for the foreign-key column. Also, allow this to be the target of
+ a property-ref.
+
+
+
+
+ not-null (optional): Enable the DDL generation of a nullability
+ constraint for the foreign key columns.
+
@@ -1587,13 +1560,15 @@
+
+ access="field|property|ClassName"
+ lazy="true|false">
@@ -1629,6 +1604,13 @@
strategy Hibernate should use for accessing the property value.
+
+
+ lazy (optional - defaults to false): Specifies
+ that this component should be fetched lazily when the instance variable is first
+ accessed (requires build-time bytecode instrumentation).
+
+
@@ -1719,9 +1701,9 @@
joined-subclass
- Alternatively, a subclass that is persisted to its own table (table-per-subclass
- mapping strategy) is declared using a <joined-subclass>
- element.
+ Alternatively, each subclass may be mapped to its own table (table-per-subclass
+ mapping strategy). Inherited state is retrieved by joining with the table of the
+ superclass. We use the <joined-subclass> element.
@@ -1729,13 +1711,20 @@
+
+ dynamic-insert="true|false"
+ schema="schema"
+ catalog="catalog"
+ extends="SuperclassName"
+ persister="ClassName"
+ subselect="TODO">
@@ -1749,12 +1738,17 @@
+
+ table: The name of the subclass table.
+
+
+
proxy (optional): Specifies a class or interface to use
for lazy initializing proxies.
-
+
lazy (optional): Setting lazy="true" is a shortcut
equalivalent to specifying the name of the class itself as the proxy
@@ -1764,6 +1758,10 @@
+
+ TODO
+
+
No discriminator column is required for this mapping strategy. Each subclass must,
however, declare a table column holding the object identifier using the
@@ -1809,14 +1807,207 @@
union-subclass
- Another option is to map only the concrete classes of an inheritance hierarchy
- (as in table-per-concrete-class) to tables, but not the superclass. This strategy
- has some problems with polymorphic associations, which can be avoided with a
- <union-subclass> mapping.
+ A third option is to map only the concrete classes of an inheritance hierarchy
+ to tables, (the table-per-concrete-class strategy) where each table defines all
+ persistent state of the class, including inherited state. In Hibernate, it is
+ not absolutely necessary to explicitly map such inheritance hierarchies. You
+ can simply map each class with a separate <class>
+ declaration. However, if you wish use polymorphic associations, you need to
+ use the <union-subclass> mapping.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ .....
+]]>
+
+
+
+ name: The fully qualified class name of the subclass.
+
+
+
+
+ table: The name of the subclass table.
+
+
+
+
+ proxy (optional): Specifies a class or interface to use
+ for lazy initializing proxies.
+
+
+
+
+ lazy (optional): Setting lazy="true" is a shortcut
+ equalivalent to specifying the name of the class itself as the proxy
+ interface.
+
+
+
+
+
- See the documentation chapter about Inheritance Mapping for more details.
+ TODO
+
+
+
+ No discriminator column or key column is required for this mapping strategy.
+
+
+
+
+
+ join
+
+
+ Using the <join> element, it is possible to map
+ properties of one class to several tables.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ...
+]]>
+
+
+
+
+ tabe: The name of the joined table.
+
+
+
+
+ schema (optional): Override the schema name specified by
+ the root <hibernate-mapping> element.
+
+
+
+
+ catalog (optional): Override the catalog name specified by
+ the root <hibernate-mapping> element.
+
+
+
+
+ sequential-select (optional - defaults to false):
+ If enabled for a join defined on a subclass, then rather than joining, a sequential
+ select will be issued if a row turns out to represent an instance of the subclass.
+
+
+
+
+ inverse (optional - defaults to false):
+ If enabled, Hibernate will not try to insert or update the properties defined
+ by this join.
+
+
+
+
+
+
+ TODO: Document join with an example
+
+
+
+
+
+ key
+
+
+ We've seen the <key> element crop up a few times
+ now. It appears anywhere the parent mapping element defines a join to
+ a new table, and defines the foreign key in the joined table, that references
+ the primary key of the original table.
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+ column (optional): The name of the foreign key column.
+ This may also be specified by nested <column>
+ element(s).
+
+
+
+
+ on-delete (optional, defaults to noaction):
+ Specifies whether the foreign key constraint has database-level cascade delete
+ enabled.
+
+
+
+
+ property-ref (optional): Specifies that the foreign key refers
+ to columns that are not the primary key of the orginal table. (Provided for
+ legacy data.)
+
+
+
+
+
+
+ We recommend that for systems where delete performance is important, all keys should be
+ defined on-delete="cascade", and Hibernate will use a database-level
+ ON CASCADE DELETE constraint, instead of many individual
+ DELETE statements. Be aware that this feature bypasses Hibernate's
+ usual optimistic locking strategy for versioned data.
@@ -2108,21 +2299,14 @@
user session data, etc).
-
-
-
-]]>
-
The meta-type attribute lets the application specify a custom type that
maps database column values to persistent classes which have identifier properties of the
- type specified by id-type. If the meta-type returns instances of
- java.lang.Class, nothing else is required. On the other hand, if it is
- a basic type like string or character, you must
- specify the mapping from values to classes.
+ type specified by id-type. You must specify the mapping from values of
+ the meta-type to class names.
-
+
@@ -2165,9 +2349,8 @@
- meta-type (optional - defaults to class):
- a type that maps java.lang.Class to a single database column
- or, alternatively, a type that is allowed for a discriminator mapping.
+ meta-type (optional - defaults to string):
+ Any type that is allowed for a discriminator mapping.
@@ -2185,11 +2368,6 @@
-
- The old object type that filled a similar role in Hibernate 1.2 is still
- supported, but is now semi-deprecated.
-
-
@@ -2231,7 +2409,7 @@
- Using XDOclet markup
+ Using XDoclet markup
Many Hibernate users prefer to embed mapping information directly in sourcecode using
@@ -2251,7 +2429,7 @@ import java.util.Date;
public class Cat {
private Long id; // identifier
private Date birthdate;
- private Cat mate;
+ private Cat mother;
private Set kittens
private Color color;
private char sex;
@@ -2271,13 +2449,13 @@ public class Cat {
/**
* @hibernate.many-to-one
- * column="MATE_ID"
+ * column="PARENT_ID"
*/
- public Cat getMate() {
- return mate;
+ public Cat getMother() {
+ return mother;
}
- void setMate(Cat mate) {
- this.mate = mate;
+ void setMother(Cat mother) {
+ this.mother = mother;
}
/**
@@ -2315,6 +2493,7 @@ public class Cat {
/**
* @hibernate.set
* lazy="true"
+ * inverse="true"
* order-by="BIRTH_DATE"
* @hibernate.collection-key
* column="PARENT_ID"