The first thing we need to figure out is how to specify the kind of object we’re interested in retrieving. There is no query language involved in building criteria queries. Instead, you build up a tree of Criteria objects describing what you want. The Hibernate Session acts as a factory for these criteria, and you start, conveniently enough, by specifying the type of objects you want to retrieve.

Edit QueryTest.java, replacing the contents of the tracksNoLongerThan() method with those shown in Example 8-1.

public static List tracksNoLongerThan(Time length, Session session) {
    Criteria criteria = session.createCriteria(Track.class);
    return criteria.list();
}

The session’s createCriteria() method builds a criteria query that will return instances of the persistent class you supply as an argument—easy enough. If you run the example at this point, of course, you’ll see all the tracks in the database, since we haven’t gotten around to expressing any actual criteria to limit our results yet (see Example 8-2).

% ant qtest
...
qtest:
     [java] Track: "Russian Trance" (PPK) 00:03:30, from Compact Disc
     [java] Track: "Video Killed the Radio Star" (The Buggles) 00:03:49, from VH
S Videocassette tape
     [java] Track: "Gravity's Angel" (Laurie Anderson) 00:06:06, from Compact Di
sc
     [java] Track: "Adagio for Strings (Ferry Corsten Remix)" (Ferry Corsten, Wi
lliam Orbit, Samuel Barber) 00:06:35, from Compact Disc
     [java] Track: "Adagio for Strings (ATB Remix)" (William Orbit, ATB, Samuel 
Barber) 00:07:39, from Compact Disc
     [java] Track: "The World '99" (Ferry Corsten, Pulp Victim) 00:07:05, from D
igital Audio Stream
     [java] Track: "Test Tone 1" 00:00:10
     [java]   Comment: Pink noise to test equalization

OK, easy enough. How about picking the tracks we want? Also easy! Add a new import statement at the top of the file:

import org.hibernate.criterion.*;

Then just add one more line to the method, as shown in Example 8-3.

public static List tracksNoLongerThan(Time length, Session session) {
    Criteria criteria = session.createCriteria(Track.class);
    criteria.add(Restrictions.le("playTime", length));
    return criteria.list();
}

The Restrictions class acts as a factory for obtaining Criterion instances that can specify different kinds of constraints on your query. Its le() method creates a criterion that constrains a property to be less than or equal to a specified value. In this case we want the Track’s playTime property to be no greater than the value passed in to the method. We add this to our set of desired criteria.

We’ll look at some other Criterion types available through Restrictions in the next section. Appendix B lists them all, and you can create your own implementations of the Criterion interface if you’ve got something new you want to support.

Running the query this time gives us just the tracks that are no more than seven minutes long, as requested by the main() method (see Example 8-4).

% ant qtest
...
qtest:
     [java] Track: "Russian Trance" (PPK) 00:03:30, from Compact Disc
     [java] Track: "Video Killed the Radio Star" (The Buggles) 00:03:49, from VH
S Videocassette tape
     [java] Track: "Gravity's Angel" (Laurie Anderson) 00:06:06, from Compact Di
sc
     [java] Track: "Adagio for Strings (Ferry Corsten Remix)" (Ferry Corsten, Sa
muel Barber, William Orbit) 00:06:35, from Compact Disc
     [java] Track: "Test Tone 1" 00:00:10
     [java]   Comment: Pink noise to test equalization

A surprising number of the queries used to retrieve objects in real applications are very simple, and criteria queries are an extremely natural and compact way of expressing them in Java. Our new tracksNoLongerThan() method is actually shorter than it was in Example 3-12, and that version required a separate query (Example 3-11) to be added to the mapping document, as well! Both approaches lead to the same patterns of underlying database access, so they are equally efficient at runtime.

If possible, however, to make the code even more compact. The add() and createCriteria() methods return the Criteria instance, so you can continue to manipulate it in the same Java statement. Taking advantage of that, we can boil the method down to the version shown in Example 8-5.

public static List tracksNoLongerThan(Time length, Session session) {
    return session.createCriteria(Track.class).
        add(Restrictions.le("playTime", length)).list();
}

The style you choose is a trade-off between space and readability (although some people may find the compact, run-on version even more readable).

