From hibernate-commits at lists.jboss.org Fri Feb 19 16:16:50 2010 Content-Type: multipart/mixed; boundary="===============5038821374018500512==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r18842 - in core/trunk/entitymanager/src/main/docbook/en: modules and 1 other directory. Date: Fri, 19 Feb 2010 16:16:50 -0500 Message-ID: <201002192116.o1JLGofv014432@svn01.web.mwc.hst.phx2.redhat.com> --===============5038821374018500512== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: steve.ebersole(a)jboss.com Date: 2010-02-19 16:16:50 -0500 (Fri, 19 Feb 2010) New Revision: 18842 Modified: core/trunk/entitymanager/src/main/docbook/en/master.xml core/trunk/entitymanager/src/main/docbook/en/modules/query_criteria.xml Log: HHH-4936 - Document JPA criteria queries Modified: core/trunk/entitymanager/src/main/docbook/en/master.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/entitymanager/src/main/docbook/en/master.xml 2010-02-19 17:0= 8:37 UTC (rev 18841) +++ core/trunk/entitymanager/src/main/docbook/en/master.xml 2010-02-19 21:1= 6:50 UTC (rev 18842) @@ -1,4 +1,4 @@ - + + --> -]> - + ]> + Hibernate EntityManager - User guide - &versionNumber; - - + - + + References + + JPA 2 Specification + JSR 317: <trademark>Java</trademark> Persistence API, Version= 2.0 + + Java Persistence 2.0 Expert Group + + + 2009 + SUN MICROSYSTEMS, INC. + + + jsr-317-feedback(a)sun.com + JSR 317 JCP P= age + + + - Introducing EJB3 Persistence - The EJB3 specification recognizes the interest and the success of - the transparent object/relational mapping paradigm. The EJB3 specifica= tion - standardizes the basic APIs and the metadata needed for any - object/relational persistence mechanism. Hibernate - EntityManager implements the programming interfaces and - lifecycle rules as defined by the EJB3 persistence specification. Toge= ther - with Hibernate Annotations, this wrapper implemen= ts a - complete (and standalone) EJB3 persistence solution on top of the matu= re - Hibernate core. You may use a combination of all three together, - annotations without EJB3 programming interfaces and lifecycle, or even - pure native Hibernate, depending on the business and technical needs of - your project. You can at all times fall back to Hibernate native APIs,= or - if required, even to native JDBC and SQL. + the transparent object/relational mapping paradigm. The EJB3 s= pecification + standardizes the basic APIs and the metadata needed for any + object/relational persistence mechanism. + Hibernate EntityManager + implements the programming interfaces and + lifecycle rules as defined by the EJB3 persistence specificati= on. Together + withHibernate Annotations, this wrapper i= mplements a + complete (and standalone) EJB3 persistence solution on top of = the mature + Hibernate core. You may use a combination of all three togethe= r, + annotations without EJB3 programming interfaces and lifecycle,= or even + pure native Hibernate, depending on the business and technical= needs of + your project. You can at all times fall back to Hibernate nati= ve APIs, or + if required, even to native JDBC and SQL. + - - - - - - - - - - - - - References - - - JPA 2 Specification - JSR 317: <trademark>Java</trademark> Persistence API, V= ersion 2.0 - Java Persistence 2.0 Expert Group - - 2009 - SUN MICROSYSTEMS, INC. - - - jsr-317-feedback(a)sun.com - - - - - \ No newline at end of file + + + + + + + + + + Modified: core/trunk/entitymanager/src/main/docbook/en/modules/query_criter= ia.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/entitymanager/src/main/docbook/en/modules/query_criteria.xml= 2010-02-19 17:08:37 UTC (rev 18841) +++ core/trunk/entitymanager/src/main/docbook/en/modules/query_criteria.xml= 2010-02-19 21:16:50 UTC (rev 18842) @@ -1,4 +1,4 @@ - + - - - + - JPA Criteria Queries + Criteria Queries = This chapter elaborates on the material discussed in - Chapter 6 Criteria API of the - . + Chapter 6 Criteria API + ofJPA 2 Specification. = - Criteria queries are a programmatic, type-safe way to express a qu= ery. They are type-safe + Criteria queries are a programmatic, type-safe way to express a qu= ery. They are type-safe in terms of using interfaces and classes to represent various stru= ctural parts of a query - such as the query itself, or the select clause, or an order-by, et= c. They can also be - type-safe in terms of referencing attributes as we will see in a b= it. Users of the older - Hibernate org.hibernate.Criteria qu= ery API will recognize + such as the query itself, or the select clause, or an order-by, et= c. They can also be + type-safe in terms of referencing attributes as we will see in a b= it. Users of the older + Hibernate + org.hibernate.Criteria + 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. There are essentially = 2 phases to performing + look at the lessons learned from that API. There are essentially 2= phases to performing a criteria query: + + + + + Building the = criteria instance + + + + + Executing th= e criteria instance + + + = - - - Building the cr= iteria instance - Executing the = criteria instance - - =
Criteria query building - Criteria queries are essentially an object graph, where each p= art 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 build= ing this graph. + query. The first step in performing a criteria query is buildi= ng this graph. -
CriteriaBuilder - - The javax.persistence.criteria.CriteriaBuil= der interface is the - first thing with which you need to become acquainted to be= gin using criteria queries. Its role - is a factory for all the individual pieces of the criteria= . You obtain a - javax.persistence.criteria.CriteriaBuilder<= /interfacename> instance by calling - the javax.persistence.EntityManagerFactory.get= CriteriaBuilder method: + The + javax.persistence.criteria.CriteriaBuilder<= /interfacename> + interface is the + first thing with which you need to become acquainted to be= gin using criteria queries. Its role + is a factory for all the individual pieces of the criteria= . You obtain a + javax.persistence.criteria.CriteriaBuilder<= /interfacename> + instance by calling + the + javax.persistence.EntityManagerFactory.getCrit= eriaBuilder + method: - CriteriaBuilder builder =3D entityManagerFacto= ry.getCriteriaBuilder();
-
CriteriaQuery creation - - Once you have the javax.persistence.criteri= a.CriteriaBuilder reference - you can begin building the pieces of the criteria query. = First, you will need a - javax.persistence.criteria.CriteriaQuery instance. - javax.persistence.criteria.CriteriaBuilder<= /interfacename> defines 3 methods - for obtaining a javax.persistence.criteria.= CriteriaQuery + Once you have the + javax.persistence.criteria.CriteriaBuilder<= /interfacename> + reference + you can begin building the pieces of the criteria query. F= irst, you will need a + javax.persistence.criteria.CriteriaQuery + instance. + javax.persistence.criteria.CriteriaBuilder<= /interfacename> + defines 3 methods + for obtaining a + javax.persistence.criteria.CriteriaQuery instance: - createQuery(= Class)]]> @@ -100,80 +110,153 @@ createQ= uery()]]> - - Each serves different purposes depending on the expected t= ype of the query results. The type - is "carried forward" to the javax.persisten= ce.TypedQuery we - create from this javax.persistence.criteria= .CriteriaQuery as - we will see late= r. + Each serves a different purpose depending on the expected = type of the query results. The type + is "carried forward" to the + javax.persistence.TypedQuery + we + create from this + javax.persistence.criteria.CriteriaQuery + as + we will see later inlater. -
Typed CriteriaQuery - personCrite= ria =3D builder.createQuery(Person.class);]]> + + personCriteria =3D buil= der.createQuery(Person.class);]]> Basically this is saying to create a criteria where th= e results of this query will be of type - Person. Person might be an entity or it might not. T= he type could even be simple types like - java.lang.Integer, j= ava.lang.String, etc. We = - will discuss this topic in more detail in + Person. Person might be an entity or it might not. The= type could even be simple types like + java.lang.Integer,ja= va.lang.String, etc. We + will discuss this topic in more detail in +
-
Tuple CriteriaQuery - personCriter= ia =3D builder.createTupleQuery();]]> - personCriter= ia =3D builder.createQuery(Tuple.class);]]> + + personCriteria =3D build= er.createTupleQuery();]]> + + personCriteria =3D build= er.createQuery(Tuple.class);]]> - These two forms are exactly the same. Both say to cre= ate a criteria where the results of this - query will be of type javax.persistence= .Tuple. The term tuple is + These two forms are exactly the same. Both say to crea= te a criteria where the results of this + query will be of typejavax.persistence.= Tuple. The term tuple is taken from mathematics, but its intent here is simply = to mean a plurality; namely we are saying - that each query result will actually be multiple value= s, a projection. The - javax.persistence.Tuple= instance gives us typed access to these - multiple result values after the query has been execut= ed. We will discuss accessing the query - results via a javax.persistence.Tuple in + that each query result will actually be multiple value= s, a projection. The + javax.persistence.Tuple + instance gives us typed access to these + multiple result values after the query has been execut= ed. We will discuss accessing the query + results via a + javax.persistence.Tuple + in .
-
Untyped CriteriaQuery - personCrite= ria =3D builder.createQuery();]]> - personCrite= ria =3D builder.createQuery(Object.class);]]> + + personCriteria =3D buil= der.createQuery();]]> + + personCriteria =3D buil= der.createQuery(Object.class);]]> - These two forms are exactly the same. Both say to cre= ate a criteria where the results of this - query could be anything. Not generally recommended as= you obviously lose the type safety. + These two forms are exactly the same. Both say to crea= te a criteria where the results of this + query could be anything. Not generally recommended as = you obviously lose the type safety.
-
-
FROM clause
- + + + JPA 2 Specification + + A CriteriaQuery object defines a query over one or mor= e entity, embeddable, or basic abstract - schema types. The root objects of the query are entit= ies, from which the other types are reached + schema types. The root objects of the query are entiti= es, from which the other types are reached by navigation.
- + All the individual parts of the FROM clause (roots, join= s, paths) implement the + javax.persistence.criteria.From + interface. +
Roots - - = + Roots define the basis from which all joins, paths a= nd attributes are available in the query. It + is + the root of the portion of your domain model you wish = to query against. In a criteria query, a root + is always an entity. Roots are defined and added to th= e criteria by the overloaded + from + methods onjavax.persistence.criteria.Cr= iteriaQuery: + Root from(Class)]]> + Root from(EntityType)]]= > + personCrite= ria =3D builder.createQuery( Person.class ); +// create and add the root +person.from( Person.class ); +...]]> + Criteria queries may define multiple roots, the effe= ct of which is to create a cartesean product + between the newly added root and the others. Here is a= n example matching all single men and all + single women: + + men =3D query.from( Person.class ); +Root women =3D query.from( Person.class ); +Predicate menRestriction =3D builder.and( + builder.equal( = + men.get( Person_.gender ), + Gender.MALE = + ), + builder.equal( = + men.get( Person_.relationshipStatus ), + RelationshipStatus.SINGLE + ) +); +Predicate womenRestriction =3D builder.and( + builder.equal( = + women.get( Person_.gender ), + Gender.FEMALE = + ), + builder.equal( = + women.get( Person_.relationshipStatus ), + RelationshipStatus.SINGLE + ) +); +query.where( + builder.and( menRestriction, womenRestriction ) +);]]>
Joins - todo + Joins allow navigation from other + javax.persistence.criteria.From + to either association or embedded attributes. Joins ar= e created by the numerous overloaded + join + methods of the + javax.persistence.criteria.From + interface: + + personCrite= ria =3D builder.createQuery( Person.class ); +Root personRoot =3D person.from( Person.class ); +// Person.address is an embedded attribute +Join personAddress =3D personRoot.join( Person_.address ); +// Address.country is a ManyToOne +Join addressCountry =3D personAddress.join( Address_.coun= try ); +...]]> + An example with collection attributes: + personCrite= ria =3D builder.createQuery( Person.class ); +Root personRoot =3D person.from( Person.class ); +Join orders =3D personRoot.join( Person_.orders ); +Join orderLines =3D orders.join( Order_.lineItems ); +...]]>
Fetches todo
-
Path expressions @@ -183,22 +266,17 @@ todo
-
Selections todo
-
-
Criteria query execution todo
-
Common use cases -
Selecting the root entity people =3D em.createQuery( personCriteria ).getResultList();]= ]>
-
Selecting an association people =3D em.createQuery( personCriteria ).getResultList();]= ]>
-
Selecting a value heights =3D em.createQuery( personCriteria ).getResultList()= ;]]>
-
Selecting an aggregated value
-
Selecting a tuple
-
Selecting a constructed value people =3D em.createQuery( personCriteria ).getResultLi= st();]]>
-
Using parameters people =3D query.getResultList();]]>
- - \ No newline at end of file + --===============5038821374018500512==--