From hibernate-commits at lists.jboss.org Fri Apr 23 13:09:48 2010
Content-Type: multipart/mixed; boundary="===============2058346865533772690=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r19286 -
core/trunk/documentation/manual/src/main/docbook/en-US/content.
Date: Fri, 23 Apr 2010 13:09:48 -0400
Message-ID: <201004231709.o3NH9mh2022681@svn01.web.mwc.hst.phx2.redhat.com>
--===============2058346865533772690==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Author: epbernard
Date: 2010-04-23 13:09:47 -0400 (Fri, 23 Apr 2010)
New Revision: 19286
Modified:
core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_map=
ping.xml
Log:
HHH-5152 @Entity description
Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/ba=
sic_mapping.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_ma=
pping.xml 2010-04-23 17:04:00 UTC (rev 19285)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_ma=
pping.xml 2010-04-23 17:09:47 UTC (rev 19286)
@@ -374,11 +374,219 @@
=
- 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 =3D 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 en=
tity
+ will be persisted into. If undefined, the table name is the unqualif=
ied
+ class name of the entity. You can also optionally define the catalog,
+ the schema as well as unique constraints on the table.
+
+ @Entity
+(a)Table(name=3D"TBL_FLIGHT", =
+ schema=3D"AIR_COMMAND", =
+ uniqueConstraints=3D
+ @UniqueConstraint(
+ name=3D"flight_number", =
+ columnNames=3D{"comp_prefix", "flight_number"} ) )
+public class Flight implements Serializable {
+ @Column(name=3D"comp_prefix")
+ public String getCompagnyPrefix() { return companyPrefix; }
+
+ @Column(name=3D"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 n=
ame
+ 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 additi=
onal
+ configurations. Some of them are hosted on
+ @org.hibernate.annotations.Entity:
+
+
+
+ mutable (defaults to true): Immutable
+ classes, mutable=3Dfalse, cannot be updated or
+ deleted by the application. This allows Hibernate to make some m=
inor
+ performance optimizations.
+
+
+
+ dynamicInsert /
+ dynamicUpdate (defaults to false): specifies =
that
+ INSERT / UPDATE SQL should=
be
+ generated at runtime and contain only the columns whose values a=
re
+ 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 perfo=
rm
+ an SQL UPDATE unless it is certain that an ob=
ject
+ 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 b=
eing
+ called unnecessarily if you reattach a graph of detached instanc=
es
+ 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 clas=
s,
+ 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 c=
lass
+ will return only instances of subclasses mapped. For most purpos=
es,
+ the default polymorphism=3DIMPLICIT is approp=
riate.
+ 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 t=
he
+ class. You can, for example, specify your own subclass of
+ org.hibernate.persister.EntityPersister, or y=
ou
+ 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 simp=
le
+ example of "persistence" to a Hashtable.
+
+
+
+ optimisticLock (defaults to
+ VERSION): determines the optimistic locking
+ strategy. If you enable dynamicUpdate, you wi=
ll
+ 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 u=
se
+ 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 a=
s 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=3Dfalse 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 insta=
nces
+ are loaded batch-size at a time (default 1).
+
+ You can specific an arbitrary SQL WHERE condition to be used w=
hen
+ retrieving objects of this class. Use @Where =
for
+ that.
+
+ In the same vein, @Check lets you defin=
e 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, althou=
gh
+ 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 u=
sing
+ @org.hibernate.annotations.Subselect:
+
+ @Entity
+(a)Subselect("select item.name, max(bid.amount), count(*) "
+ + "from item "
+ + "join bid on bid.item_id =3D item.id "
+ + "group by item.name")
+(a)Synchronize( {"item", "bid"} ) //tables impacted
+public class Summary {
+ @Id
+ public String getId() { return id; }
+ ...
+}
+
+ Declare the tables to synchronize this entity with, ensuring t=
hat
+ auto-flush happens correctly and that queries against the derived en=
tity
+ 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 structu=
re.
+ You can declare a persistent class using the class
+ element. For example:
+
@@ -600,92 +808,8 @@
static inner class. Specify the class name using
the standard form i.e. e.g.Foo$Bar.
=
- Immutable classes, mutable=3D"false", canno=
t be
- updated or deleted by the application. This allows Hibernate to make
- some minor performance optimizations.
+ Here is how to do a virtual view (subselect) in XML:
=
- The optional proxy attribute enables lazy
- initialization of persistent instances of the class. Hibernate will
- initially return CGLIB proxies that implement the named interface. T=
he
- persistent object will load when a method of the proxy is invoked. S=
ee
- "Initializing collections and proxies" below.
-
- Implicit polymorphism means that instance=
s 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=3D"implicit" is appropriate.
- Explicit polymorphism is useful when two different classes are mappe=
d to
- the same table This allows a "lightweight" class that contains a sub=
set
- of the table columns.
-
- The persister attribute lets you customize =
the
- persistence strategy used for the class. You can, for example, speci=
fy
- your own subclass of
- org.hibernate.persister.EntityPersister, or you c=
an
- 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 trig=
ger
- being called unnecessarily if you reattach a graph of detached insta=
nces
- 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, allow=
ing
- 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 m=
ade
- 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, althou=
gh
- 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:
-
<class name=3D"Summary">
<subselect>
select item.name, max(bid.amount), count(*)
@@ -699,10 +823,8 @@
...
</class>
=
- Declare the tables to synchronize this entity with, ensuring t=
hat
- auto-flush happens correctly and that queries against the derived en=
tity
- 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.
=
--===============2058346865533772690==--