…sorting the list of results, or retrieving a subset of all matching objects? Like the Query interface, the Criteria interface lets you limit the number of results you get back (and choose where to start) by calling setMaxResults() and setFirstResult() as well as a variety of other scrolling and manipulation methods. It also lets you control the order in which results are returned (which you’d do using an order by clause in an HQL query), as shown in Example 8-6.

public static List tracksNoLongerThan(Time length, Session session) {
    Criteria criteria = session.createCriteria(Track.class);
    criteria.add(Restrictions.le("playTime", length));
    criteria.addOrder(Order.asc("title").ignoreCase());
    return criteria.list();
}

The Order class is just a way of representing orderings. It has two static factory methods, asc() and desc(), for creating ascending or descending orderings respectively. Each takes the name of the property to be sorted. If you call the ignoreCase() method on an Order instance, it will sort capital and lowercase letters together, which is often what you want for display. The results of running this version are in Example 8-7.

% ant qtest
...
qtest:
     [java] Track: "Adagio for Strings (Ferry Corsten Remix)" (Ferry Corsten, Sa
muel Barber, William Orbit) 00:06:35, from Compact Disc
     [java] Track: "Gravity's Angel" (Laurie Anderson) 00:06:06, from Compact Di
sc
     [java] Track: "Russian Trance" (PPK) 00:03:30, from Compact Disc
     [java] Track: "Test Tone 1" 00:00:10
     [java]   Comment: Pink noise to test equalization
     [java] Track: "Video Killed the Radio Star" (The Buggles) 00:03:49, from VH
S Videocassette tape

You can add more than one Order to the Criteria, and it will sort by each of them in turn (the first gets priority, and then if there are any results with the same value for that property, the second ordering is applied to them, and so on).

Example 8-13 shows a method that uses the projection capability of the criteria API to achieve this.

/**
 * Retrieve the titles of any tracks that contain a particular text string.
 *
 * @param text the text to be matched, ignoring case, anywhere in the title.
 * @param session the Hibernate session that can retrieve data.
 * @return the matching titles, as strings.
 */
public static List titlesContainingText(String text, Session session) {
    Criteria criteria = session.createCriteria(Track.class);
    criteria.add(Restrictions.like("title", text, MatchMode.ANYWHERE). 
            ignoreCase());
    criteria.setProjection(Projections.property("title")); 
    return criteria.list();
}

So this method, like our other criteria queries, returns a List. But a list of what, exactly? The criteria are created on the Track class, but it wouldn’t make sense to construct and return Track objects since we are only retrieving the title property. In fact, in situations like this where you project on a single property, you get a list of whatever class is associated with that property.

In this case, since it is a string property, you get a List of String instances.

We can easily check this by adding this method to QueryTest.java and changing main() to call it as follows:

System.out.println(titlesContainingText("v", session));

Running this version produces the following output:

