diff --git a/documentation/src/main/docbook/mappingGuide/en-US/Hibernate_Mapping_Guide.xml b/documentation/src/main/docbook/mappingGuide/en-US/Hibernate_Mapping_Guide.xml
index d37f7d4a89..db3e695df3 100644
--- a/documentation/src/main/docbook/mappingGuide/en-US/Hibernate_Mapping_Guide.xml
+++ b/documentation/src/main/docbook/mappingGuide/en-US/Hibernate_Mapping_Guide.xml
@@ -45,15 +45,18 @@
+
-
+
+
diff --git a/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/Entity.xml b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/Entity.xml
index 119fda757f..1842f293fc 100644
--- a/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/Entity.xml
+++ b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/Entity.xml
@@ -6,17 +6,330 @@
~ See the lgpl.txt file in the root directory or .
-->
- Entity
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns="http://docbook.org/ns/docbook" version="5.0">
+
+ Entity
+
+ Discuss mapping entities in the application domain model.
+
+
+
+
+ Related Topics
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ POJO Models
+
+
+ Section 2.1 The Entity Class of the JPA 2.1 specification
+ defines its requirements for an entity class. Applications that wish to remain portable across JPA providers
+ should adhere to these requirements.
+
+
+
+ The entity class must be annotated with the javax.persistence.Entity
+ annotation (or be denoted as such in XML mapping)
+
+
+
+
+ The entity class must have a public or protected no-argument constructor. It may define
+ additional constructors as well.
+
+
+
+
+ The entity class must be a top-level class.
+
+
+
+
+ An enum or interface may not be designated as an entity.
+
+
+
+
+ The entity class must not be final. No methods or persistent instance variables of the entity
+ class may be final.
+
+
+
+
+ If an entity instance is to be used remotely as a detached object, the entity class must
+ implement the Serializable interface.
+
+
+
+
+ Both abstract and concrete classes can be entities. Entities may extend non-entity classes as
+ well as entity classes, and non-entity classes may extend entity classes.
+
+
+
+
+ The persistent state of an entity is represented by instance variables, which may correspond to
+ JavaBean-style properties. An instance variable must be directly accessed only from within the
+ methods of the entity by the entity instance itself. The state of the entity is available to
+ clients only through the entity’s accessor methods (getter/setter methods) or other business
+ methods.
+
+
+
+
+
+
+ Hibernate, however, is not as strict in its requirements. The differences from the list above include:
+
+
+
+ The entity class must have a no-argument constructor, which may be public, protected or package
+ visibility. It may define additional constructors as well.
+
+
+
+
+ The entity class need not be a top-level class.
+
+
+
+
+ Technically Hibernate can persist final classes or classes with final persistent state
+ accessor (getter/setter) methods. However, it is generally not a good idea as doing
+ so will stop Hibernate from being able to generate proxies for lazy-loading the entity.
+
+
+
+
+ Hibernate does not really care if you expose direct access to your instance variables and
+ use them from outside the entity itself. The validity of such a paradigm, however, is debatable
+ at best.
+
+
+
+
+
+
+ Let's look at each requirement in detail.
+
+
+
+ Prefer non-final classes
+
+
+ This is a requirement for JPA. It is more of a recommendation for Hibernate.
+
+
+
+ A central feature of Hibernate is the ability to lazy load an entity's data via runtime proxies. This
+ feature depends upon the entity class being non-final or else implementing an interface that declares
+ all the attribute getters/setters. You can still persist classes that are declared final and that do
+ not implement such an interface with Hibernate; you just will not be able to use proxies for lazy
+ association fetching which will ultimately limit your options for performance tuning.
+
+
+
+
+ Starting in 5.0 Hibernate offers a more robust version of bytecode enhancement as another means
+ for handling lazy loading. Hibernate had some bytecode re-writing capabilities prior to 5.0 but
+ they were very rudimentary.
+
+
+
+
+
+ You should also avoid declaring persistent attribute getters and setters as final for the reasons
+ already mentioned. And of course making the instance variable hold the entiy's persistent state would
+ just simply not make any sense.
+
+
+
+
+ Implement a no-argument constructor
+
+
+ The entity class should have a no-argument constructor. Both Hibernate and JPA require this.
+
+
+
+ JPA requires that this constructor be defined as public or protected. Hibernate for the most part does
+ note care about the visibility as long as the system's SecurityManager allows overriding the visibility.
+ That said, the constructor should be defined with at least package visibility if you wish to leverage
+ runtime proxy generation.
+
+
+
+
+ Declare getters and setters for persistent attributes
+
+
+ Standard, portable JPA essentially requires this. Otherwise your model would violate the requirement
+ quoted above in regards to accessing the entity persistent state fields directly from outside the
+ entity itself.
+
+
+
+ Although Hibernate does not require it, it is recommended to follow JavaBean conventions by defining
+ getters and setters for you entities persistent attributes. You can still tell Hibernate to directly
+ access the entity's fields.
+
+
+
+ Attributes (whether fields or getters/setters) need not be declared public. Hibernate can deal with
+ attributes declared with public, protected, package or private visibility. Again, if wanting to use
+ runtime proxy generation for lazy loading the visibility for the getter/setter should be at least
+ package visibility.
+
+
+
+
+
+ Provide identifier attribute(s)
+
+
+
+ Historically this was considered optional. However, not defining identifier attribute(s) on the
+ entity should be considered a deprecated feature that will be removed in an upcoming release.
+
+
+
+
+ The identifier attribute does not necessarily need to be mapped to the column(s) that physically
+ define the primary key. However, it should map to column(s) that can uniquely identify each row.
+
+
+
+ We recommend that you declare consistently-named identifier attributes on persistent classes and
+ that you use a nullable (i.e., non-primitive) type.
+
+
+
+
+ Mapping the entity
+
+
+ The main piece in mapping the entity is the javax.persistence.Entity
+ annotation. The Entity annotation defines just one attribute name which
+ is used to give the entity a specific name for use in JPQL queries; by default the name is the
+ unqualified name of the entity class.
+
+
+
+ Simple @Entity
+
+
+
+
+ An entity models a database table. The identifier uniquely identifies each row in that table. By
+ default the name of the table is assumed to be the same as the name of the entity. To explicitly
+ give the name of the table or to specify other information about the table, we would use the
+ javax.persistence.Table annotation.
+
+
+
+ Simple @Entity with @Table
+
+
+
+
+ For details on mapping the identifier, see
+
+
+
+
+ Mapping optimistic locking
+
+
+ JPA defines support for optimistic locking based on either a version (sequential numeric) or timestamp
+ strategy. To enable this style of optimistic locking simply add the
+ javax.persistence.Version to the persistent attribute that defines the
+ optimistic locking value. According to JPA, the valid types for these attributes are limited to:
+
+
+ int, or Integer
+
+
+ short, or Short
+
+
+ long, or Long
+
+
+ java.sql.Timestamp
+
+
+
+
+
+ Version
+
+
+
+
+
+
+
+ Hibernate supports a form of optimistic locking that does not require a dedicated "version attribute".
+ This is intended mainly for use with modeling legacy schemas. The idea is that you can get Hibernate
+ to perform "version checks" using either all of the entity's attributes, or just the attributes that
+ have changed. This is achieved through the use of the
+ org.hibernate.annotations.OptimisticLocking annotation which defines a
+ single attribute of type org.hibernate.annotations.OptimisticLockType.
+ There are 4 available OptimisticLockTypes:
+
+
+
+ NONE - optimistic locking is disabled. Even if there is a @Version
+ annotation present.
+
+
+
+
+ VERSION (the default) - performs optimistic locking based on a @Version
+ as described above.
+
+
+
+
+ ALL - Perform optimistic locking based on *all* fields as part of an
+ expanded WHERE clause restriction for the UPDATE/DELETE SQL statement.
+
+
+
+
+ DIRTY - Perform optimistic locking based on *dirty* fields as part of
+ an expanded WHERE clause restriction for the UPDATE/DELETE SQL statement
+
+
+
+
+
+
+
+ Inheritance
+
+
+ blah blah blah
+
+
+
+
- * POJO, etc discussion from manual/en-US/chapters/domain/DomainModel.xml
* dynamic models (hbm.xml)
* Map mode
* proxy solutions (hibernate-core/src/test/java/org/hibernate/test/dynamicentity/tuplizer2)
- * inheritance
- * optimistic locking
\ No newline at end of file
diff --git a/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/Instant.java b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/Instant.java
new file mode 100644
index 0000000000..b2994b4cd8
--- /dev/null
+++ b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/Instant.java
@@ -0,0 +1,8 @@
+@Entity
+public class Thing2 {
+ @Id
+ private Integer id;
+ @Version
+ private Instant ts;
+ ...
+}
\ No newline at end of file
diff --git a/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/SimpleEntity.java b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/SimpleEntity.java
new file mode 100644
index 0000000000..9d3a771fd7
--- /dev/null
+++ b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/SimpleEntity.java
@@ -0,0 +1,13 @@
+@Entity
+public class Simple {
+ @Id
+ private Integer id;
+
+ public Integer getId() {
+ return id;
+ }
+
+ public void setId(Integer id) {
+ this.id = id;
+ }
+}
\ No newline at end of file
diff --git a/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/SimpleEntityWithTable.java b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/SimpleEntityWithTable.java
new file mode 100644
index 0000000000..c033f48229
--- /dev/null
+++ b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/SimpleEntityWithTable.java
@@ -0,0 +1,14 @@
+@Entity
+@Table( catalog="CRM", schema="purchasing", name="t_simple" )
+public class Simple {
+ @Id
+ private Integer id;
+
+ public Integer getId() {
+ return id;
+ }
+
+ public void setId(Integer id) {
+ this.id = id;
+ }
+}
\ No newline at end of file
diff --git a/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/Timestamp.java b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/Timestamp.java
new file mode 100644
index 0000000000..d987f16471
--- /dev/null
+++ b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/Timestamp.java
@@ -0,0 +1,8 @@
+@Entity
+public class Thing {
+ @Id
+ private Integer id;
+ @Version
+ Timestamp ts;
+ ...
+}
\ No newline at end of file
diff --git a/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/Version.java b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/Version.java
new file mode 100644
index 0000000000..94bad8cf04
--- /dev/null
+++ b/documentation/src/main/docbook/mappingGuide/en-US/chapters/entity/extras/Version.java
@@ -0,0 +1,8 @@
+@Entity
+public class Course {
+ @Id
+ private Integer id;
+ @Version
+ private Integer version;
+ ...
+}
\ No newline at end of file
diff --git a/documentation/src/main/docbook/userGuide/en-US/chapters/domain/DomainModel.xml b/documentation/src/main/docbook/userGuide/en-US/chapters/domain/DomainModel.xml
index c63bf1f450..5d6505c90e 100644
--- a/documentation/src/main/docbook/userGuide/en-US/chapters/domain/DomainModel.xml
+++ b/documentation/src/main/docbook/userGuide/en-US/chapters/domain/DomainModel.xml
@@ -104,7 +104,7 @@
- You should also avoid declaring persistemt attribute getters and setters as final for the reasons
+ You should also avoid declaring persistent attribute getters and setters as final for the reasons
already mentioned.
@@ -113,7 +113,7 @@
Declare getters and setters for persistent attributes
- Although not required, it is recommended to follow POJO/JavaBean conventions by defining getters and
+ Although not required, it is recommended to follow JavaBean conventions by defining getters and
setters for you entities persistent attributes. Hibernate can also directly access the entity's
fields.