diff --git a/entitymanager/src/main/docbook/en/master.xml b/entitymanager/src/main/docbook/en/master.xml index 5a9c263197..ef1b2fb71f 100644 --- a/entitymanager/src/main/docbook/en/master.xml +++ b/entitymanager/src/main/docbook/en/master.xml @@ -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@sun.com + JSR 317 JCP Page + + + - Introducing EJB3 Persistence - The EJB3 specification recognizes the interest and the success of - the transparent object/relational mapping paradigm. The EJB3 specification - 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. Together - with Hibernate Annotations, this wrapper implements a - complete (and standalone) EJB3 persistence solution on top of the mature - 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 specification + 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. Together + withHibernate Annotations, this wrapper implements a + complete (and standalone) EJB3 persistence solution on top of the mature + 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. + - - - - - - - - - - - - - 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@sun.com - - - - - \ No newline at end of file + + + + + + + + + + diff --git a/entitymanager/src/main/docbook/en/modules/query_criteria.xml b/entitymanager/src/main/docbook/en/modules/query_criteria.xml index e1619c8d91..46bea10c03 100644 --- a/entitymanager/src/main/docbook/en/modules/query_criteria.xml +++ b/entitymanager/src/main/docbook/en/modules/query_criteria.xml @@ -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 query. They are type-safe + 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 org.hibernate.Criteria query API will recognize + 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 + 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 the criteria instance + + + - - - Building the criteria instance - Executing the criteria instance - -
Criteria query building - 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. + query. The first step in performing a criteria query is building this graph. -
CriteriaBuilder - - The javax.persistence.criteria.CriteriaBuilder interface is the - first thing with which you need to become acquainted to begin using criteria queries. Its role - is a factory for all the individual pieces of the criteria. You obtain a - javax.persistence.criteria.CriteriaBuilder instance by calling - the javax.persistence.EntityManagerFactory.getCriteriaBuilder method: + The + javax.persistence.criteria.CriteriaBuilder + interface is the + first thing with which you need to become acquainted to begin using criteria queries. Its role + is a factory for all the individual pieces of the criteria. You obtain a + javax.persistence.criteria.CriteriaBuilder + instance by calling + the + javax.persistence.EntityManagerFactory.getCriteriaBuilder + method: - CriteriaBuilder builder = entityManagerFactory.getCriteriaBuilder();
-
CriteriaQuery creation - - Once you have the javax.persistence.criteria.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 defines 3 methods - for obtaining a javax.persistence.criteria.CriteriaQuery + Once you have the + javax.persistence.criteria.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 + defines 3 methods + for obtaining a + javax.persistence.criteria.CriteriaQuery instance: - createQuery(Class)]]> @@ -100,80 +110,153 @@ createQuery()]]> - - Each serves different purposes 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. + 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 - personCriteria = builder.createQuery(Person.class);]]> + + personCriteria = builder.createQuery(Person.class);]]> Basically this is saying to create a criteria where the results of this query will be of type - Person. Person might be an entity or it might not. The type could even be simple types like - java.lang.Integer, java.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,java.lang.String, etc. We + will discuss this topic in more detail in +
-
Tuple CriteriaQuery - personCriteria = builder.createTupleQuery();]]> - personCriteria = builder.createQuery(Tuple.class);]]> + + personCriteria = builder.createTupleQuery();]]> + + personCriteria = builder.createQuery(Tuple.class);]]> - These two forms are exactly the same. Both say to create 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 create 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 values, a projection. The - javax.persistence.Tuple instance gives us typed access to these - multiple result values after the query has been executed. We will discuss accessing the query - results via a javax.persistence.Tuple in + that each query result will actually be multiple values, a projection. The + javax.persistence.Tuple + instance gives us typed access to these + multiple result values after the query has been executed. We will discuss accessing the query + results via a + javax.persistence.Tuple + in .
-
Untyped CriteriaQuery - personCriteria = builder.createQuery();]]> - personCriteria = builder.createQuery(Object.class);]]> + + personCriteria = builder.createQuery();]]> + + personCriteria = builder.createQuery(Object.class);]]> - These two forms are exactly the same. Both say to create 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 create 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 more entity, embeddable, or basic abstract - schema types. The root objects of the query are entities, from which the other types are reached + schema types. The root objects of the query are entities, from which the other types are reached by navigation.
- + All the individual parts of the FROM clause (roots, joins, paths) implement the + javax.persistence.criteria.From + interface. +
Roots - - + Roots define the basis from which all joins, paths and 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 the criteria by the overloaded + from + methods onjavax.persistence.criteria.CriteriaQuery: + Root from(Class)]]> + Root from(EntityType)]]> + personCriteria = builder.createQuery( Person.class ); +// create and add the root +person.from( Person.class ); +...]]> + Criteria queries may define multiple roots, the effect of which is to create a cartesean product + between the newly added root and the others. Here is an example matching all single men and all + single women: + + men = query.from( Person.class ); +Root 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 + ) +); +Predicate womenRestriction = 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 are created by the numerous overloaded + join + methods of the + javax.persistence.criteria.From + interface: + + personCriteria = builder.createQuery( Person.class ); +Root personRoot = person.from( Person.class ); +// Person.address is an embedded attribute +Join personAddress = personRoot.join( Person_.address ); +// Address.country is a ManyToOne +Join addressCountry = personAddress.join( Address_.country ); +...]]> + An example with collection attributes: + personCriteria = builder.createQuery( Person.class ); +Root personRoot = person.from( Person.class ); +Join orders = personRoot.join( Person_.orders ); +Join orderLines = 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 = em.createQuery( personCriteria ).getResultList();]]>
-
Selecting an association people = em.createQuery( personCriteria ).getResultList();]]>
-
Selecting a value heights = em.createQuery( personCriteria ).getResultList();]]>
-
Selecting an aggregated value
-
Selecting a tuple
-
Selecting a constructed value people = em.createQuery( personCriteria ).getResultList();]]>
-
Using parameters people = query.getResultList();]]>
- - \ No newline at end of file +