qtest:
     [java] [Video Killed the Radio Star, Gravity's Angel]

It should be clear that projections can retrieve a different property than the one(s) you use in the restrictions. If we retrieved the track lengths instead, like so:

criteria.setProjection(Projections.property("playTime"));

we’d get this output:

qtest:
     [java] [00:03:49, 00:06:06]

Of course, the method name would be wrong then, and the output is kind of cryptic. What if we wanted to retrieve both the titles and lengths? It turns out that’s almost as easy, as shown in Example 8-14.

/**
 * Retrieve the titles and play times of any tracks that contain a
 * particular text string.
 * 
 * @param text the text to be matched, ignoring case, anywhere in the title.
 * @param session the Hibernate session that can retrieve data.
 * @return the matching titles and times wrapped in object arrays.
 */
public static List titlesContainingTextWithPlayTimes(String text,
                                                     Session session) {
    Criteria criteria = session.createCriteria(Track.class);
    criteria.add(Restrictions.like("title", text, MatchMode.ANYWHERE)
            .ignoreCase());
    criteria.setProjection(Projections.projectionList(). 
            add(Projections.property("title")). 
            add(Projections.property("playTime")));
    return criteria.list();
}

The trickiest part here is what gets returned from the query. As always, it is a List, but now each element is going to contain more than one value, of potentially different types. Hibernate chooses to return a list of Object arrays. This makes the code for display somewhat more awkward:

for (Object o : titlesContainingTextWithPlayTimes("v", session)) {
    Object[] array = (Object[])o;
    System.out.println("Title: " + array[0] +
            " (Play Time: " + array[1] + ')'),
}

This produces the following output:

qtest:
     [java] Title: Video Killed the Radio Star (Play Time: 00:03:49)
     [java] Title: Gravity's Angel (Play Time: 00:06:06)

But really, the code is ugly; you’d never really use projection this way. The whole point of an object/relational mapping system is that you can just return the object, and then use that to get at the properties you want when you want more than one of them.

So, why would projection support multiple values? Well, there is actually a good reason, and it has to do with that notion of aggregation that we introduced at the start of this section. Most of the time you are interested in using projection, you will be getting values that aren’t directly object properties at all, but that are based on those properties. Example 8-15 shows a method that prints out, for each type of media represented in the database, the number of tracks that came from that media, and the longest play time of any track from that media.

/**
 * Print statistics about various media types.
 * 
 * @param session the Hibernate session that can retrieve data.
 */
public static void printMediaStatistics(Session session) {
    Criteria criteria = session.createCriteria(Track.class);
    criteria.setProjection(Projections.projectionList(). 
            add(Projections.groupProperty("sourceMedia")). 
            add(Projections.rowCount()). 
            add(Projections.max("playTime"))); 

    for (Object o : criteria.list()) { 
        Object[] array = (Object[])o;
        System.out.println(array[0] + " track count: " + array[1] +
                "; max play time: " + array[2]);
    }
}

This example builds on many of the things we’ve seen so far:

Setting up main() in QueryTest.java to call this method is simple:

printMediaStatistics(session);

And it produces the following output:

qtest:
     [java] CD track count: 4; max play time: 00:07:39
     [java] VHS track count: 1; max play time: 00:03:49
     [java] STREAM track count: 1; max play time: 00:07:05
     [java] null track count: 1; max play time: 00:00:10

That should give you a sense of the real value of projection and aggregation. (That null media type was our test tone.)

Notice that this output is not sorted in any particular order, though. We might want to do that, but how do you sort on a projection? To answer that we need to look at another refinement in the Criteria API. You can assign aliases to objects and properties with which you’re working (just as you can for tables and columns in database query languages), whether they come directly from the database, or from projection and aggregation. So to get things sorted nicely by source media, we need to start by adding an alias to our grouped property:

add(Projections.groupProperty("sourceMedia").as("media")).

This declares the alias media which we can then use for sorting, as we did previously with ordinary object properties:

 criteria.addOrder(Order.asc("media"));

With these changes, we see sorted output:

qtest:
     [java] null track count: 1; max play time: 00:00:10
     [java] CD track count: 4; max play time: 00:07:39
     [java] STREAM track count: 1; max play time: 00:07:05
     [java] VHS track count: 1; max play time: 00:03:49

There are other reasons for using aliases, and more things you can do with projection, but it’s time to look at other aspects of criteria. We’ll show you where you can learn more about all this at the end of the chapter.

Let’s suppose we’re interested in finding all the tracks associated with particular artists. We’d want our criteria to look at the values contained in each Track’s artists property, which is a collection of associations to Artist objects. Just to make it a bit more fun, let’s say we want to be able to find tracks associated with artists whose name property matches a particular substring pattern.

Let’s add a new method to QueryTest.java to implement this. Add the method shown in Example 8-16 after the end of the tracksNoLongerThan() method.

/**
 * Retrieve any tracks associated with artists whose name matches a SQL
 * string pattern.
 * 
 * @param namePattern the pattern which an artist's name must match
 * @param session the Hibernate session that can retrieve data.
 * @return a list of {@link Track}s meeting the artist name restriction.
 */
public static List tracksWithArtistLike(String namePattern, Session session)
{
    Criteria criteria = session.createCriteria(Track.class);
    Criteria artistCriteria = criteria.createCriteria("artists"); 
    artistCriteria.add(Restrictions.like("name", namePattern)); 
    artistCriteria.addOrder(Order.asc("name").ignoreCase()); 
    return criteria.list();
}

To see all this in action, we need to make one more change. Modify the main() method so that it invokes this new query, as shown in Example 8-17.

...
// Ask for a session using the JDBC information we've configured
Session session = sessionFactory.openSession();
try {
    // Print tracks associated with an artist whose name ends with "n"
    List tracks = tracksWithArtistLike("%n", session);
    for (ListIterator iter = tracks.listIterator() ;
...

Running ant qtest now gives the results shown in Example 8-18.

qtest:
     [java] Track: "The World '99" (Pulp Victim, Ferry Corsten) 00:07:05, from D
igital Audio Stream
     [java] Track: "Adagio for Strings (Ferry Corsten Remix)" (William Orbit, Sa
muel Barber, Ferry Corsten) 00:06:35, from Compact Disc
     [java] Track: "Gravity's Angel" (Laurie Anderson) 00:06:06, from Compact Di
sc

If you look at the lists of artists for each of the three tracks that were found, you’ll see that at least one of them has a name ending in “n” as we requested (they’re in bold type for easier recognition in this printing). Also notice that we have access to all the artists associated with each track, not just the ones that matched the name criterion. This is what you’d expect and want, given that we’ve retrieved the actual Track entities. You can run criteria queries in a different mode, by calling setResultTransformer(Criteria.ALIAS_TO_ENTITY_MAP), which causes it to return a list of hierarchical Maps in which the criteria at each level have filtered the results. This goes beyond the scope of this book, but there are some examples of it in the reference and API documentation.

Let’s add another query method to QueryTest.java. Add the code of Example 8-19 to the top of the class where the other queries are.

/**
 * Retrieve any tracks that were obtained from a particular source media
 * type.
 * 
 * @param media the media type of interest.
 * @param session the Hibernate session that can retrieve data.
 * @return a list of {@link Track}s meeting the media restriction.
 */
public static List tracksFromMedia(SourceMedia media, Session session) {
    Track track = new Track(); 
    track.setSourceMedia(media);
    Example example = Example.create(track); 

    Criteria criteria = session.createCriteria(Track.class); 
    criteria.add(example);
    criteria.addOrder(Order.asc("title"));
    return criteria.list();
}

Once again we need to modify the main() method to call our new query. Let’s find the tracks that came from CDs. Make the changes shown in Example 8-20.

...
// Ask for a session using the JDBC information we've configured
Session session = sessionFactory.openSession();
try {
    // Print tracks that came from CDs
    List tracks = tracksFromMedia(SourceMedia.CD, session);
    for (ListIterator iter = tracks.listIterator() ;
...

Running this version produces output like Example 8-21.

     [java] Track: "Adagio for Strings (ATB Remix)" (ATB, Samuel Barber, William
 Orbit) 00:07:39, from Compact Disc
     [java] Track: "Adagio for Strings (Ferry Corsten Remix)" (Samuel Barber, Wi
lliam Orbit, Ferry Corsten) 00:06:35, from Compact Disc
     [java] Track: "Gravity's Angel" (Laurie Anderson) 00:06:06, from Compact Di
sc
     [java] Track: "Russian Trance" (PPK) 00:03:30, from Compact Disc

As you might expect, you can use examples with subcriteria for associated objects, too. We could rewrite tracksWithArtistLike() so that it uses an example Artist rather than building its criterion “by hand.” We’ll need to call enableLike() on our example. Example 8-22 shows a concise way of doing this.

public static List tracksWithArtistLike(String namePattern, Session session)
{
    Criteria criteria = session.createCriteria(Track.class);
    Example example = Example.create(new Artist(namePattern, null, null));
    criteria.createCriteria("artists").add(example.enableLike()).addOrder(
        Order.asc("name").ignoreCase());
    return criteria.list();
}

This produces exactly the same output as when we were constructing the inner criteria “by hand.” Remember that if you want to try running this you’ll need to switch main() back to the way it was in Example 8-17.

A great variety of queries that power the user interface and general operation of a typical data-driven Java application can be expressed as criteria queries, and they provide advantages in readability, compile-time type checking, and even (surprisingly) compactness. As far as new database APIs go, I’d call this a winner.

…sneaking a little SQL in with your other criteria to take advantage of database-specific features or your mad DBA skillz? Using subqueries, or detached criteria that can be set up before you have a Hibernate session? Plugging in your own Java code to filter the results as the query is performed? All of these things and more are possible, but beyond the scope of this book. If you’re ready for them, the Advanced query options chapter in Java Persistence with Hibernate is a good overview, and the Hibernate JavaDoc and source code are the definitive references.