Java Persistence with Hibernate 2nd phần 9 pps

664 CHAPTER 15 Advanced query options This chapter explains all query options that you may consider optional or advanced. You’ll need the first subject of this chapter, the Criteria query interface, whenever you create more complex queries programmatically. This API is much more convenient and elegant than programmatic generation of query strings for HQL and JPA QL. Unfortunately, it’s also only available as a native Hibernate API; Java Persistence doesn’t (yet) standardize a program- matic query interface. Both Hibernate and Java Persistence support queries written in native SQL. You can embed SQL and stored procedure calls in your Java source code or exter- nalize them to mapping metadata. Hibernate can execute your SQL and convert the resultset into more convenient objects, depending on your mapping. Filtering of collections is a simple convenience feature of Hibernate—you won’t use it often. It helps you to replace a more elaborate query with a simple API call and a query fragment, for example, if you want to obtain a subset of the objects in a collection. Finally, we’ll discuss the optional query result cache—we’ve already mentioned that it’s not useful in all situations, so we’ll take a closer look at the benefits of caching results of a query and when you’d ideally enable this feature. Let’s start with query by criteria and query by example. 15.1 Querying with criteria and example The Criteria and Example APIs are available in Hibernate only; Java Persistence doesn’t standardize these interfaces. As mentioned earlier, it seems likely that other vendors, not only Hibernate, support a similar extension interface and that a future version of the standard will include this functionality. Querying with programmatically generated criteria and example objects is often the preferred solution when queries get more complex. This is especially true if you have to create a query at runtime. Imagine that you have to imple- ment a search mask in your application, with many check boxes, input fields, and switches the user can enable. You must create a database query from the user’s selection. The traditional way to do this is to create a query string through con- catenation, or maybe to write a query builder that can construct the SQL query string for you. You’d run into the same problem if you’d try to use HQL or JPA QL in this scenario. The Criteria and Example interfaces allow you to build queries programmati- cally by creating and combining objects in the right order. We now show you how Querying with criteria and example 665 to work with these APIs, and how to express selection, restriction, joins, and projection. We assume that you’ve read the previous chapter and that you know how these operations are translated into SQL. Even if you decide to use the Cri- teria and Example APIs as your primary way to write queries, keep in mind that HQL and JPA QL are always more flexible due to their string-based nature. Let’s start with some basic selection and restriction examples. 15.1.1 Basic criteria queries The simplest criteria query looks like this: session.createCriteria(Item.class); It retrieves all persistent instances of the Item class. This is also called the root entity of the criteria query. Criteria queries also support polymorphism: session.createCriteria(BillingDetails.class); This query returns instances of BillingDetails and its subclasses. Likewise, the following criteria query returns all persistent objects: session.createCriteria(java.lang.Object.class); The Criteria interface also supports ordering of results with the addOrder() method and the Order criterion: session.createCriteria(User.class) .addOrder( Order.asc("lastname") ) .addOrder( Order.asc("firstname") ); You don’t need to have an open Session to create a criteria object; a Detached- Criteria can be instantiated and later attached to a Session for execution (or to another Criteria as a subquery): DetachedCriteria crit = DetachedCriteria.forClass(User.class) .addOrder( Order.asc("lastname") ) .addOrder( Order.asc("firstname") ); List result = crit.getExecutableCriteria(session).list(); Usually you want to restrict the result and don’t retrieve all instances of a class. Applying restrictions For a criteria query, you must construct a Criterion object to express a con- straint. The Restrictions class provides factory methods for built-in Criterion types. Let’s search for User objects with a particular email address: 666 CHAPTER 15 Advanced query options Criterion emailEq = Restrictions.eq("email", "foo@hibernate.org"); Criteria crit = session.createCriteria(User.class); crit.add(emailEq); User user = (User) crit.uniqueResult(); You create a Criterion that represents the restriction for an equality comparison and add it to the Criteria . This eq() method has two arguments: first the name of the property, and then the value that should be compared. The property name is always given as a string; keep in mind that this name may change during a refactoring of your domain model and that you must update any predefined cri- teria queries manually. Also note that the criteria interfaces don’t support explicit parameter binding, because it’s not needed. In the previous example you bound the string "foo@hibernate.org" to the query; you can bind any java. lang.Object and let Hibernate figure out what to do with it. The unique- Result() method executes the query and returns exactly one object as a result— you have to cast it correctly. Usually, you write this a bit less verbosely, using method chaining: User user = (User) session.createCriteria(User.class) .add(Restrictions.eq("email", "foo@hibernate.org")) .uniqueResult(); Obviously, criteria queries are more difficult to read if they get more complex—a good reason to prefer them for dynamic and programmatic query generation, but to use externalized HQL and JPA QL for predefined queries. A new feature of JDK 5.0 is static imports; it helps making criteria queries more readable. For example, by adding import static org.hibernate.criterion.Restrictions.*; you’re able to abbreviate the criteria query restriction code to User user = (User) session.createCriteria(User.class) .add( eq("email", "foo@hibernate.org") ) .uniqueResult(); An alternative to obtaining a Criterion is a Property object—this will be more useful later in this section when we discuss projection: session.createCriteria(User.class) .add( Property.forName("email").eq("foo@hibernate.org") ); You can also name a property of a component with the usual dot notation: session.createCriteria(User.class) .add( Restrictions.eq("homeAddress.street", "Foo")); Querying with criteria and example 667 The Criteria API and the org.hibernate.criterion package offer many other operators besides eq() you can use to construct more complex expressions. Creating comparison expressions All regular SQL (and HQL, JPA QL) comparison operators are also available via the Restrictions class: Criterion restriction = Restrictions.between("amount", new BigDecimal(100), new BigDecimal(200) ); session.createCriteria(Bid.class).add(restriction); session.createCriteria(Bid.class) .add( Restrictions.gt("amount", new BigDecimal(100) ) ); String[] emails = { "foo@hibernate.org", "bar@hibernate.org" }; session.createCriteria(User.class) .add( Restrictions.in("email", emails) ); A ternary logic operator is also available; this query returns all users with no email address: session.createCriteria(User.class) .add( Restrictions.isNull("email") ); You also need to be able to find users who do have an email address: session.createCriteria(User.class) .add( Restrictions.isNotNull("email") ); You can also test a collection with isEmpty() , isNotEmpty() , or its actual size: session.createCriteria(Item.class) .add( Restrictions.isEmpty("bids")); session.createCriteria(Item.class) .add( Restrictions.sizeGt("bids", 3)); Or you can compare two properties: session.createCriteria(User.class) .add( Restrictions.eqProperty("firstname", "username") ); The criteria query interfaces also have special support for string matching. String matching For criteria queries, wildcarded searches may use either the same wildcard sym- bols as HQL and JPA QL (percentage sign and underscore) or specify a MatchMode . The MatchMode is a convenient way to express a substring match without string manipulation. These two queries are equivalent: 668 CHAPTER 15 Advanced query options session.createCriteria(User.class) .add( Restrictions.like("username", "G%") ); session.createCriteria(User.class) .add( Restrictions.like("username", "G", MatchMode.START) ); The allowed MatchMode s are START , END , ANYWHERE , and EXACT . You often also want to perform case-insensitive string matching. Where you’d resort to a function such as LOWER() in HQL or JPA QL, you can rely on a method of the Criteria API: session.createCriteria(User.class) .add( Restrictions.eq("username", "foo").ignoreCase() ); You can combine expressions with logical operators. Combining expressions with logical operators If you add multiple Criterion instances to the one Criteria instance, they’re applied conjunctively (using and ): session.createCriteria(User.class) .add( Restrictions.like("firstname", "G%") ) .add( Restrictions.like("lastname", "K%") ); If you need disjunction ( or ), there are two options. The first is to use Restric- tions.or() together with Restrictions.and() : session.createCriteria(User.class) .add( Restrictions.or( Restrictions.and( Restrictions.like("firstname", "G%"), Restrictions.like("lastname", "K%") ), Restrictions.in("email", emails) ) ); The second option is to use Restrictions.disjunction() together with Restrictions.conjunction() : session.createCriteria(User.class) .add( Restrictions.disjunction() .add( Restrictions.conjunction() .add( Restrictions.like("firstname", "G%") ) .add( Restrictions.like("lastname", "K%") ) ) .add( Restrictions.in("email", emails) ) ); Querying with criteria and example 669 We think both these options are ugly, even after spending five minutes trying to format them for maximum readability. JDK 5.0 static imports can help improve readability considerably, but even so, unless you’re constructing a query on the fly, the HQL or JPA QL string is much easier to understand. You may have noticed that many standard comparison operators (less than, greater than, equals, and so on) are built into the Criteria API, but certain oper- ators are missing. For example, any arithmetic operators such as addition and division aren’t supported directly. Another issue is function calls. Criteria has built-in functions only for the most common cases such as string case-insensitive matching. HQL, on the other hand, allows you to call arbitrary SQL functions in the WHERE clause. The Criteria API has a similar facility: You can add an arbitrary SQL expres- sion as a Criterion . Adding arbitrary SQL expressions Let’s assume you want to test a string for its length and restrict your query result accordingly. The Criteria API has no equivalent to the LENGTH() function in SQL, HQL, or JPA QL. You can, however, add a plain SQL function expression to your Criteria : session.createCriteria(User.class) .add( Restrictions.sqlRestriction( "length({alias}.PASSWORD) < ?", 5, Hibernate.INTEGER ) ); This query returns all User objects that have a password with less than 5 charac- ters. The {alias} placeholder is needed to prefix any table alias in the final SQL; it always refers to the table the root entity is mapped to ( USERS in this case). You also use a position parameter (named parameters aren’t supported by this API) and specify its type as Hibernate.INTEGER . Instead of a single bind argument and type, you can also use an overloaded version of the sqlRestriction() method that supports arrays of arguments and types. This facility is powerful—for example, you can add an SQL WHERE clause subse- lect with quantification: session.createCriteria(Item.class) .add( Restrictions.sqlRestriction( "'100' > all" + " ( select b.AMOUNT from BID b" + 670 CHAPTER 15 Advanced query options " where b.ITEM_ID = {alias}.ITEM_ID )" ) ); This query returns all Item objects which have no bids greater than 100. (The Hibernate criteria query system is extensible: You could also wrap the LENGTH() SQL function in your own implementation of the Criterion interface.) Finally, you can write criteria queries that include subqueries. Writing subqueries A subquery in a criteria query is a WHERE clause subselect. Just like in HQL, JPA QL, and SQL, the result of a subquery may contain either a single row or multiple rows. Typically, subqueries that return single rows perform aggregation. The following subquery returns the total number of items sold by a user; the outer query returns all users who have sold more than 10 items: DetachedCriteria subquery = DetachedCriteria.forClass(Item.class, "i"); subquery.add( Restrictions.eqProperty("i.seller.id", "u.id")) .add( Restrictions.isNotNull("i.successfulBid") ) .setProjection( Property.forName("i.id").count() ); Criteria criteria = session.createCriteria(User.class, "u") .add( Subqueries.lt(10, subquery) ); This is a correlated subquery. The DetachedCriteria refers to the u alias; this alias is declared in the outer query. Note that the outer query uses a less than oper- ator because the subquery is the right operand. Also note that i.seller.id does not result in a join, because SELLER_ID is a column in the ITEM table, which is the root entity for that detached criteria. Let’s move on to the next topic about criteria queries: joins and dynamic fetching. 15.1.2 Joins and dynamic fetching Just like in HQL and JPA QL, you may have different reasons why you want to express a join. First, you may want to use a join to restrict the result by some prop- erty of a joined class. For example, you may want to retrieve all Item instances that are sold by a particular User . Of course, you also want to use joins to dynamically fetch associated objects or collections, as you’d do with the fetch keyword in HQL and JPA QL. In criteria queries you have the same options available, with a FetchMode . Querying with criteria and example 671 We first look at regular joins and how you can express restrictions that involve associated classes. Joining associations for restriction There are two ways to express a join in the Criteria API; hence there are two ways in which you can use aliases for restriction. The first is the createCriteria() method of the Criteria interface. This basically means you can nest calls to cre- ateCriteria() : Criteria itemCriteria = session.createCriteria(Item.class); itemCriteria.add( Restrictions.like("description", "Foo", MatchMode.ANYWHERE) ); Criteria bidCriteria = itemCriteria.createCriteria("bids"); bidCriteria.add( Restrictions.gt( "amount", new BigDecimal(99) ) ); List result = itemCriteria.list(); You usually write the query as follows (method chaining): List result = session.createCriteria(Item.class) .add( Restrictions.like("description", "Foo", MatchMode.ANYWHERE) ) .createCriteria("bids") .add( Restrictions.gt("amount", new BigDecimal(99) ) ) .list(); The creation of a Criteria for the bids of the Item results in an inner join between the tables of the two classes. Note that you may call list() on either Criteria instance without changing the query result. Nesting criteria works not only for collections (such as bids ), but also for single-valued associations (such as seller ): List result = session.createCriteria(Item.class) .createCriteria("seller") .add( Restrictions.like("email", "%@hibernate.org") ) .list(); This query returns all items that are sold by users with a particular email address pattern. 672 CHAPTER 15 Advanced query options The second way to express inner joins with the Criteria API is to assign an alias to the joined entity: session.createCriteria(Item.class) .createAlias("bids", "b") .add( Restrictions.like("description", "%Foo%") ) .add( Restrictions.gt("b.amount", new BigDecimal(99) ) ); And the same for a restriction on a single-valued association, the seller : session.createCriteria(Item.class) .createAlias("seller", "s") .add( Restrictions.like("s.email", "%hibernate.org" ) ); This approach doesn’t use a second instance of Criteria ; it’s basically the same alias assignment mechanism you’d write in the FROM clause of an HQL/JPA QL statement. Properties of the joined entity must then be qualified by the alias assigned in createAlias() method, such as s.email . Properties of the root entity of the criteria query ( Item ) may be referred to without the qualifying alias, or with the alias "this" : session.createCriteria(Item.class) .createAlias("bids", "b") .add( Restrictions.like("this.description", "%Foo%") ) .add( Restrictions.gt("b.amount", new BigDecimal(99) ) ); Finally, note that at the time of writing only joining of associated entities or collec- tions that contain references to entities (one-to-many and many-to-many) is sup- ported in Hibernate with the Criteria API. The following example tries to join a collection of components: session.createCriteria(Item.class) .createAlias("images", "img") .add( Restrictions.gt("img.sizeX", 320 ) ); Hibernate fails with an exception and tells you that the property you want to alias doesn’t represent an entity association. We think this feature will likely be imple- mented by the time you read this book. Another syntax that is also invalid, but that you may be tempted to try, is an implicit join of a single-valued association with the dot notation: session.createCriteria(Item.class) .add( Restrictions.like("seller.email", "%hibernate.org") ); The "seller.email" string isn’t a property or a component’s property path. Cre- ate an alias or a nested Criteria object to join this entity association. Let’s discuss dynamic fetching of associated objects and collections. Querying with criteria and example 673 Dynamic fetching with criteria queries In HQL and JPA QL, you use the join fetch operation to eagerly fill a collection or to initialize an object that is mapped as lazy and would otherwise be proxied. You can do the same using the Criteria API: session.createCriteria(Item.class) .setFetchMode("bids", FetchMode.JOIN) .add( Restrictions.like("description", "%Foo%") ); This query returns all Item instance with a particular collection and eagerly loads the bids collection for each Item . A FetchMode.JOIN enables eager fetching through an SQL outer join. If you want to use an inner join instead (rare, because it wouldn’t return items that don’t have bids), you can force it: session.createCriteria(Item.class) .createAlias("bids", "b", CriteriaSpecification.INNER_JOIN) .setFetchMode("b", FetchMode.JOIN) .add( Restrictions.like("description", "%Foo%") ); You can also prefetch many-to-one and one-to-one associations: session.createCriteria(Item.class) .setFetchMode("bids", FetchMode.JOIN) .setFetchMode("seller", FetchMode.JOIN) .add( Restrictions.like("description", "%Foo%") ); Be careful, though. The same caveats as in HQL and JPA QL apply here: Eager fetching more than one collection in parallel (such as bids and images ) results in an SQL Cartesian product that is probably slower than two separate queries. Limit- ing the resultset for pagination, if you use eager fetching for collections, is also done in-memory. However, dynamic fetching with Criteria and FetchMode is slightly different than in HQL and JPA QL: A Criteria query doesn’t ignore the global fetching strategies as defined in the mapping metadata. For example, if the bids collection is mapped with fetch="join" or FetchType.EAGER , the following query results in an outer join of the ITEM and BID table: session.createCriteria(Item.class) .add( Restrictions.like("description", "%Foo%") ); The returned Item instances have their bids collections initialized and fully loaded. This doesn’t happen with HQL or JPA QL unless you manually query with LEFT JOIN FETCH (or, of course, map the collection as lazy="false" , which results in a second SQL query). [...]... mapping options are the same Java Persistence standardizes JPA QL and also allows the fallback to native SQL 15.2.3 Native SQL in Java Persistence Java Persistence supports native SQL queries with the createNativeQuery() method on an EntityManager A native SQL query may return entity instances, scalar values, or a mix of both However, unlike Hibernate, the API in Java Persistence utilizes mapping metadata...  696 CHAPTER 15 Advanced query options Table 15.1 shows a summary you can use to compare native Hibernate features and Java Persistence Table 15.1 Hibernate and JPA comparison chart for chapter 15 Hibernate Core Java Persistence and EJB 3.0 Hibernate supports a powerful Criteria and Example API for programmatic query generation Some QBC and QBE API is expected in an upcoming version of the standard Hibernate. .. flexible mapping options for embedded and externalized SQL queries, with automatic marshaling of resultsets Java Persistence standardizes SQL embedding and mapping and supports resultset marshaling Hibernate supports a collection filter API Java Persistence doesn’t standardize a collection filter API Hibernate can cache query results A Hibernate- specific query hint can be used to cache query results In... design and architecture of applications with Hibernate, Java Persistence, and EJB 3.0 components We’ll also unit test a Hibernate application Creating and testing layered applications This chapter covers ■ Creating layered applications ■ Managed components and services ■ Strategies for integration testing 697 698 CHAPTER 16 Creating and testing layered applications Hibernate is intended to be used in... architectural scenario imaginable Hibernate may run inside a servlet container; you can use it with web application framework like Struts, WebWork, or Tapestry, or inside an EJB container, or to manage persistent data in a Java Swing application Even—perhaps especially with all these options, it’s often difficult to see exactly how Hibernate should be integrated into a particular Java- based architecture Inevitably,... to integrate Hibernate in a typical layered application We assume that you want to write a simple web application with Java servlets We need a simple use case of the CaveatEmptor application to demonstrate these ideas 16.1.1 Introducing the use case When a user places a bid on an item, CaveatEmptor must perform the following tasks, all in a single request: Hibernate in a web application 699 1 Check that... This is the key we already isolated as perfect for the 694 CHAPTER 15 Advanced query options implementation of a good equals() object equality routine You can find examples of such keys in “Implementing equality with a business key,” in chapter 9, section 9. 2.3 Usually, you map the attributes that form your natural key as regular properties in Hibernate You may enable a unique constraint at the database... caching for a javax .persistence. Query, use setHint("org .hibernate. cacheable", true)  692 CHAPTER 15 Advanced query options 15.4.2 Understanding the query cache When a query is executed for the first time, its results are cached in a cache region—this region is different from any other entity or collection cache region you may already have configured The name of the region is by default org .hibernate. cache.QueryCache... be enabled using a Hibernate configuration property: hibernate. cache.use_query_cache = true However, this setting alone isn’t enough for Hibernate to cache query results By default, all queries always ignore the cache To enable query caching for a particular query (to allow its results to be added to the cache, and to allow it to draw its results from the cache), you use the org .hibernate. Query interface... AliasToBeanResultTransformer(ItemPriceSummary.class) ); The ItemPriceSummary is a simple Java bean with setter methods or public fields named itemId, itemDescription, and itemInitialPrice It doesn’t have to be a mapped persistent class; only the property/field names must match with the aliases assigned to the projected properties in the criteria query Aliases are assigned with the as() method (which you can think of as the equivalent . it’s also only available as a native Hibernate API; Java Persistence doesn’t (yet) standardize a program- matic query interface. Both Hibernate and Java Persistence support queries written in. feature. Let’s start with query by criteria and query by example. 15.1 Querying with criteria and example The Criteria and Example APIs are available in Hibernate only; Java Persistence doesn’t. example you bound the string "foo @hibernate. org" to the query; you can bind any java. lang.Object and let Hibernate figure out what to do with it. The unique- Result() method executes