[hibernate-commits] Hibernate SVN: r18941 - core/trunk/entitymanager/src/main/docbook/en/modules.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Mar 9 09:50:33 EST 2010
Author: epbernard
Date: 2010-03-09 09:50:32 -0500 (Tue, 09 Mar 2010)
New Revision: 18941
Modified:
core/trunk/entitymanager/src/main/docbook/en/modules/configuration.xml
core/trunk/entitymanager/src/main/docbook/en/modules/entitymanagerapi.xml
core/trunk/entitymanager/src/main/docbook/en/modules/query_criteria.xml
core/trunk/entitymanager/src/main/docbook/en/modules/transactions.xml
Log:
HHH-4933 improve EM doc wrt JPA 2
Modified: core/trunk/entitymanager/src/main/docbook/en/modules/configuration.xml
===================================================================
--- core/trunk/entitymanager/src/main/docbook/en/modules/configuration.xml 2010-03-09 14:49:39 UTC (rev 18940)
+++ core/trunk/entitymanager/src/main/docbook/en/modules/configuration.xml 2010-03-09 14:50:32 UTC (rev 18941)
@@ -67,7 +67,7 @@
<para>If you use Maven, add the following dependencies</para>
- <programlisting><project ...>
+ <programlisting role="XML" language="XML"><project ...>
...
<dependencies>
<dependency>
@@ -100,7 +100,7 @@
configuration, so by default, your persistence.xml will be quite
minimalist:</para>
- <programlisting><persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ <programlisting role="XML" language="XML"><persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="2.0">
@@ -116,7 +116,7 @@
<para>Here's a more complete example of a
<filename><literal>persistence.xml</literal></filename> file</para>
- <programlisting><persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ <programlisting role="XML" language="XML"><persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="2.0">
@@ -211,7 +211,7 @@
environment, the persistence.xml file is not under the same root
directory or jar than your domain model).</para>
- <programlisting> <jar-file>file:/home/turin/work/local/lab8/build/classes</jar-file></programlisting>
+ <programlisting role="XML" language="XML"> <jar-file>file:/home/turin/work/local/lab8/build/classes</jar-file></programlisting>
</listitem>
</varlistentry>
@@ -275,7 +275,7 @@
</listitem>
</itemizedlist>
- <para> See Hibernate Annotation's documentation for more
+ <para>See Hibernate Annotation's documentation for more
details.</para>
</listitem>
</varlistentry>
@@ -323,14 +323,14 @@
<literal><validation-mode></literal>. To use it, add a
regular property</para>
- <programlisting><property name="javax.persistence.validation.mode">
+ <programlisting role="XML" language="XML"><property name="javax.persistence.validation.mode">
ddl
</property></programlisting>
<para>With this approach, you can mix ddl and callback
modes:</para>
- <programlisting><property name="javax.persistence.validation.mode">
+ <programlisting role="XML" language="XML"><property name="javax.persistence.validation.mode">
ddl, callback
</property></programlisting>
</listitem>
@@ -427,7 +427,7 @@
the version embedded in the hibernate-entitymanager.jar. It won't fetch
the resource from the internet.</para>
- <programlisting><persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ <programlisting role="XML" language="XML"><persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="2.0"></programlisting>
@@ -441,7 +441,7 @@
<classname>EntityManager</classname>. The bootstrap class is
<classname>javax.persistence.Persistence</classname>, e.g.</para>
- <programlisting>EntityManagerFactory emf = Persistence.createEntityManagerFactory("manager1");
+ <programlisting role="JAVA" language="JAVA">EntityManagerFactory emf = Persistence.createEntityManagerFactory("manager1");
//or
@@ -528,8 +528,6 @@
reference documentation for a complete listing. There are however a
couple of properties available in the EJB3 provider only.</para>
- <para></para>
-
<table>
<title>Hibernate Entity Manager specific properties</title>
@@ -665,7 +663,7 @@
<para>Here is a typical configuration in a Java SE environment</para>
- <programlisting><persistence>
+ <programlisting role="XML" language="XML"><persistence>
<persistence-unit name="manager1" transaction-type="RESOURCE_LOCAL">
<class>org.hibernate.ejb.test.Cat</class>
<class>org.hibernate.ejb.test.Distributor</class>
@@ -697,7 +695,7 @@
<para>TODO: me more descriptive on some APIs like setDatasource()</para>
- <programlisting>Ejb3Configuration cfg = new Ejb3Configuration();
+ <programlisting role="JAVA" language="JAVA">Ejb3Configuration cfg = new Ejb3Configuration();
EntityManagerFactory emf =
cfg.addProperties( properties ) //add some properties
.setInterceptor( myInterceptorImpl ) // set an interceptor
@@ -714,9 +712,9 @@
<title>Event listeners</title>
<para>Hibernate Entity Manager needs to enhance Hibernate core to
- implements all the EJB3 semantics. It does that through the event listener
+ implements all the JPA semantics. It does that through the event listener
system of Hibernate. Be careful when you use the event system yourself,
- you might override some of the EJB3 semantics. A safe way is to add your
+ you might override some of the JPA semantics. A safe way is to add your
event listeners to the list given below.</para>
<table>
@@ -793,15 +791,13 @@
<row>
<entry>pre-insert</entry>
- <entry>org.hibernate.secure.JACCPreInsertEventListener,
- org.hibernate.valitator.event.ValidateEventListener</entry>
+ <entry>org.hibernate.secure.JACCPreInsertEventListener</entry>
</row>
<row>
<entry>pre-insert</entry>
- <entry>org.hibernate.secure.JACCPreUpdateEventListener,
- org.hibernate.valitator.event.ValidateEventListener</entry>
+ <entry>org.hibernate.secure.JACCPreUpdateEventListener</entry>
</row>
<row>
@@ -861,7 +857,7 @@
<classname>Persistence</classname> class is bootstrap class to create an
entity manager factory.</para>
- <programlisting>// Use persistence.xml configuration
+ <programlisting role="JAVA" language="JAVA">// Use persistence.xml configuration
EntityManagerFactory emf = Persistence.createEntityManagerFactory("manager1")
EntityManager em = emf.createEntityManager(); // Retrieve an application managed entity manager
// Work with the EM
@@ -896,4 +892,4 @@
be no performance cost. For more information on Hibernate Validator,
please refer to the Hibernate Annotations reference guide.</para>
</section>
-</chapter>
+</chapter>
\ No newline at end of file
Modified: core/trunk/entitymanager/src/main/docbook/en/modules/entitymanagerapi.xml
===================================================================
--- core/trunk/entitymanager/src/main/docbook/en/modules/entitymanagerapi.xml 2010-03-09 14:49:39 UTC (rev 18940)
+++ core/trunk/entitymanager/src/main/docbook/en/modules/entitymanagerapi.xml 2010-03-09 14:50:32 UTC (rev 18941)
@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
@@ -22,15 +22,15 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="objectstate">
<title>Working with objects</title>
<section>
<title>Entity states</title>
- <para>Like in Hibernate (comparable terms in parantheses), an entity
+ <para>Like in Hibernate (comparable terms in parentheses), an entity
instance is in one of the following states:</para>
<itemizedlist>
@@ -63,7 +63,7 @@
<para>The <classname>EntityManager</classname> API allows you to change
the state of an entity, or in other words, to load and store objects. You
- will find persistence with EJB3 easier to understand if you think about
+ will find persistence with JPA easier to understand if you think about
object state management, not managing of SQL statements.</para>
</section>
@@ -102,7 +102,8 @@
<para>In some cases, you don't really want to load the object state, but
just having a reference to it (ie a proxy). You can get this reference
using the <literal>getReference()</literal> method. This is especially
- useful to link a child to its parent without having to load the parent.</para>
+ useful to link a child to its parent without having to load the
+ parent.</para>
<programlisting>child = new Child();
child.SetName("Henry");
@@ -128,32 +129,33 @@
<para>If you don't know the identifier values of the objects you are
looking for, you need a query. The Hibernate EntityManager implementation
supports an easy-to-use but powerful object-oriented query language
- (EJB3-QL) which has been inspired by HQL (and vice-versa). Both query
- languages are portable across databases, the use entity and property names
- as identifiers (instead of table and column names). You may also express
- your query in the native SQL of your database, with optional support from
- EJB3 for result set conversion into Java business objects.</para>
+ (JP-QL) which has been inspired by HQL (and vice-versa). HQL is strictly
+ speaking a superset of JP-QL. Both query languages are portable across
+ databases, the use entity and property names as identifiers (instead of
+ table and column names). You may also express your query in the native SQL
+ of your database, with optional support from JPA for result set conversion
+ into Java business objects.</para>
<section>
<title>Executing queries</title>
- <para>EJB3QL and SQL queries are represented by an instance of
+ <para>JP-QL and SQL queries are represented by an instance of
<classname>javax.persistence.Query</classname>. This interface offers
methods for parameter binding, result set handling, and for execution of
the query. Queries are always created using the current entity
manager:</para>
- <programlisting>List cats = em.createQuery(
+ <programlisting>List<?> cats = em.createQuery(
"select cat from Cat as cat where cat.birthdate < ?1")
.setParameter(1, date, TemporalType.DATE)
.getResultList();
-List mothers = em.createQuery(
+List<?> mothers = em.createQuery(
"select mother from Cat as cat join cat.mother as mother where cat.name = ?1")
.setParameter(1, name)
.getResultList();
-List kittens = em.createQuery(
+List<?> kittens = em.createQuery(
"from Cat as cat where cat.mother = ?1")
.setEntity(1, pk)
.getResultList();
@@ -165,17 +167,43 @@
<para>A query is usually executed by invoking
<methodname>getResultList()</methodname>. This method loads the
- resulting instances of the query completly into memory. Entity instances
- retrieved by a query are in persistent state. The
+ resulting instances of the query completely into memory. Entity
+ instances retrieved by a query are in persistent state. The
<methodname>getSingleResult() </methodname>method offers a shortcut if
you know your query will only return a single object.</para>
+ <para>JPA 2 provides more type-safe approaches to queries. The truly
+ type-safe approach is the Criteria API explained in <xref
+ linkend="querycriteria" />.</para>
+
+ <programlisting>CriteriaQuery<Cat> criteria = builder.createQuery( Cat.class );
+Root<Cat> cat = criteria.from( Cat.class );
+criteria.select( cat );
+criteria.where( builder.lt( cat.get( Cat_.birthdate ), catDate ) );
+List<Cat> cats = em.createQuery( criteria ).getResultList(); //notice no downcasting is necessary</programlisting>
+
+ <para>But you can benefit form some type-safe convenience even when
+ using JP-QL (note that it's not as type-safe as the compiler has to
+ trust you with the return type.</para>
+
+ <programlisting>//No downcasting since we pass the return type
+List<Cat> cats = em.createQuery(
+ "select cat from Cat as cat where cat.birthdate < ?1", Cat.class)
+ .setParameter(1, date, TemporalType.DATE)
+ .getResultList();</programlisting>
+
+ <note>
+ <para>We highly recommend the Criteria API approach. While more
+ verbose, it provides compiler-enforced safety (including down to
+ property names) which will pay off when the application will move to
+ maintenance mode.</para>
+ </note>
+
<section>
<title>Projection</title>
- <para>An EJB3QL query queries can return tuples of objects if
- projection is used. Each result tuple is returned as an object
- array:</para>
+ <para>JPA queries can return tuples of objects if projection is used.
+ Each result tuple is returned as an object array:</para>
<programlisting>Iterator kittensAndMothers = sess.createQuery(
"select kitten, mother from Cat kitten join kitten.mother mother")
@@ -188,6 +216,11 @@
Cat mother = (Cat) tuple[1];
....
}</programlisting>
+
+ <note>
+ <para>The criteria API provides a type-safe approach to projection
+ results. Check out <xref linkend="querycriteria-tuple" />.</para>
+ </note>
</section>
<section>
@@ -220,9 +253,9 @@
<para>Both named and positional query parameters are supported, the
<literal>Query</literal> API offers several methods to bind arguments.
- The EJB3 specification numbers positional parameters from one. Named
+ The JPA specification numbers positional parameters from one. Named
parameters are identifiers of the form <literal>:paramname</literal>
- in the query string. Named parameters should be prefered, they are
+ in the query string. Named parameters should be preferred, they are
more robust and easier to read and understand:</para>
<programlisting>// Named parameter (preferred)
@@ -268,14 +301,21 @@
<programlisting>@javax.persistence.NamedQuery(name="eg.DomesticCat.by.name.and.minimum.weight",
query="select cat from eg.DomesticCat as cat where cat.name = ?1 and cat.weight > ?2")</programlisting>
- <para>Parameters are bound programatically to the named query, before
+ <para>Parameters are bound programmatically to the named query, before
it is executed:</para>
<programlisting>Query q = em.createNamedQuery("eg.DomesticCat.by.name.and.minimum.weight");
q.setString(1, name);
q.setInt(2, minWeight);
-List cats = q.getResultList();</programlisting>
+List<?> cats = q.getResultList();</programlisting>
+ <para>You can also use the slightly more type-safe approach:</para>
+
+ <programlisting>Query q = em.createNamedQuery("eg.DomesticCat.by.name.and.minimum.weight", Cat.class);
+q.setString(1, name);
+q.setInt(2, minWeight);
+List<Cat> cats = q.getResultList();</programlisting>
+
<para>Note that the actual program code is independent of the query
language that is used, you may also define native SQL queries in
metadata, or use Hibernate's native facilities by placing them in XML
@@ -315,6 +355,29 @@
</section>
<section>
+ <title>Query lock and flush mode</title>
+
+ <para>You can adjust the flush mode used when executing the query as
+ well as define the lock mode used to load the entities. </para>
+
+ <para>Adjusting the flush mode is interesting when one must guaranty
+ that a query execution will not trigger a flush operation. Most of the
+ time you don't need to care about this.</para>
+
+ <para>Adjusting the lock mode is useful if you need to lock the
+ objects returns by the query to a certain level.</para>
+
+ <programlisting>query.setFlushMode(FlushModeType.COMMIT)
+ .setLockMode(LockModeType.PESSIMISTIC_READ);</programlisting>
+
+ <note>
+ <para>If you want to use <literal>FlushMode.MANUAL</literal> (ie the
+ Hibernate specific flush mode), you will need to use a query hint.
+ See below.</para>
+ </note>
+ </section>
+
+ <section>
<title>Query hints</title>
<para>Query hints (for performance optimization, usually) are
@@ -395,7 +458,9 @@
<row>
<entry>org.hibernate.flushMode</entry>
- <entry>Flush mode used for this query</entry>
+ <entry>Flush mode used for this query (useful to pass
+ Hibernate specific flush modes, in particular
+ <literal>MANUAL</literal>).</entry>
</row>
<row>
@@ -438,6 +503,20 @@
</section>
<section>
+ <title>Detaching a object</title>
+
+ <para>An object when loaded in the persistence context is managed by
+ Hibernate. You can force an object to be detached (ie. no longer managed
+ by Hibernate) by closing the EntityManager or in a more fine-grained
+ approach by calling the <methodname>detach()</methodname> method.</para>
+
+ <programlisting>Cat cat = em.find( Cat.class, new Long(69) );
+...
+em.detach(cat);
+cat.setName("New name"); //not propatated to the database</programlisting>
+ </section>
+
+ <section>
<title>Modifying detached objects</title>
<para>Many applications need to retrieve an object in one transaction,
@@ -447,7 +526,7 @@
approach in a high-concurrency environment usually use versioned data to
ensure isolation for the "long" unit of work.</para>
- <para>The EJB3 specifications supports this development model by providing
+ <para>The JPA specifications supports this development model by providing
for persistence of modifications made to detached instances using the
<methodname>EntityManager.merge()</methodname> method:</para>
@@ -559,7 +638,7 @@
<note>
<title>Merging vs. saveOrUpdate/saveOrUpdateCopy</title>
- <para>Merging in EJB3 is similar to the
+ <para>Merging in JPA is similar to the
<literal>saveOrUpdateCopy()</literal> method in native Hibernate.
However, it is not the same as the <literal>saveOrUpdate()</literal>
method, the given instance is not reattached with the persistence
@@ -582,14 +661,15 @@
<section>
<title>Flush the persistence context</title>
+ <para>From time to time the entity manager will execute the SQL DML
+ statements needed to synchronize the data store with the state of objects
+ held in memory. This process is called flushing.</para>
+
<section>
<title>In a transaction</title>
- <para>From time to time the entity manager will execute the SQL DML
- statements needed to synchronize the data store with the state of
- objects held in memory. This process, flush, occurs by default (this is
- Hibernate specific and not defined by the specification) at the
- following points:</para>
+ <para>Flush occurs by default (this is Hibernate specific and not
+ defined by the specification) at the following points:</para>
<itemizedlist>
<listitem>
@@ -645,10 +725,10 @@
<para>(Exception: entity instances using application-assigned
identifiers are inserted when they are saved.)</para>
- <para>Except when you explicity <methodname>flush()</methodname>, there
- are absolutely no guarantees about when the entity manager executes the
- JDBC calls, only the order in which they are executed. However,
- Hibernate does guarantee that the
+ <para>Except when you explicitly <methodname>flush()</methodname>, there
+ are no guarantees about when the entity manager executes the JDBC calls,
+ only the order in which they are executed. However, Hibernate does
+ guarantee that the
<methodname>Query.getResultList()</methodname>/<methodname>Query.getSingleResult()</methodname>
will never return stale data; nor will they return wrong data if
executed in an active transaction.</para>
@@ -677,7 +757,8 @@
violates a constraint). TODO: Add link to exception handling.</para>
<para>Hibernate provides more flush modes than the one described in the
- EJB3 specification. Please refer to the Hibernate core reference
+ JPA specification. In particular <literal>FlushMode.MANUAL</literal> for
+ long running conversation. Please refer to the Hibernate core reference
documentation for more informations.</para>
</section>
@@ -730,9 +811,11 @@
<methodname>persist()</methodname>, <methodname>merge()</methodname>,
<methodname>remove()</methodname>, <methodname>refresh()</methodname> -
there is a corresponding cascade style. Respectively, the cascade styles
- are named PERSIST, MERGE, REMOVE, REFRESH. If you want an operation to be
- cascaded to associated entity (or collection of entities), you must
- indicate that in the association annotation:</para>
+ are named <literal>PERSIST</literal>, <literal>MERGE</literal>,
+ <literal>REMOVE</literal>, <literal>REFRESH</literal>,
+ <literal>DETACH</literal>. If you want an operation to be cascaded to
+ associated entity (or collection of entities), you must indicate that in
+ the association annotation:</para>
<programlisting>@OneToOne(cascade=CascadeType.PERSIST)</programlisting>
@@ -740,10 +823,17 @@
<programlisting>@OneToOne(cascade= { CascadeType.PERSIST, CascadeType.REMOVE, CascadeType.REFRESH } )</programlisting>
- <para>You may even use CascadeType.ALL to specify that all operations
- should be cascaded for a particular association. Remember that by default,
- no operation is cascaded.</para>
+ <para>You may even use <literal>CascadeType.ALL</literal> to specify that
+ all operations should be cascaded for a particular association. Remember
+ that by default, no operation is cascaded.</para>
+ <para>There is an additional cascading mode used to describe orphan
+ deletion (ie an object no longer linked to an owning object should be
+ removed automatically by Hibernate. Use
+ <literal>orphanRemoval=true</literal> on <classname>@OneToOne</classname>
+ or <classname>@OneToMany</classname>. Check Hibernate Annotations's
+ documentation for more information.</para>
+
<para>Hibernate offers more native cascading options, please refer to the
Hibernate Annotations manual and the Hibernate reference guide for more
informations.</para>
@@ -780,25 +870,58 @@
<section>
<title>Locking</title>
- <para>The default locking system in EJB3 is mostly based on optimistic
- locking (ie using a version column to check any concurrency issues). EJB3
- has defined an additional mechanism to increase the concurrency
- guaranties. You can apply a lock on a given entity (and it's associated
- entities if <literal>LOCK</literal> is cascaded) through the
- <methodname>lock(Object entity)</methodname> method. Depending on the
- concurrency guaranties you requires, you choose a lock mode:</para>
+ <para>You can define various levels of locking strategies. A lock can be
+ applied in several ways:</para>
<itemizedlist>
<listitem>
- <para><literal>LockMode.READ</literal> prevents dirty-reads and non
- repeatable read on a given entity.</para>
+ <para>via the explicit <methodname>entityManager.lock()</methodname>
+ method</para>
</listitem>
<listitem>
- <para><literal>LockMode.WRITE</literal> prevents dirty-reads and non
- repeatable read on a given entity and force an increase of the version
- number if any.</para>
+ <para>via lookup methods on <classname>EntityManager</classname>:
+ <literal>find()</literal>, <literal>refresh()</literal></para>
</listitem>
+
+ <listitem>
+ <para>on queries: <methodname>query.setLockMode()</methodname></para>
+ </listitem>
</itemizedlist>
+
+ <para>You can use various lock approaches:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>OPTIMISTIC</literal> (previously
+ <literal>READ</literal>): use an optimistic locking scheme where the
+ version number is compared: the version number is compared and has to
+ match before the transaction is committed.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>OPTIMISTIC_FORCE_INCREMENT</literal> (previously
+ <literal>WRITE</literal>): use an optimistic locking scheme but force
+ a version number increase as well: the version number is compared and
+ has to match before the transaction is committed.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>PESSIMISTIC_READ</literal>: apply a database-level read
+ lock when the lock operation is requested: roughly concurrent readers
+ are allowed but no writer is allowed.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>PESSIMISTIC_WRITE</literal>: apply a database-level
+ write lock when the lock operation is requested: roughly no reader nor
+ writer is allowed.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>All these locks prevent dirty reads and non-repeatable reads on a
+ given entity. Optimistic locks enforce the lock as late as possible hoping
+ nobody changes the data underneath while pessimistic locks enforce the
+ lock right away and keep it till the transaction is committed.</para>
</section>
-</chapter>
\ No newline at end of file
+</chapter>
Modified: core/trunk/entitymanager/src/main/docbook/en/modules/query_criteria.xml
===================================================================
--- core/trunk/entitymanager/src/main/docbook/en/modules/query_criteria.xml 2010-03-09 14:49:39 UTC (rev 18940)
+++ core/trunk/entitymanager/src/main/docbook/en/modules/query_criteria.xml 2010-03-09 14:50:32 UTC (rev 18941)
@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding='UTF-8'?>
+<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
@@ -22,300 +22,336 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
-
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="querycriteria">
- <title>Criteria Queries</title>
+ <title>Criteria Queries</title>
- <para>
- Criteria queries are a programmatic, type-safe way to express a query. They are type-safe
- in terms of using interfaces and classes to represent various structural parts of a query
- such as the query itself, or the select clause, or an order-by, etc. They can also be
- type-safe in terms of referencing attributes as we will see in a bit. Users of the older
- Hibernate <interfacename>org.hibernate.Criteria</interfacename> query API will recognize
- the general approach, though we believe the JPA API to be superior as it represents a clean
- look at the lessons learned from that API.
- </para>
+ <para>Criteria queries are a programmatic, type-safe way to express a query.
+ They are type-safe in terms of using interfaces and classes to represent
+ various structural parts of a query such as the query itself, or the select
+ clause, or an order-by, etc. They can also be type-safe in terms of
+ referencing attributes as we will see in a bit. Users of the older Hibernate
+ <interfacename>org.hibernate.Criteria</interfacename> query API will
+ recognize the general approach, though we believe the JPA API to be superior
+ as it represents a clean look at the lessons learned from that API.</para>
- <para>
- Criteria queries are essentially an object graph, where each part of the graph represents an increasing
- (as we navigate down this graph) more atomic part of query. The first step in performing a criteria query
- is building this graph. The <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
- interface is the first thing with which you need to become acquainted to begin using criteria queries. Its
- role is that of a factory for all the individual pieces of the criteria. You obtain a
- <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename> instance by calling the
- <methodname>getCriteriaBuilder</methodname> method of the
- <interfacename>javax.persistence.EntityManagerFactory</interfacename>
- </para>
+ <para>Criteria queries are essentially an object graph, where each part of
+ the graph represents an increasing (as we navigate down this graph) more
+ atomic part of query. The first step in performing a criteria query is
+ building this graph. The
+ <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
+ interface is the first thing with which you need to become acquainted to
+ begin using criteria queries. Its role is that of a factory for all the
+ individual pieces of the criteria. You obtain a
+ <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
+ instance by calling the <methodname>getCriteriaBuilder</methodname> method
+ of the
+ <interfacename>javax.persistence.EntityManagerFactory</interfacename></para>
- <programlisting>CriteriaBuilder builder = entityManagerFactory.getCriteriaBuilder();</programlisting>
+ <programlisting>CriteriaBuilder builder = entityManagerFactory.getCriteriaBuilder();</programlisting>
- <para>
- The next step is to obtain a <interfacename>javax.persistence.criteria.CriteriaQuery</interfacename>.
- You do this by one of the 3 methods on <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
- for this puropse.
- </para>
+ <para>The next step is to obtain a
+ <interfacename>javax.persistence.criteria.CriteriaQuery</interfacename>. You
+ do this by one of the 3 methods on
+ <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
+ for this purpose.</para>
- <programlisting><![CDATA[CriteriaQuery<T> createQuery(Class<T>)]]></programlisting>
- <programlisting><![CDATA[CriteriaQuery<Tuple> createTupleQuery()]]></programlisting>
- <programlisting><![CDATA[CriteriaQuery<Object> createQuery()]]></programlisting>
+ <programlisting>CriteriaQuery<T> createQuery(Class<T>)</programlisting>
- <para>
- Each serves a different purpose depending on the expected type of the query results.
- </para>
+ <programlisting>CriteriaQuery<Tuple> createTupleQuery()</programlisting>
- <note>
- <para>
- <citetitle pubwork="chapter">Chapter 6 Criteria API</citetitle> of the <citation><xref linkend="JPA2"/></citation>
- already contains a decent amount of reference material pertaining to the various parts of a criteria query.
- So rather than duplicate all that content here, lets instead look at some of the more widely anticipated
- usages of the API.
- </para>
- </note>
+ <programlisting>CriteriaQuery<Object> createQuery()</programlisting>
- <section id="querycriteria-typedquery">
- <title>Typed criteria queries</title>
- <programlisting><![CDATA[CriteriaQuery<T> createQuery(Class<T>)]]></programlisting>
- <para>
- The type of the criteria query (aka the <T>) indicates the expected types in the
- query result. This might be an entity, an Integer, or any other object.
- </para>
+ <para>Each serves a different purpose depending on the expected type of the
+ query results.</para>
- <section id="querycriteria-typedquery-entity">
- <title>Selecting an entity</title>
- <para>
- This the most used form of query in Hibernate Query Language (HQL) and Hibernate Criteria Queries.
- You have an entity and you want to select one or more of that entity based on some condition.
- </para>
- <example id="ex-criteria-typedquery-entity">
- <title>Selecting the root entity</title>
- <programlistingco role="JAVA">
- <areaspec>
- <areaset id="ex.criteria.typedquery.entity.1" coords="">
- <area id="ex.criteria.typedquery.entity.1.c1" coords='1'/>
- <area id="ex.criteria.typedquery.entity.1.c2" coords='6'/>
- </areaset>
- <area id="ex.criteria.typedquery.entity.2" coords="3" />
- <area id="ex.criteria.typedquery.entity.3" coords="4" />
- </areaspec>
- <programlisting><![CDATA[CriteriaQuery<Person> criteria = builder.createQuery( Person.class );
-Root<Person> personRoot = criteria.from( Person.class );
+ <note>
+ <para><citetitle pubwork="chapter">Chapter 6 Criteria API</citetitle> of
+ the <citation><xref linkend="JPA2" /></citation> already contains a decent
+ amount of reference material pertaining to the various parts of a criteria
+ query. So rather than duplicate all that content here, lets instead look
+ at some of the more widely anticipated usages of the API.</para>
+ </note>
+
+ <section id="querycriteria-typedquery">
+ <title>Typed criteria queries</title>
+
+ <programlisting>CriteriaQuery<T> createQuery(Class<T>)</programlisting>
+
+ <para>The type of the criteria query (aka the <T>) indicates the
+ expected types in the query result. This might be an entity, an Integer,
+ or any other object.</para>
+
+ <section id="querycriteria-typedquery-entity">
+ <title>Selecting an entity</title>
+
+ <para>This the most used form of query in Hibernate Query Language (HQL)
+ and Hibernate Criteria Queries. You have an entity and you want to
+ select one or more of that entity based on some condition.</para>
+
+ <example id="ex-criteria-typedquery-entity">
+ <title>Selecting the root entity</title>
+
+ <programlistingco role="JAVA">
+ <areaspec>
+ <areaset coords="" id="ex.criteria.typedquery.entity.1">
+ <area coords="1" id="ex.criteria.typedquery.entity.1.c1" />
+
+ <area coords="6" id="ex.criteria.typedquery.entity.1.c2" />
+ </areaset>
+
+ <area coords="3" id="ex.criteria.typedquery.entity.2" />
+
+ <area coords="4" id="ex.criteria.typedquery.entity.3" />
+ </areaspec>
+
+ <programlisting>CriteriaQuery<Person> criteria = builder.createQuery( Person.class );
+Root<Person> personRoot = criteria.from( Person.class );
criteria.select( personRoot );
criteria.where( builder.equal( personRoot.get( Person_.eyeColor ), "brown" ) );
-List<Person> people = em.createQuery( criteria ).getResultList();
-for ( Person person : people ) { ... }]]></programlisting>
- </programlistingco>
- <calloutlist>
- <callout arearefs="ex.criteria.typedquery.entity.1">
- <para>
- We use the form <emphasis>createQuery( Person.class )</emphasis>
- here because the expected returns are in fact Person entities as we see when we
- begin processing the results.
- </para>
- </callout>
- <callout arearefs="ex.criteria.typedquery.entity.2">
- <para>
- <emphasis>personCriteria.select( personRoot )</emphasis> here is completely
- unneeded in this specific case because of the fact that <emphasis>personRoot</emphasis>
- will be the implied selection since we have only a single root. It was done here only
- for completeness of an example
- </para>
- </callout>
- <callout arearefs="ex.criteria.typedquery.entity.3">
- <para>
- <emphasis>Person_.eyeColor</emphasis> is an example of the static form of metamodel
- reference. We will use that form exclusively in this chapter.
- See <xref linkend="metamodel-static"/> for details.
- </para>
- </callout>
- </calloutlist>
- </example>
- </section>
+List<Person> people = em.createQuery( criteria ).getResultList();
+for ( Person person : people ) { ... }</programlisting>
+ </programlistingco>
- <section id="querycriteria-typedquery-expression">
- <title>Selecting a value</title>
- <para>
- The simplest form of selecting a value is selecting a particular attribute from an entity. But
- this might also be an aggregation, a mathematical operation, etc.
- </para>
- <example id="ex-criteria-typedquery-attribute">
- <title>Selecting an attribute</title>
- <programlistingco role="JAVA">
- <areaspec>
- <areaset id="ex.criteria.typedquery.attr.1" coords="">
- <area id="ex.criteria.typedquery.attr.1.c1" coords='1'/>
- <area id="ex.criteria.typedquery.attr.1.c2" coords='5'/>
- </areaset>
- <area id="ex.criteria.typedquery.attr.2" coords="3" />
- </areaspec>
- <programlisting><![CDATA[CriteriaQuery<Integer> criteria = builder.createQuery( Integer.class );
-Root<Person> personRoot = criteria.from( Person.class );
+ <calloutlist>
+ <callout arearefs="ex.criteria.typedquery.entity.1">
+ <para>We use the form <emphasis>createQuery( Person.class
+ )</emphasis> here because the expected returns are in fact Person
+ entities as we see when we begin processing the results.</para>
+ </callout>
+
+ <callout arearefs="ex.criteria.typedquery.entity.2">
+ <para><emphasis>personCriteria.select( personRoot )</emphasis>
+ here is completely unneeded in this specific case because of the
+ fact that <emphasis>personRoot</emphasis> will be the implied
+ selection since we have only a single root. It was done here only
+ for completeness of an example</para>
+ </callout>
+
+ <callout arearefs="ex.criteria.typedquery.entity.3">
+ <para><emphasis>Person_.eyeColor</emphasis> is an example of the
+ static form of metamodel reference. We will use that form
+ exclusively in this chapter. See <xref
+ linkend="metamodel-static" /> for details.</para>
+ </callout>
+ </calloutlist>
+ </example>
+ </section>
+
+ <section id="querycriteria-typedquery-expression">
+ <title>Selecting a value</title>
+
+ <para>The simplest form of selecting a value is selecting a particular
+ attribute from an entity. But this might also be an aggregation, a
+ mathematical operation, etc.</para>
+
+ <example id="ex-criteria-typedquery-attribute">
+ <title>Selecting an attribute</title>
+
+ <programlistingco role="JAVA">
+ <areaspec>
+ <areaset coords="" id="ex.criteria.typedquery.attr.1">
+ <area coords="1" id="ex.criteria.typedquery.attr.1.c1" />
+
+ <area coords="5" id="ex.criteria.typedquery.attr.1.c2" />
+ </areaset>
+
+ <area coords="3" id="ex.criteria.typedquery.attr.2" />
+ </areaspec>
+
+ <programlisting>CriteriaQuery<Integer> criteria = builder.createQuery( Integer.class );
+Root<Person> personRoot = criteria.from( Person.class );
criteria.select( personRoot.get( Person_.age ) );
criteria.where( builder.equal( personRoot.get( Person_.eyeColor ), "brown" ) );
-List<Integer> ages = em.createQuery( criteria ).getResultList();
-for ( Integer age : ages ) { ... } ]]></programlisting>
- </programlistingco>
- <calloutlist>
- <callout arearefs="ex.criteria.typedquery.attr.1">
- <para>
- Notice again the typing of the query based on the anticipated result type(s). Here
- we are specifying <classname>java.lang.Integer</classname> as the type of the
- <emphasis>Person#age</emphasis> attribute is <classname>java.lang.Integer</classname>.
- </para>
- </callout>
- <callout arearefs="ex.criteria.typedquery.attr.2">
- <para>
- We need to bind the fact that we are interested in the age associated with the
- <emphasis>personRoot</emphasis>. We might have multiple references to the Person
- entity in the query so we need to identify (aka qualify) which
- <emphasis>Person#age</emphasis> we mean.
- </para>
- </callout>
- </calloutlist>
- </example>
- <example id="ex-criteria-typedquery-expression">
- <title>Selecting an expression</title>
- <programlistingco role="JAVA">
- <areaspec>
- <area id="ex.criteria.typedquery.expr.1" coords="3" />
- </areaspec>
- <programlisting><![CDATA[CriteriaQuery<Integer> criteria = builder.createQuery( Integer.class );
-Root<Person> personRoot = criteria.from( Person.class );
+List<Integer> ages = em.createQuery( criteria ).getResultList();
+for ( Integer age : ages ) { ... } </programlisting>
+ </programlistingco>
+
+ <calloutlist>
+ <callout arearefs="ex.criteria.typedquery.attr.1">
+ <para>Notice again the typing of the query based on the
+ anticipated result type(s). Here we are specifying
+ <classname>java.lang.Integer</classname> as the type of the
+ <emphasis>Person#age</emphasis> attribute is
+ <classname>java.lang.Integer</classname>.</para>
+ </callout>
+
+ <callout arearefs="ex.criteria.typedquery.attr.2">
+ <para>We need to bind the fact that we are interested in the age
+ associated with the <emphasis>personRoot</emphasis>. We might have
+ multiple references to the Person entity in the query so we need
+ to identify (aka qualify) which <emphasis>Person#age</emphasis> we
+ mean.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <example id="ex-criteria-typedquery-expression">
+ <title>Selecting an expression</title>
+
+ <programlistingco role="JAVA">
+ <areaspec>
+ <area coords="3" id="ex.criteria.typedquery.expr.1" />
+ </areaspec>
+
+ <programlisting>CriteriaQuery<Integer> criteria = builder.createQuery( Integer.class );
+Root<Person> personRoot = criteria.from( Person.class );
criteria.select( builder.max( personRoot.get( Person_.age ) ) );
criteria.where( builder.equal( personRoot.get( Person_.eyeColor ), "brown" ) );
-Integer maxAge = em.createQuery( criteria ).getSingleResult();]]></programlisting>
- </programlistingco>
- <calloutlist>
- <callout arearefs="ex.criteria.typedquery.expr.1">
- <para>
- Here we see <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
- used to obtain a <emphasis>MAX</emphasis> expression. These expression building
- methods return <interfacename>javax.persistence.criteria.Expression</interfacename>
- instances typed according to various rules. The rule for a <emphasis>MAX</emphasis>
- expression is that the expression type is the same as that of the underlying attribute.
- </para>
- </callout>
- </calloutlist>
- </example>
- </section>
+Integer maxAge = em.createQuery( criteria ).getSingleResult();</programlisting>
+ </programlistingco>
- <section id="querycriteria-typedquery-multiselect">
- <title>Selecting multiple values</title>
- <para>
- There are actually a few different ways to select multiple values using criteria queries. We will
- explore 2 options here, but an alternative recommended approach is to use tuples as
- described in <xref linkend="querycriteria-tuple"/>
- </para>
- <example id="ex-criteria-typedquery-array">
- <title>Selecting an array</title>
- <programlistingco role="JAVA">
- <areaspec>
- <areaset id="ex.criteria.typedquery.array.1" coords="">
- <area id="ex.criteria.typedquery.array.1.c1" coords='1'/>
- <area id="ex.criteria.typedquery.array.1.c2" coords='7'/>
- </areaset>
- <area id="ex.criteria.typedquery.array.2" coords="5" />
- </areaspec>
- <programlisting><![CDATA[CriteriaQuery<Object[]> criteria = builder.createQuery( Object[].class );
-Root<Person> personRoot = criteria.from( Person.class );
-Path<Long> idPath = personRoot.get( Person_.id );
-Path<Integer> agePath = personRoot.get( Person_.age );
+ <calloutlist>
+ <callout arearefs="ex.criteria.typedquery.expr.1">
+ <para>Here we see
+ <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
+ used to obtain a <emphasis>MAX</emphasis> expression. These
+ expression building methods return
+ <interfacename>javax.persistence.criteria.Expression</interfacename>
+ instances typed according to various rules. The rule for a
+ <emphasis>MAX</emphasis> expression is that the expression type is
+ the same as that of the underlying attribute.</para>
+ </callout>
+ </calloutlist>
+ </example>
+ </section>
+
+ <section id="querycriteria-typedquery-multiselect">
+ <title>Selecting multiple values</title>
+
+ <para>There are actually a few different ways to select multiple values
+ using criteria queries. We will explore 2 options here, but an
+ alternative recommended approach is to use tuples as described in <xref
+ linkend="querycriteria-tuple" /></para>
+
+ <example id="ex-criteria-typedquery-array">
+ <title>Selecting an array</title>
+
+ <programlistingco role="JAVA">
+ <areaspec>
+ <areaset coords="" id="ex.criteria.typedquery.array.1">
+ <area coords="1" id="ex.criteria.typedquery.array.1.c1" />
+
+ <area coords="7" id="ex.criteria.typedquery.array.1.c2" />
+ </areaset>
+
+ <area coords="5" id="ex.criteria.typedquery.array.2" />
+ </areaspec>
+
+ <programlisting>CriteriaQuery<Object[]> criteria = builder.createQuery( Object[].class );
+Root<Person> personRoot = criteria.from( Person.class );
+Path<Long> idPath = personRoot.get( Person_.id );
+Path<Integer> agePath = personRoot.get( Person_.age );
criteria.select( builder.array( idPath, agePath ) );
criteria.where( builder.equal( personRoot.get( Person_.eyeColor ), "brown" ) );
-List<Object[]> valueArray = em.createQuery( criteria ).getResultList();
+List<Object[]> valueArray = em.createQuery( criteria ).getResultList();
for ( Object[] values : valueArray ) {
final Long id = (Long) values[0];
final Integer age = (Integer) values[1];
...
-}]]></programlisting>
- </programlistingco>
- <calloutlist>
- <callout arearefs="ex.criteria.typedquery.array.1">
- <para>
- Technically this is classified as a typed query, but as you can see in handling the
- results that is sort of misleading. Anyway, the expected result type here is an
- array.
- </para>
- </callout>
- <callout arearefs="ex.criteria.typedquery.array.2">
- <para>
- Here we see the use of the <methodname>array</methodname> method of the
- <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename> which
- explicitly combines individual selections into a
- <interfacename>javax.persistence.criteria.CompoundSelection</interfacename>.
- </para>
- </callout>
- </calloutlist>
- </example>
- <example id="ex-criteria-typedquery-array2">
- <title>Selecting an array (2)</title>
- <programlistingco role="JAVA">
- <areaspec>
- <areaset id="ex.criteria.typedquery.array2.1" coords="">
- <area id="ex.criteria.typedquery.array2.1.c1" coords='1'/>
- <area id="ex.criteria.typedquery.array2.1.c2" coords='7'/>
- </areaset>
- <area id="ex.criteria.typedquery.array2.2" coords="5" />
- </areaspec>
- <programlisting><![CDATA[CriteriaQuery<Object[]> criteria = builder.createQuery( Object[].class );
-Root<Person> personRoot = criteria.from( Person.class );
-Path<Long> idPath = personRoot.get( Person_.id );
-Path<Integer> agePath = personRoot.get( Person_.age );
+}</programlisting>
+ </programlistingco>
+
+ <calloutlist>
+ <callout arearefs="ex.criteria.typedquery.array.1">
+ <para>Technically this is classified as a typed query, but as you
+ can see in handling the results that is sort of misleading.
+ Anyway, the expected result type here is an array.</para>
+ </callout>
+
+ <callout arearefs="ex.criteria.typedquery.array.2">
+ <para>Here we see the use of the <methodname>array</methodname>
+ method of the
+ <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
+ which explicitly combines individual selections into a
+ <interfacename>javax.persistence.criteria.CompoundSelection</interfacename>.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <example id="ex-criteria-typedquery-array2">
+ <title>Selecting an array (2)</title>
+
+ <programlistingco role="JAVA">
+ <areaspec>
+ <areaset coords="" id="ex.criteria.typedquery.array2.1">
+ <area coords="1" id="ex.criteria.typedquery.array2.1.c1" />
+
+ <area coords="7" id="ex.criteria.typedquery.array2.1.c2" />
+ </areaset>
+
+ <area coords="5" id="ex.criteria.typedquery.array2.2" />
+ </areaspec>
+
+ <programlisting>CriteriaQuery<Object[]> criteria = builder.createQuery( Object[].class );
+Root<Person> personRoot = criteria.from( Person.class );
+Path<Long> idPath = personRoot.get( Person_.id );
+Path<Integer> agePath = personRoot.get( Person_.age );
criteria.multiselect( idPath, agePath );
criteria.where( builder.equal( personRoot.get( Person_.eyeColor ), "brown" ) );
-List<Object[]> valueArray = em.createQuery( criteria ).getResultList();
+List<Object[]> valueArray = em.createQuery( criteria ).getResultList();
for ( Object[] values : valueArray ) {
final Long id = (Long) values[0];
final Integer age = (Integer) values[1];
...
-} ]]></programlisting>
- </programlistingco>
- <calloutlist>
- <callout arearefs="ex.criteria.typedquery.array2.1">
- <para>
- Just as we saw in <xref linkend="ex-criteria-typedquery-array"/> we have
- a "typed" criteria query returning an Object array.
- </para>
- </callout>
- <callout arearefs="ex.criteria.typedquery.array2.2">
- <para>
- This actually functions exactly the same as what we saw in
- <xref linkend="ex-criteria-typedquery-array"/>. The <methodname>multiselect</methodname>
- method behaves slightly differently based on the type given when the criteria query
- was first built, but in this case it says to select and return an
- <emphasis>Object[]</emphasis>.
- </para>
- </callout>
- </calloutlist>
- </example>
- </section>
+} </programlisting>
+ </programlistingco>
- <section id="querycriteria-typedquery-construct">
- <title>Selecting a wrapper</title>
- <para>
- Another alternative to <xref linkend="querycriteria-typedquery-multiselect"/> is to instead select
- an object that will "wrap" the multiple values. Going back to the example query there, rather than
- returning an array of <emphasis>[Person#id, Person#age]</emphasis> instead declare a class
- that holds these values and instead return that.
- </para>
- <example id="ex-criteria-typedquery-construct">
- <title>Selecting an wrapper</title>
- <programlistingco role="JAVA">
- <areaspec>
- <areaset id="ex.criteria.typedquery.construct.1" coords="" >
- <area id="ex.criteria.typedquery.construct.1.c1" coords="1" />
- <area id="ex.criteria.typedquery.construct.1.c2" coords="4" />
- </areaset>
- <areaset id="ex.criteria.typedquery.construct.2" coords="">
- <area id="ex.criteria.typedquery.construct.2.c1" coords='11'/>
- <area id="ex.criteria.typedquery.construct.2.c2" coords='21'/>
- </areaset>
- <areaset id="ex.criteria.typedquery.construct.3" coords="" >
- <area id="ex.criteria.typedquery.construct.3.c1" coords="13" />
- <area id="ex.criteria.typedquery.construct.3.c2" coords="14" />
- </areaset>
- </areaspec>
- <programlisting><![CDATA[public class PersonWrapper {
+ <calloutlist>
+ <callout arearefs="ex.criteria.typedquery.array2.1">
+ <para>Just as we saw in <xref
+ linkend="ex-criteria-typedquery-array" /> we have a "typed"
+ criteria query returning an Object array.</para>
+ </callout>
+
+ <callout arearefs="ex.criteria.typedquery.array2.2">
+ <para>This actually functions exactly the same as what we saw in
+ <xref linkend="ex-criteria-typedquery-array" />. The
+ <methodname>multiselect</methodname> method behaves slightly
+ differently based on the type given when the criteria query was
+ first built, but in this case it says to select and return an
+ <emphasis>Object[]</emphasis>.</para>
+ </callout>
+ </calloutlist>
+ </example>
+ </section>
+
+ <section id="querycriteria-typedquery-construct">
+ <title>Selecting a wrapper</title>
+
+ <para>Another alternative to <xref
+ linkend="querycriteria-typedquery-multiselect" /> is to instead select
+ an object that will "wrap" the multiple values. Going back to the
+ example query there, rather than returning an array of
+ <emphasis>[Person#id, Person#age]</emphasis> instead declare a class
+ that holds these values and instead return that.</para>
+
+ <example id="ex-criteria-typedquery-construct">
+ <title>Selecting an wrapper</title>
+
+ <programlistingco role="JAVA">
+ <areaspec>
+ <areaset coords="" id="ex.criteria.typedquery.construct.1">
+ <area coords="1" id="ex.criteria.typedquery.construct.1.c1" />
+
+ <area coords="4" id="ex.criteria.typedquery.construct.1.c2" />
+ </areaset>
+
+ <areaset coords="" id="ex.criteria.typedquery.construct.2">
+ <area coords="11" id="ex.criteria.typedquery.construct.2.c1" />
+
+ <area coords="21" id="ex.criteria.typedquery.construct.2.c2" />
+ </areaset>
+
+ <areaset coords="" id="ex.criteria.typedquery.construct.3">
+ <area coords="13" id="ex.criteria.typedquery.construct.3.c1" />
+
+ <area coords="14" id="ex.criteria.typedquery.construct.3.c2" />
+ </areaset>
+ </areaspec>
+
+ <programlisting>public class PersonWrapper {
private final Long id;
private final Integer age;
public PersonWrapper(Long id, Integer age) {
@@ -325,8 +361,8 @@
...
}
...
-CriteriaQuery<PersonWrapper> criteria = builder.createQuery( PersonWrapper.class );
-Root<Person> personRoot = criteria.from( Person.class );
+CriteriaQuery<PersonWrapper> criteria = builder.createQuery( PersonWrapper.class );
+Root<Person> personRoot = criteria.from( Person.class );
criteria.select(
builder.construct(
PersonWrapper.class,
@@ -335,201 +371,231 @@
)
);
criteria.where( builder.equal( personRoot.get( Person_.eyeColor ), "brown" ) );
-List<PersonWrapper> people = em.createQuery( criteria ).getResultList();
-for ( PersonWrapper person : people ) { ... }]]></programlisting>
- </programlistingco>
- <calloutlist>
- <callout arearefs="ex.criteria.typedquery.construct.1">
- <para>
- First we see the simple definition of the wrapper object we will be using to
- wrap our result values. Specifically notice the constructor and its argument types.
- </para>
- </callout>
- <callout arearefs="ex.criteria.typedquery.construct.2">
- <para>
- Since we will be returning <emphasis>PersonWrapper</emphasis> objects, we
- use <emphasis>PersonWrapper</emphasis> as the type of our criteria query.
- </para>
- </callout>
- <callout arearefs="ex.criteria.typedquery.construct.3">
- <para>
- Here we see another new <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
- method, <methodname>construct</methodname>, which is used to builder a wrapper
- expression. Basically for every row in the result we are saying we would like
- a <emphasis>PersonWrapper</emphasis> instantiated by the matching constructor. This
- wrapper expression is then passed as the select.
- </para>
- </callout>
- </calloutlist>
- </example>
- </section>
+List<PersonWrapper> people = em.createQuery( criteria ).getResultList();
+for ( PersonWrapper person : people ) { ... }</programlisting>
+ </programlistingco>
+ <calloutlist>
+ <callout arearefs="ex.criteria.typedquery.construct.1">
+ <para>First we see the simple definition of the wrapper object we
+ will be using to wrap our result values. Specifically notice the
+ constructor and its argument types.</para>
+ </callout>
+
+ <callout arearefs="ex.criteria.typedquery.construct.2">
+ <para>Since we will be returning
+ <emphasis>PersonWrapper</emphasis> objects, we use
+ <emphasis>PersonWrapper</emphasis> as the type of our criteria
+ query.</para>
+ </callout>
+
+ <callout arearefs="ex.criteria.typedquery.construct.3">
+ <para>Here we see another new
+ <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
+ method, <methodname>construct</methodname>, which is used to
+ builder a wrapper expression. Basically for every row in the
+ result we are saying we would like a
+ <emphasis>PersonWrapper</emphasis> instantiated by the matching
+ constructor. This wrapper expression is then passed as the
+ select.</para>
+ </callout>
+ </calloutlist>
+ </example>
</section>
+ </section>
- <section id="querycriteria-tuple">
- <title>Tuple criteria queries</title>
- <para>
- A better approach to <xref linkend="querycriteria-typedquery-multiselect"/> is to either use
- a wrapper (which we just saw in <xref linkend="querycriteria-typedquery-construct"/>) or using
- the <interfacename>javax.persistence.Tuple</interfacename> contract.
- </para>
+ <section id="querycriteria-tuple">
+ <title>Tuple criteria queries</title>
- <example id="ex-criteria-typedquery-tuple">
- <title>Selecting a tuple</title>
- <programlistingco role="JAVA">
- <areaspec>
- <areaset id="ex.criteria.typedquery.tuple.1" coords="">
- <area id="ex.criteria.typedquery.tuple.1.c1" coords='1'/>
- <area id="ex.criteria.typedquery.tuple.1.c2" coords='7'/>
- </areaset>
- <area id="ex.criteria.typedquery.tuple.2" coords="5" />
- <areaset id="ex.criteria.typedquery.tuple.3" coords="">
- <area id="ex.criteria.typedquery.tuple.3.c1" coords='9'/>
- <area id="ex.criteria.typedquery.tuple.3.c2" coords='10'/>
- </areaset>
- </areaspec>
- <programlisting><![CDATA[CriteriaQuery<Tuple> criteria = builder.createTupleQuery();
-Root<Person> personRoot = criteria.from( Person.class );
-Path<Long> idPath = personRoot.get( Person_.id );
-Path<Integer> agePath = personRoot.get( Person_.age );
+ <para>A better approach to <xref
+ linkend="querycriteria-typedquery-multiselect" /> is to either use a
+ wrapper (which we just saw in <xref
+ linkend="querycriteria-typedquery-construct" />) or using the
+ <interfacename>javax.persistence.Tuple</interfacename> contract.</para>
+
+ <example id="ex-criteria-typedquery-tuple">
+ <title>Selecting a tuple</title>
+
+ <programlistingco role="JAVA">
+ <areaspec>
+ <areaset coords="" id="ex.criteria.typedquery.tuple.1">
+ <area coords="1" id="ex.criteria.typedquery.tuple.1.c1" />
+
+ <area coords="7" id="ex.criteria.typedquery.tuple.1.c2" />
+ </areaset>
+
+ <area coords="5" id="ex.criteria.typedquery.tuple.2" />
+
+ <areaset coords="" id="ex.criteria.typedquery.tuple.3">
+ <area coords="9" id="ex.criteria.typedquery.tuple.3.c1" />
+
+ <area coords="10" id="ex.criteria.typedquery.tuple.3.c2" />
+ </areaset>
+ </areaspec>
+
+ <programlisting>CriteriaQuery<Tuple> criteria = builder.createTupleQuery();
+Root<Person> personRoot = criteria.from( Person.class );
+Path<Long> idPath = personRoot.get( Person_.id );
+Path<Integer> agePath = personRoot.get( Person_.age );
criteria.multiselect( idPath, agePath );
criteria.where( builder.equal( personRoot.get( Person_.eyeColor ), "brown" ) );
-List<Tuple> tuples = em.createQuery( criteria ).getResultList();
+List<Tuple> tuples = em.createQuery( criteria ).getResultList();
for ( Tuple tuple : valueArray ) {
assert tuple.get( 0 ) == tuple.get( idPath );
assert tuple.get( 1 ) == tuple.get( agePath );
...
-} ]]></programlisting>
- </programlistingco>
- <calloutlist>
- <callout arearefs="ex.criteria.typedquery.tuple.1">
- <para>
- Here we see the use of a new <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
- <interfacename>javax.persistence.criteria.CriteriaQuery</interfacename> building method,
- <methodname>createTupleQuery</methodname>. This is exactly equivalent to calling
- <emphasis>builder.createQuery( Tuple.class )</emphasis>. It signifies that we want
- to access the results through the <interfacename>javax.persistence.Tuple</interfacename> contract.
- </para>
- </callout>
- <callout arearefs="ex.criteria.typedquery.tuple.2">
- <para>
- Again we see the use of the <methodname>multiselect</methodname> method, just like
- in <xref linkend="ex-criteria-typedquery-array2"/>. The difference here is that the
- type of the <interfacename>javax.persistence.criteria.CriteriaQuery</interfacename> was defined
- as <interfacename>javax.persistence.Tuple</interfacename> so the compound selections in
- this case are interpreted to be the tuple elements.
- </para>
- </callout>
- <callout arearefs="ex.criteria.typedquery.tuple.3">
- <para>
- Here we see <interfacename>javax.persistence.Tuple</interfacename> allowing different types of
- access to the results, which we will expand on next.
- </para>
- </callout>
- </calloutlist>
- </example>
+} </programlisting>
+ </programlistingco>
- <section id="querycriteria-tuple-access">
- <title>Accessing tuple elements</title>
- <para>
- The <interfacename>javax.persistence.Tuple</interfacename> contract provides 3 basic forms of
- access to the underlying elements:
- </para>
- <variablelist>
- <varlistentry>
- <term>typed</term>
- <listitem>
- <programlisting><![CDATA[<X> X get(TupleElement<X> tupleElement)]]></programlisting>
- <para>
- This allows typed access to the underlying tuple elements. We see this in
- <xref linkend="ex-criteria-typedquery-tuple"/> in the <emphasis>tuple.get( idPath )</emphasis>
- and <emphasis>tuple.get( agePath )</emphasis> calls. Just about everything is a
- <interfacename>javax.persistence.TupleElement</interfacename>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>positional</term>
- <listitem>
- <programlisting><![CDATA[Object get(int i)]]></programlisting>
- <programlisting><![CDATA[<X> X get(int i, Class<X> type)]]></programlisting>
- <para>
- Very similar to what we saw in <xref linkend="ex-criteria-typedquery-array"/> and
- <xref linkend="ex-criteria-typedquery-array2"/> in terms of positional access. Only the
- second form here provides typing, because the user explicitly provides the typing
- on access. We see this in <xref linkend="ex-criteria-typedquery-tuple"/> in
- the <emphasis>tuple.get( 0 )</emphasis> and <emphasis>tuple.get( 1 )</emphasis> calls.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>aliased</term>
- <listitem>
- <programlisting><![CDATA[Object get(String alias)]]></programlisting>
- <programlisting><![CDATA[<X> X get(String alias, Class<X> type)]]></programlisting>
- <para>
- Again, only the second form here provides typing, because the user explicitly provides
- the typing on access. We have not seen an example of using this, but its trivial. We
- would simply, for example, have applies an alias to either of the paths like
- <emphasis>idPath.alias( "id" )</emphasis> and/or <emphasis>agePath.alias( "age" )</emphasis>
- and we could have accessed the individual tuple elements by those specified aliases.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
+ <calloutlist>
+ <callout arearefs="ex.criteria.typedquery.tuple.1">
+ <para>Here we see the use of a new
+ <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
+ <interfacename>javax.persistence.criteria.CriteriaQuery</interfacename>
+ building method, <methodname>createTupleQuery</methodname>. This is
+ exactly equivalent to calling <emphasis>builder.createQuery(
+ Tuple.class )</emphasis>. It signifies that we want to access the
+ results through the
+ <interfacename>javax.persistence.Tuple</interfacename>
+ contract.</para>
+ </callout>
+ <callout arearefs="ex.criteria.typedquery.tuple.2">
+ <para>Again we see the use of the
+ <methodname>multiselect</methodname> method, just like in <xref
+ linkend="ex-criteria-typedquery-array2" />. The difference here is
+ that the type of the
+ <interfacename>javax.persistence.criteria.CriteriaQuery</interfacename>
+ was defined as
+ <interfacename>javax.persistence.Tuple</interfacename> so the
+ compound selections in this case are interpreted to be the tuple
+ elements.</para>
+ </callout>
+
+ <callout arearefs="ex.criteria.typedquery.tuple.3">
+ <para>Here we see
+ <interfacename>javax.persistence.Tuple</interfacename> allowing
+ different types of access to the results, which we will expand on
+ next.</para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ <section id="querycriteria-tuple-access">
+ <title>Accessing tuple elements</title>
+
+ <para>The <interfacename>javax.persistence.Tuple</interfacename>
+ contract provides 3 basic forms of access to the underlying
+ elements:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>typed</term>
+
+ <listitem>
+ <programlisting><X> X get(TupleElement<X> tupleElement)</programlisting>
+
+ <para>This allows typed access to the underlying tuple elements.
+ We see this in <xref linkend="ex-criteria-typedquery-tuple" /> in
+ the <emphasis>tuple.get( idPath )</emphasis> and
+ <emphasis>tuple.get( agePath )</emphasis> calls. Just about
+ everything is a
+ <interfacename>javax.persistence.TupleElement</interfacename>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>positional</term>
+
+ <listitem>
+ <programlisting>Object get(int i)</programlisting>
+
+ <programlisting><X> X get(int i, Class<X> type)</programlisting>
+
+ <para>Very similar to what we saw in <xref
+ linkend="ex-criteria-typedquery-array" /> and <xref
+ linkend="ex-criteria-typedquery-array2" /> in terms of positional
+ access. Only the second form here provides typing, because the
+ user explicitly provides the typing on access. We see this in
+ <xref linkend="ex-criteria-typedquery-tuple" /> in the
+ <emphasis>tuple.get( 0 )</emphasis> and <emphasis>tuple.get( 1
+ )</emphasis> calls.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>aliased</term>
+
+ <listitem>
+ <programlisting>Object get(String alias)</programlisting>
+
+ <programlisting><X> X get(String alias, Class<X> type)</programlisting>
+
+ <para>Again, only the second form here provides typing, because
+ the user explicitly provides the typing on access. We have not
+ seen an example of using this, but its trivial. We would simply,
+ for example, have applies an alias to either of the paths like
+ <emphasis>idPath.alias( "id" )</emphasis> and/or
+ <emphasis>agePath.alias( "age" )</emphasis> and we could have
+ accessed the individual tuple elements by those specified
+ aliases.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
+ </section>
+ <section id="querycriteria-from">
+ <title>FROM clause</title>
+ <blockquote>
+ <attribution><citation><xref linkend="JPA2" />, section 6.5.2 Query
+ Roots, pg 262</citation></attribution>
- <section id="querycriteria-from">
- <title>FROM clause</title>
- <blockquote>
- <attribution>
- <citation><xref linkend="JPA2"/>, section 6.5.2 Query Roots, pg 262</citation>
- </attribution>
- <para>
- A CriteriaQuery object defines a query over one or more entity, embeddable, or basic abstract
- schema types. The root objects of the query are entities, from which the other types are reached
- by navigation.
- </para>
- </blockquote>
+ <para>A CriteriaQuery object defines a query over one or more entity,
+ embeddable, or basic abstract schema types. The root objects of the
+ query are entities, from which the other types are reached by
+ navigation.</para>
+ </blockquote>
- <note>
- <para>
- All the individual parts of the FROM clause (roots, joins, paths) implement the
- <interfacename>javax.persistence.criteria.From</interfacename> interface.
- </para>
- </note>
+ <note>
+ <para>All the individual parts of the FROM clause (roots, joins, paths)
+ implement the
+ <interfacename>javax.persistence.criteria.From</interfacename>
+ interface.</para>
+ </note>
- <section id="querycriteria-from-root">
- <title>Roots</title>
- <para>
- Roots define the basis from which all joins, paths and attributes are available in the query. In
- a criteria query, a root is always an entity. Roots are defined and added to the criteria by
- the overloaded <methodname>from</methodname> methods on
- <interfacename>javax.persistence.criteria.CriteriaQuery</interfacename>:
- </para>
- <programlisting><![CDATA[<X> Root<X> from(Class<X>)]]></programlisting>
- <programlisting><![CDATA[<X> Root<X> from(EntityType<X>)]]></programlisting>
- <example>
- <title>Adding a root</title>
- <programlisting><![CDATA[CriteriaQuery<Person> personCriteria = builder.createQuery( Person.class );
+ <section id="querycriteria-from-root">
+ <title>Roots</title>
+
+ <para>Roots define the basis from which all joins, paths and attributes
+ are available in the query. In a criteria query, a root is always an
+ entity. Roots are defined and added to the criteria by the overloaded
+ <methodname>from</methodname> methods on
+ <interfacename>javax.persistence.criteria.CriteriaQuery</interfacename>:</para>
+
+ <programlisting><X> Root<X> from(Class<X>)</programlisting>
+
+ <programlisting><X> Root<X> from(EntityType<X>)</programlisting>
+
+ <example>
+ <title>Adding a root</title>
+
+ <programlisting>CriteriaQuery<Person> personCriteria = builder.createQuery( Person.class );
// create and add the root
person.from( Person.class );
-...]]></programlisting>
- </example>
+...</programlisting>
+ </example>
- <para>
- Criteria queries may define multiple roots, the effect of which is to create a
- <ulink url="http://en.wikipedia.org/wiki/Cartesian_product">cartesian product</ulink>
- between the newly added root and the others. Here is an example matching all single men and all
- single women:
- </para>
- <programlisting><![CDATA[CriteriaQuery query = builder.createQuery();
-Root<Person> men = query.from( Person.class );
-Root<Person> women = query.from( Person.class );
+ <para>Criteria queries may define multiple roots, the effect of which is
+ to create a <ulink
+ url="http://en.wikipedia.org/wiki/Cartesian_product">cartesian
+ product</ulink> between the newly added root and the others. Here is an
+ example matching all single men and all single women:</para>
+
+ <programlisting>CriteriaQuery query = builder.createQuery();
+Root<Person> men = query.from( Person.class );
+Root<Person> women = query.from( Person.class );
Predicate menRestriction = builder.and(
builder.equal( men.get( Person_.gender ), Gender.MALE ),
builder.equal( men.get( Person_.relationshipStatus ), RelationshipStatus.SINGLE )
@@ -538,127 +604,133 @@
builder.equal( women.get( Person_.gender ), Gender.FEMALE ),
builder.equal( women.get( Person_.relationshipStatus ), RelationshipStatus.SINGLE )
);
-query.where( builder.and( menRestriction, womenRestriction ) );]]></programlisting>
- </section>
+query.where( builder.and( menRestriction, womenRestriction ) );</programlisting>
+ </section>
- <section id="querycriteria-from-join">
- <title>Joins</title>
- <para>Joins allow navigation from other
- <interfacename>javax.persistence.criteria.From</interfacename>
- to either association or embedded attributes. Joins are created by the numerous overloaded
- <methodname>join</methodname>
- methods of the
- <interfacename>javax.persistence.criteria.From</interfacename>
- interface:
- </para>
- <example id="criteria-join-singular">
- <title>Example with Embedded and ManyToOne</title>
- <programlisting><![CDATA[CriteriaQuery<Person> personCriteria = builder.createQuery( Person.class );
-Root<Person> personRoot = person.from( Person.class );
+ <section id="querycriteria-from-join">
+ <title>Joins</title>
+
+ <para>Joins allow navigation from other
+ <interfacename>javax.persistence.criteria.From</interfacename> to either
+ association or embedded attributes. Joins are created by the numerous
+ overloaded <methodname>join</methodname> methods of the
+ <interfacename>javax.persistence.criteria.From</interfacename>
+ interface:</para>
+
+ <example id="criteria-join-singular">
+ <title>Example with Embedded and ManyToOne</title>
+
+ <programlisting>CriteriaQuery<Person> personCriteria = builder.createQuery( Person.class );
+Root<Person> personRoot = person.from( Person.class );
// Person.address is an embedded attribute
-Join<Person,Address> personAddress = personRoot.join( Person_.address );
+Join<Person,Address> personAddress = personRoot.join( Person_.address );
// Address.country is a ManyToOne
-Join<Address,Country> addressCountry = personAddress.join( Address_.country );
-...]]></programlisting>
- </example>
- <example id="criteria-join-plural">
- <title>Example with Collections</title>
- <programlisting><![CDATA[CriteriaQuery<Person> personCriteria = builder.createQuery( Person.class );
-Root<Person> personRoot = person.from( Person.class );
-Join<Person,Order> orders = personRoot.join( Person_.orders );
-Join<Order,LineItem> orderLines = orders.join( Order_.lineItems );
-...]]></programlisting>
- </example>
- </section>
+Join<Address,Country> addressCountry = personAddress.join( Address_.country );
+...</programlisting>
+ </example>
- <section id="querycriteria-from-fetch">
- <title>Fetches</title>
- <para>
- Just like in HQL and EJB-QL, we can specify that associated data be fetched along with the owner.
- Fetches are created by the numerous overloaded <methodname>fetch</methodname>
- methods of the <interfacename>javax.persistence.criteria.From</interfacename>
- interface:
- </para>
- <example id="criteria-fetch-singular">
- <title>Example with Embedded and ManyToOne</title>
- <programlisting><![CDATA[CriteriaQuery<Person> personCriteria = builder.createQuery( Person.class );
-Root<Person> personRoot = person.from( Person.class );
+ <example id="criteria-join-plural">
+ <title>Example with Collections</title>
+
+ <programlisting>CriteriaQuery<Person> personCriteria = builder.createQuery( Person.class );
+Root<Person> personRoot = person.from( Person.class );
+Join<Person,Order> orders = personRoot.join( Person_.orders );
+Join<Order,LineItem> orderLines = orders.join( Order_.lineItems );
+...</programlisting>
+ </example>
+ </section>
+
+ <section id="querycriteria-from-fetch">
+ <title>Fetches</title>
+
+ <para>Just like in HQL and EJB-QL, we can specify that associated data
+ be fetched along with the owner. Fetches are created by the numerous
+ overloaded <methodname>fetch</methodname> methods of the
+ <interfacename>javax.persistence.criteria.From</interfacename>
+ interface:</para>
+
+ <example id="criteria-fetch-singular">
+ <title>Example with Embedded and ManyToOne</title>
+
+ <programlisting>CriteriaQuery<Person> personCriteria = builder.createQuery( Person.class );
+Root<Person> personRoot = person.from( Person.class );
// Person.address is an embedded attribute
-Join<Person,Address> personAddress = personRoot.fetch( Person_.address );
+Join<Person,Address> personAddress = personRoot.fetch( Person_.address );
// Address.country is a ManyToOne
-Join<Address,Country> addressCountry = personAddress.fetch( Address_.country );
-...]]></programlisting>
- </example>
- <note>
- <para>
- Technically speaking, embedded attributes are always fetched with their owner. However
- in order to define the fetching of <emphasis>Address#country</emphasis> we needed
- a <interfacename>javax.persistence.criteria.Fetch</interfacename> for its parent path.
- </para>
- </note>
- <example id="criteria-fetch-plural">
- <title>Example with Collections</title>
- <programlisting><![CDATA[CriteriaQuery<Person> personCriteria = builder.createQuery( Person.class );
-Root<Person> personRoot = person.from( Person.class );
-Join<Person,Order> orders = personRoot.fetch( Person_.orders );
-Join<Order,LineItem> orderLines = orders.fetch( Order_.lineItems );
-...]]></programlisting>
- </example>
- </section>
+Join<Address,Country> addressCountry = personAddress.fetch( Address_.country );
+...</programlisting>
+ </example>
+ <note>
+ <para>Technically speaking, embedded attributes are always fetched
+ with their owner. However in order to define the fetching of
+ <emphasis>Address#country</emphasis> we needed a
+ <interfacename>javax.persistence.criteria.Fetch</interfacename> for
+ its parent path.</para>
+ </note>
+
+ <example id="criteria-fetch-plural">
+ <title>Example with Collections</title>
+
+ <programlisting>CriteriaQuery<Person> personCriteria = builder.createQuery( Person.class );
+Root<Person> personRoot = person.from( Person.class );
+Join<Person,Order> orders = personRoot.fetch( Person_.orders );
+Join<Order,LineItem> orderLines = orders.fetch( Order_.lineItems );
+...</programlisting>
+ </example>
</section>
+ </section>
- <section id="querycriteria-path">
- <title>Path expressions</title>
- <note>
- <para>
- Roots, joins and fetches are themselves paths as well.
- </para>
- </note>
- </section>
+ <section id="querycriteria-path">
+ <title>Path expressions</title>
+ <note>
+ <para>Roots, joins and fetches are themselves paths as well.</para>
+ </note>
+ </section>
- <section id="querycriteria-param">
- <title>Using parameters</title>
- <example id="ex-querycriteria-param" >
- <title>Using parameters</title>
- <programlistingco>
- <areaspec>
- <area coords="4" id="ex.criteria.param.1"/>
- <area coords="5" id="ex.criteria.param.2"/>
- <area coords="7" id="ex.criteria.param.3"/>
- </areaspec>
- <programlisting><![CDATA[CriteriaQuery<Person> criteria = build.createQuery( Person.class );
-Root<Person> personRoot = criteria.from( Person.class );
+ <section id="querycriteria-param">
+ <title>Using parameters</title>
+
+ <example id="ex-querycriteria-param">
+ <title>Using parameters</title>
+
+ <programlistingco>
+ <areaspec>
+ <area coords="4" id="ex.criteria.param.1" />
+
+ <area coords="5" id="ex.criteria.param.2" />
+
+ <area coords="7" id="ex.criteria.param.3" />
+ </areaspec>
+
+ <programlisting>CriteriaQuery<Person> criteria = build.createQuery( Person.class );
+Root<Person> personRoot = criteria.from( Person.class );
criteria.select( personRoot );
-ParameterExpression<String> eyeColorParam = builder.parameter( String.class );
+ParameterExpression<String> eyeColorParam = builder.parameter( String.class );
criteria.where( builder.equal( personRoot.get( Person_.eyeColor ), eyeColorParam ) );
-TypedQuery<Person> query = em.createQuery( criteria );
+TypedQuery<Person> query = em.createQuery( criteria );
query.setParameter( eyeColorParam, "brown" );
-List<Person> people = query.getResultList();]]></programlisting>
- <calloutlist>
- <callout arearefs="ex.criteria.param.1">
- <para>
- Use the <methodname>parameter</methodname> method of
- <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
- to obtain a parameter reference.
- </para>
- </callout>
- <callout arearefs="ex.criteria.param.2">
- <para>
- Use the parameter reference in the criteria query.
- </para>
- </callout>
- <callout arearefs="ex.criteria.param.3">
- <para>
- Use the parameter reference to bind the parameter value to the
- <interfacename>javax.persistence.TypedQuery</interfacename>
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
+List<Person> people = query.getResultList();</programlisting>
- </example>
- </section>
+ <calloutlist>
+ <callout arearefs="ex.criteria.param.1">
+ <para>Use the <methodname>parameter</methodname> method of
+ <interfacename>javax.persistence.criteria.CriteriaBuilder</interfacename>
+ to obtain a parameter reference.</para>
+ </callout>
+ <callout arearefs="ex.criteria.param.2">
+ <para>Use the parameter reference in the criteria query.</para>
+ </callout>
+
+ <callout arearefs="ex.criteria.param.3">
+ <para>Use the parameter reference to bind the parameter value to
+ the
+ <interfacename>javax.persistence.TypedQuery</interfacename></para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+ </example>
+ </section>
</chapter>
Modified: core/trunk/entitymanager/src/main/docbook/en/modules/transactions.xml
===================================================================
--- core/trunk/entitymanager/src/main/docbook/en/modules/transactions.xml 2010-03-09 14:49:39 UTC (rev 18940)
+++ core/trunk/entitymanager/src/main/docbook/en/modules/transactions.xml 2010-03-09 14:50:32 UTC (rev 18941)
@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
@@ -22,8 +22,8 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="transactions" revision="1">
<title>Transactions and Concurrency</title>
@@ -95,23 +95,22 @@
<para>The most common pattern in a multi-user client/server application
is <emphasis>entitymanager-per-request</emphasis>. In this model, a
- request from the client is send to the server (where the EJB3
- persistence layer runs), a new <literal>EntityManager</literal> is
- opened, and all database operations are executed in this unit of work.
- Once the work has been completed (and the response for the client has
- been prepared), the persistence context is flushed and closed, as well
- as the entity manager object. You would also use a single database
- transaction to serve the clients request. The relationship between the
- two is one-to-one and this model is a perfect fit for many
- applications.</para>
+ request from the client is send to the server (where the JPA persistence
+ layer runs), a new <literal>EntityManager</literal> is opened, and all
+ database operations are executed in this unit of work. Once the work has
+ been completed (and the response for the client has been prepared), the
+ persistence context is flushed and closed, as well as the entity manager
+ object. You would also use a single database transaction to serve the
+ clients request. The relationship between the two is one-to-one and this
+ model is a perfect fit for many applications.</para>
- <para>This is the default EJB3 persistence model in a Java EE
- environment (JTA bounded, transaction-scoped persistence context);
- injected (or looked up) entity managers share the same persistence
- context for a particular JTA transaction. The beauty of EJB3 is that you
- don't have to care about that anymore and just see data access through
- entity manager and demarcation of transaction scope on session beans as
- completely orthogonal.</para>
+ <para>This is the default JPA persistence model in a Java EE environment
+ (JTA bounded, transaction-scoped persistence context); injected (or
+ looked up) entity managers share the same persistence context for a
+ particular JTA transaction. The beauty of JPA is that you don't have to
+ care about that anymore and just see data access through entity manager
+ and demarcation of transaction scope on session beans as completely
+ orthogonal.</para>
<para>The challenge is the implementation of this (and other) behavior
outside an EJB3 container: not only has the
@@ -187,14 +186,14 @@
transactions (the last one) stores the updated data, all others simply
read data (e.g. in a wizard-style dialog spanning several
request/response cycles). This is easier to implement than it might
- sound, especially if you use EJB3 entity manager and persistence context
+ sound, especially if you use JPA entity manager and persistence context
features:</para>
<itemizedlist>
<listitem>
<para><emphasis>Automatic Versioning</emphasis> - An entity manager
can do automatic optimistic concurrency control for you, it can
- automatically detect if a concurrent modification occured during
+ automatically detect if a concurrent modification occurred during
user think time (usually by comparing version numbers or timestamps
when updating the data in the final resource-local
transaction).</para>
@@ -249,9 +248,7 @@
<term>Database Identity</term>
<listitem>
- <para>
- <literal>foo.getId().equals( bar.getId() )</literal>
- </para>
+ <para><literal>foo.getId().equals( bar.getId() )</literal></para>
</listitem>
</varlistentry>
@@ -259,9 +256,7 @@
<term>JVM Identity</term>
<listitem>
- <para>
- <literal>foo==bar</literal>
- </para>
+ <para><literal>foo==bar</literal></para>
</listitem>
</varlistentry>
</variablelist>
@@ -371,8 +366,8 @@
<sect1 id="transactions-demarcation">
<title>Database transaction demarcation</title>
- <para>Database (or system) transaction boundaries are always necessary.
- No communication with the database can occur outside of a database
+ <para>Database (or system) transaction boundaries are always necessary. No
+ communication with the database can occur outside of a database
transaction (this seems to confuse many developers who are used to the
auto-commit mode). Always use clear transaction boundaries, even for
read-only operations. Depending on your isolation level and database
@@ -381,8 +376,8 @@
outside a transaction, though, when you'll need to retain modifications in
an <literal>EXTENDED</literal> persistence context.</para>
- <para>An EJB3 application can run in non-managed (i.e. standalone, simple
- Web- or Swing applications) and managed J2EE environments. In a
+ <para>A JPA application can run in non-managed (i.e. standalone, simple
+ Web- or Swing applications) and managed Java EE environments. In a
non-managed environment, an <literal>EntityManagerFactory</literal> is
usually responsible for its own database connection pool. The application
developer has to manually set transaction boundaries, in other words,
@@ -418,7 +413,7 @@
<sect2 id="transactions-demarcation-nonmanaged">
<title>Non-managed environment</title>
- <para>If an EJB3 persistence layer runs in a non-managed environment,
+ <para>If an JPA persistence layer runs in a non-managed environment,
database connections are usually handled by Hibernate's pooling
mechanism behind the scenes. The common entity manager and transaction
handling idiom looks like this:</para>
@@ -562,6 +557,11 @@
<programlisting>//CMT idiom through injection
@PersistenceContext(name="sample") EntityManager em;</programlisting>
+ <para>Or this if you use Java Context and Dependency Injection
+ (CDI).</para>
+
+ <programlisting>@Inject EntityManager em;</programlisting>
+
<para>In other words, all you have to do in a managed environment is to
inject the <literal>EntityManager</literal>, do your data access work,
and leave the rest to the container. Transaction boundaries are set
@@ -569,12 +569,7 @@
session beans. The lifecycle of the entity manager and persistence
context is completely managed by the container.</para>
- <para>TODO: The following paragraph is very confusing, especially the
- beginning...</para>
-
- <para>When using particular Hibernate native APIs, one caveat has to be
- remembered: <literal>after_statement</literal> connection release mode.
- Due to a silly limitation of the JTA spec, it is not possible for
+ <para>Due to a silly limitation of the JTA spec, it is not possible for
Hibernate to automatically clean up any unclosed
<literal>ScrollableResults</literal> or <literal>Iterator</literal>
instances returned by <literal>scroll()</literal> or
@@ -610,23 +605,76 @@
<itemizedlist>
<listitem>
- <para>IllegalArgumentException: something wrong happen</para>
+ <para><classname>IllegalArgumentException</classname>: something
+ wrong happen</para>
</listitem>
<listitem>
- <para>EntityNotFoundException: an entity was expected but none match
- the requirement</para>
+ <para><classname>EntityNotFoundException</classname>: an entity was
+ expected but none match the requirement</para>
</listitem>
<listitem>
- <para>TransactionRequiredException: this operation has to be in a
- transaction</para>
+ <para><classname>NonUniqueResultException</classname>: more than one
+ entity is found when calling
+ <methodname>getSingleResult()</methodname></para>
</listitem>
<listitem>
- <para>IllegalStateException: the entity manager is used in a wrong
- way</para>
+ <para>NoResultException: when
+ <methodname>getSingleResult()</methodname> does not find any
+ matching entity</para>
</listitem>
+
+ <listitem>
+ <para><classname>EntityExistsException</classname>: an existing
+ entity is passed to <methodname>persist()</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><classname>TransactionRequiredException</classname>: this
+ operation has to be in a transaction</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>IllegalStateException</classname>: the entity
+ manager is used in a wrong way</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>RollbackException</classname>: a failure happens
+ during <methodname>commit()</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><classname>QueryTimeoutException</classname>: the query takes
+ longer than the specified timeout (see
+ <literal>javax.persistence.query.timeout</literal> - this property
+ is a hint and might not be followed)</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>PessimisticLockException</classname>: when a lock
+ cannot be acquired</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>OptimisticLockException</classname>: an optimistic
+ lock is failing</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>LockTimeoutException</classname>: when a lock takes
+ longer than the expected time to be acquired
+ (<literal>javax.persistence.lock.timeout</literal> in
+ milliseconds)</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>TransactionRequiredException</classname>: an
+ operation requiring a transaction is executed outside of a
+ transaction</para>
+ </listitem>
</itemizedlist>
<para>The <literal>HibernateException</literal>, which wraps most of the
@@ -694,10 +742,10 @@
<para>In an <literal>EXTENDED</literal> persistence context, all read only
operations of the entity manager can be executed outside a transaction
(<literal>find()</literal>, <literal>getReference()</literal>,
- <literal>refresh()</literal>, and read queries). Some modifications
- operations can be executed outside a transaction, but they are queued
- until the persistence context join a transaction: this is the case of
- <literal>persist()</literal>,
+ <literal>refresh()</literal>, <methodname>detach()</methodname> and read
+ queries). Some modifications operations can be executed outside a
+ transaction, but they are queued until the persistence context join a
+ transaction: this is the case of <literal>persist()</literal>,
<literal><literal>merge()</literal></literal>,
<literal>remove()</literal>. Some operations cannot be called outside a
transaction: <literal>flush()</literal>, <literal>lock()</literal>, and
@@ -706,12 +754,12 @@
<sect2>
<title>Container Managed Entity Manager</title>
- <para>When using an EXTENDED persistence context with a container
- managed entity manager, the lifecycle of the persistence context is
- binded to the lifecycle of the Stateful Session Bean. Plus if the entity
- manager is created outside a transaction, modifications operations
- (persist, merge, remove) are queued in the persistence context and not
- executed to the database.</para>
+ <para>When using an <literal>EXTENDED</literal> persistence context with
+ a container managed entity manager, the lifecycle of the persistence
+ context is binded to the lifecycle of the Stateful Session Bean. Plus if
+ the entity manager is created outside a transaction, modifications
+ operations (persist, merge, remove) are queued in the persistence
+ context and not executed to the database.</para>
<para>When a method of the stateful session bean involved or starting a
transaction is later called, the entity manager join the transaction.
@@ -897,7 +945,7 @@
entityManager.close();</programlisting>
<para>Again, the entity manager will check instance versions during
- flush, throwing an exception if conflicting updates occured.</para>
+ flush, throwing an exception if conflicting updates occurred.</para>
</sect2>
</sect1>
-</chapter>
\ No newline at end of file
+</chapter>
More information about the hibernate-commits
mailing list