diff --git a/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml b/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml
index 09dc108865..20ae700f9f 100644
--- a/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml
+++ b/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml
@@ -374,10 +374,218 @@ public class Dog { ... }
- Class
+ Entity
- You can declare a persistent class using the
- class element. For example:
+ An entity is a regular Java object (aka POJO) which will be
+ persisted by Hibernate.
+
+ To mark an object as an entity in annotations, use the
+ @Entity annotation.
+
+ @Entity
+public class Flight implements Serializable {
+ Long id;
+
+ @Id
+ public Long getId() { return id; }
+
+ public void setId(Long id) { this.id = id; }
+}
+
+ That's pretty much it, the rest is optional. There are however any
+ options to tweak your entity mapping, let's explore them.
+
+ @Table lets you define the table the entity
+ will be persisted into. If undefined, the table name is the unqualified
+ class name of the entity. You can also optionally define the catalog,
+ the schema as well as unique constraints on the table.
+
+ @Entity
+@Table(name="TBL_FLIGHT",
+ schema="AIR_COMMAND",
+ uniqueConstraints=
+ @UniqueConstraint(
+ name="flight_number",
+ columnNames={"comp_prefix", "flight_number"} ) )
+public class Flight implements Serializable {
+ @Column(name="comp_prefix")
+ public String getCompagnyPrefix() { return companyPrefix; }
+
+ @Column(name="flight_number")
+ public String getNumber() { return number; }
+}
+
+ The constraint name is optional (generated if left undefined). The
+ column names composing the constraint correspond to the column names as
+ defined before the Hibernate NamingStrategy is
+ applied.
+
+ @Entity.name lets you define the shortcut name
+ of the entity you can used in JP-QL and HQL queries. It defaults to the
+ unqualified class name of the class.
+
+ Hibernate goes beyond the JPA specification and provide additional
+ configurations. Some of them are hosted on
+ @org.hibernate.annotations.Entity:
+
+
+
+ mutable (defaults to true): Immutable
+ classes, mutable=false, cannot be updated or
+ deleted by the application. This allows Hibernate to make some minor
+ performance optimizations.
+
+
+
+ dynamicInsert /
+ dynamicUpdate (defaults to false): specifies that
+ INSERT / UPDATE SQL should be
+ generated at runtime and contain only the columns whose values are
+ not null. The dynamic-update and
+ dynamic-insert settings are not inherited by
+ subclasses. Although these settings can increase performance in some
+ cases, they can actually decrease performance in others.
+
+
+
+ selectBeforeUpdate (defaults to false):
+ specifies that Hibernate should never perform
+ an SQL UPDATE unless it is certain that an object
+ is actually modified. Only when a transient object has been
+ associated with a new session using update(),
+ will Hibernate perform an extra SQL SELECT to
+ determine if an UPDATE is actually required. Use
+ of select-before-update will usually decrease
+ performance. It is useful to prevent a database update trigger being
+ called unnecessarily if you reattach a graph of detached instances
+ to a Session.
+
+
+
+ polymorphism (defaults to
+ IMPLICIT): determines whether implicit or
+ explicit query polymorphism is used. Implicit
+ polymorphism means that instances of the class will be returned by a
+ query that names any superclass or implemented interface or class,
+ and that instances of any subclass of the class will be returned by
+ a query that names the class itself. Explicit
+ polymorphism means that class instances will be returned only by
+ queries that explicitly name that class. Queries that name the class
+ will return only instances of subclasses mapped. For most purposes,
+ the default polymorphism=IMPLICIT is appropriate.
+ Explicit polymorphism is useful when two different classes are
+ mapped to the same table This allows a "lightweight" class that
+ contains a subset of the table columns.
+
+
+
+ persister: specifies a custom
+ ClassPersister. The persister
+ attribute lets you customize the persistence strategy used for the
+ class. You can, for example, specify your own subclass of
+ org.hibernate.persister.EntityPersister, or you
+ can even provide a completely new implementation of the interface
+ org.hibernate.persister.ClassPersister that
+ implements, for example, persistence via stored procedure calls,
+ serialization to flat files or LDAP. See
+ org.hibernate.test.CustomPersister for a simple
+ example of "persistence" to a Hashtable.
+
+
+
+ optimisticLock (defaults to
+ VERSION): determines the optimistic locking
+ strategy. If you enable dynamicUpdate, you will
+ have a choice of optimistic locking strategies:
+
+
+
+ version: check the version/timestamp
+ columns
+
+
+
+ all: check all columns
+
+
+
+ dirty: check the changed columns,
+ allowing some concurrent updates
+
+
+
+ none: do not use optimistic
+ locking
+
+
+
+ It is strongly recommended that you use
+ version/timestamp columns for optimistic locking with Hibernate.
+ This strategy optimizes performance and correctly handles
+ modifications made to detached instances (i.e. when
+ Session.merge() is used).
+
+
+
+
+ Be sure to import
+ @javax.persistence.Entity to mark a class as an
+ entity. It's a common mistake to import
+ @org.hibernate.annotations.Entity by
+ accident.
+
+
+ You can also alter how Hibernate deals with lazy initialization
+ for this class. On @Proxy, use
+ lazy=false to disable lazy fetching (not
+ recommended). You can also specify an interface to use for lazy
+ initializing proxies (defaults to the class itself): use
+ proxyClass on @Proxy.
+ Hibernate will initially return proxies (Javassist or CGLIB) that
+ implement the named interface. The persistent object will load when a
+ method of the proxy is invoked. See "Initializing collections and
+ proxies" below.
+
+ @BatchSize specifies a "batch size" for
+ fetching instances of this class by identifier. Not yet loaded instances
+ are loaded batch-size at a time (default 1).
+
+ You can specific an arbitrary SQL WHERE condition to be used when
+ retrieving objects of this class. Use @Where for
+ that.
+
+ In the same vein, @Check lets you define an
+ SQL expression used to generate a multi-row check
+ constraint for automatic schema generation.
+
+ There is no difference between a view and a base table for a
+ Hibernate mapping. This is transparent at the database level, although
+ some DBMS do not support views properly, especially with updates.
+ Sometimes you want to use a view, but you cannot create one in the
+ database (i.e. with a legacy schema). In this case, you can map an
+ immutable and read-only entity to a given SQL subselect expression using
+ @org.hibernate.annotations.Subselect:
+
+ @Entity
+@Subselect("select item.name, max(bid.amount), count(*) "
+ + "from item "
+ + "join bid on bid.item_id = item.id "
+ + "group by item.name")
+@Synchronize( {"item", "bid"} ) //tables impacted
+public class Summary {
+ @Id
+ public String getId() { return id; }
+ ...
+}
+
+ Declare the tables to synchronize this entity with, ensuring that
+ auto-flush happens correctly and that queries against the derived entity
+ do not return stale data. The <subselect> is
+ available both as an attribute and a nested mapping element.
+
+ We will now explore the same options using the hbm.xml structure.
+ You can declare a persistent class using the class
+ element. For example:
@@ -600,91 +808,7 @@ public class Dog { ... }
static inner class. Specify the class name using
the standard form i.e. e.g.Foo$Bar.
- Immutable classes, mutable="false", cannot be
- updated or deleted by the application. This allows Hibernate to make
- some minor performance optimizations.
-
- The optional proxy attribute enables lazy
- initialization of persistent instances of the class. Hibernate will
- initially return CGLIB proxies that implement the named interface. The
- persistent object will load when a method of the proxy is invoked. See
- "Initializing collections and proxies" below.
-
- Implicit polymorphism means that instances of
- the class will be returned by a query that names any superclass or
- implemented interface or class, and that instances of any subclass of
- the class will be returned by a query that names the class itself.
- Explicit polymorphism means that class instances
- will be returned only by queries that explicitly name that class.
- Queries that name the class will return only instances of subclasses
- mapped inside this <class> declaration as a
- <subclass> or
- <joined-subclass>. For most purposes, the
- default polymorphism="implicit" is appropriate.
- Explicit polymorphism is useful when two different classes are mapped to
- the same table This allows a "lightweight" class that contains a subset
- of the table columns.
-
- The persister attribute lets you customize the
- persistence strategy used for the class. You can, for example, specify
- your own subclass of
- org.hibernate.persister.EntityPersister, or you can
- even provide a completely new implementation of the interface
- org.hibernate.persister.ClassPersister that
- implements, for example, persistence via stored procedure calls,
- serialization to flat files or LDAP. See
- org.hibernate.test.CustomPersister for a simple
- example of "persistence" to a Hashtable.
-
- The dynamic-update and
- dynamic-insert settings are not inherited by
- subclasses, so they can also be specified on the
- <subclass> or
- <joined-subclass> elements. Although these
- settings can increase performance in some cases, they can actually
- decrease performance in others.
-
- Use of select-before-update will usually
- decrease performance. It is useful to prevent a database update trigger
- being called unnecessarily if you reattach a graph of detached instances
- to a Session.
-
- If you enable dynamic-update, you will have a
- choice of optimistic locking strategies:
-
-
-
- version: check the version/timestamp
- columns
-
-
-
- all: check all columns
-
-
-
- dirty: check the changed columns, allowing
- some concurrent updates
-
-
-
- none: do not use optimistic locking
-
-
-
- It is strongly recommended that you use
- version/timestamp columns for optimistic locking with Hibernate. This
- strategy optimizes performance and correctly handles modifications made
- to detached instances (i.e. when Session.merge() is
- used).
-
- There is no difference between a view and a base table for a
- Hibernate mapping. This is transparent at the database level, although
- some DBMS do not support views properly, especially with updates.
- Sometimes you want to use a view, but you cannot create one in the
- database (i.e. with a legacy schema). In this case, you can map an
- immutable and read-only entity to a given SQL subselect
- expression:
+ Here is how to do a virtual view (subselect) in XML:
<class name="Summary">
<subselect>
@@ -699,10 +823,8 @@ public class Dog { ... }
...
</class>
- Declare the tables to synchronize this entity with, ensuring that
- auto-flush happens correctly and that queries against the derived entity
- do not return stale data. The <subselect> is
- available both as an attribute and a nested mapping element.
+ The <subselect> is available both as an
+ attribute and a nested mapping element.