How do you create a basic criteria object and use it to load data from a database?

As with HQL, you get the criteria object from the session. If you don't have a session to create a criteria object, then you can use DetachedCriteria. This DetachedCriteria object is later used with the session to get the results. This recipe demonstrates the basic implementation of the Criteria API.

A basic Criteria query looks like this:

Criteria criteria = session.createCriteria(Book.class)
List books = criteria.list();

This query corresponds to the following HQL query:

from Book book

Most methods in the Criteria class return an instance of themselves, so you can build up your criteria as follows. Here you add a restriction to your criteria, which says that the name of the book should be equal to "Hibernate Quickly":

Criteria criteria = session.createCriteria(Book.class)
.add(Restrictions.eq("name", "Hibernate Quickly"));
List books = criteria.list();

If you don't have an open session, you can instantiate a detached criteria by using the forClass() method and later attach it to a session for execution. When you have a session to run the query, you call getExecutableCriteria() and pass the session as a method argument. The getExecutableCriteria() method returns an executable instance of criteria:

DetachedCriteria criteria = DetachedCriteria.forClass(Book.class);
List books = criteria.getExecutableCriteria(session).list();

How do you filter data when using criteria? How do you apply restriction to criteria?

You can add a series of restrictions to your Criteria query to filter the results, just as you build up the where clause in HQL. The Restrictions class provides a variety of methods to build restrictions.

Each restriction you add is treated as a logical conjunction. The Criterion interface is an object-oriented representation of a query criterion that may be used as a restriction in a Criteria query. The Restrictions class provides static factory methods that return built-in criterion types. The org.hibernate.criterion package provides an API for creating complex queries:

Criteria criteria = session.createCriteria(Book.class);
Criterion nameRest = Restrictions.eq("name", "Hibernate Recipes");
criteria.add(nameRest);
List books = criteria.list();

This is equivalent to the following HQL:

from Book book where name='Hibernate Recipes'

eq is an equals implementation that takes two input method arguments: the name of the property of the Book class and the value to be compared with. To get a unique result, you can use the uniqueResult() method:

Criteria criteria = session.createCriteria(Book.class);
Criterion nameRest = Restrictions.eq("name", "Hibernate Recipes");
criteria.add(nameRest);
Book book = (Book)criteria.uniqueResult();

You can use the ignoreCase() method to add case insensitivity to the query:

Criterion nameRest = Restrictions.eq("name", "Hibernate Recipes").ignoreCase();

The Restrictions class has many other methods, including the following:

Here's an example:

Criteria criteria = session.createCriteria(Book.class)
        .add(Restrictions.like("name", "%Hibernate%"))
        .add(Restrictions.between("price", new Integer(100), new Integer(200)));
List books = criteria.list();

This Criteria query corresponds to the following HQL query:

from Book book
where (book.name like '%Hibernate%') and (book.price between 100 and 200)

The % character is a wildcard. Because it's added before and after the word Hibernate, it enables you to search for all books that have the word Hibernate in a book name. If you want to look for all books whose name starts with Hibernate, the query is as follows:

Criteria criteria = session.createCriteria(Book.class)
        .add(Restrictions.like("name", "Hibernate%"))
.add(Restrictions.between("price", new Integer(100), new Integer(200)));
List books = criteria.list();

Notice that there is no % character before the word Hibernate in the search string. You can also group some of the restrictions with logical disjunction. How do you achieve the following query using the Criteria API?

from Book book
where (book.name like '%Hibernate%' or book.name like '%Java%') and (book.price between 100
and 200)

You can directly translate it into something like this:

Criteria criteria = session.createCriteria(Book.class)
        .add(Restrictions.or(
                        Restrictions.like("name", "%Hibernate%"),
                        Restrictions.like("name", "%Java%")
                )

)
.add(Restrictions.between("price", new Integer(100), new Integer(200)));
List books = criteria.list();

This query can also be written using Restrictions' disjunction() method:

Criteria criteria = session.createCriteria(Book.class)
                .add(Restrictions.disjunction()
                                .add(Restrictions.like("name", "%Hibernate%"))
                                .add(Restrictions.like("name", "%Java%"))
                )
                .add(Restrictions.between("price", new Integer(100), new Integer(200)));
List books = criteria.list();

If you want to search using wildcards, you can use the MatchMode class. It provides a convenient way to express a substring match without using string manipulation:

Criteria criteria = session.createCriteria(Book.class);
Criterion nameRest = Restrictions.like("name", "Hibernate",MatchMode.START);
criteria.add(nameRest);
Book books = (Book)criteria.uniqueResult();

This Criteria statement is the same as

Criterion nameRest = Restrictions.like("name", "Hibernate%");

The following MatchMode values are available:

select publisher_name, address from Publisher pub where pub.code=(select publisher_code from Book book where book.publish_date=current_timestamp)

DetachedCriteria todaysBook = DetachedCriteria.forClass(Book.class)
.setProjection( (Projection) Property.forName("publishDate").eq("current_timestamp") );
List =manager.createCriteria(Publisher.class)
            .add( Property.forName("publisherCode").eq(todaysBook) )
            .list();

How do you express a join restriction using the Criteria API when there are associated objects? How do you use dynamic fetching?

When you have associated objects, you need to join them in order to retrieve data from them. In HQL, you use an alias and an equijoin on the foreign key in the where clause:

from Book b, Publisher p where b.publisherId = p.publisherId

This query joins the Publisher object and Book object with publisherId, which is the foreign key in Book.

Let's see how this is achieved using the Criteria API. Hibernate provides two methods to enable joining of associated entities: createCriteria() and createAlias(). The difference between the two is that createCriteria() returns a new instance of Criteria. It means you can nest calls to createCriteria(). The createAlias() method doesn't create a new instance of Criteria and is very similar to the alias you declare in the HQL from clause.

You can reference an association property by its name to trigger an implicit join. For example, suppose you have an Order class that contains a Price object, which holds details as unitPrice and currency:

public class Order {

        Price price;
}

public class Price {

                String currency;
                float unitPrice;
}

If you need to fetch the unitPrice of an Order, you can use Order.price.unitPrice in HQL:

from Order order where order.price.unitPrice > 50

Can the same implicit join work using Criteria?

Criteria criteria = session.createCriteria(Book.class,"book")
.add(Restrictions.like("name", "%Hibernate%"))
.add(Restrictions.eq("book.publisher.name", "Manning"));
List books = criteria.list();

If you execute this code, the following exception is thrown:

Exception in thread "main" org.hibernate.QueryException: could not resolve property:

publisher.name of: com.hibernaterecipes.chapter5.Book
    at
org.hibernate.persister.entity.AbstractPropertyMapping.propertyException(AbstractPropertyMapping.java:67)

Hibernate can't resolve the property publisher.name. That means an implicit join isn't supported for Criteria queries. To join an association explicitly, you need to create a new criteria object for it:

Criteria criteria = session.createCriteria(Book.class)
        .add(Restrictions.like("name", "%Hibernate%"))
        .createCriteria("publisher")
        .add(Restrictions.eq("name", "Manning"));
List books = criteria.list();

In this example, the createCriteria() method has a string attribute, where you pass the name of the associated property. Because you're creating a criteria on the publisher property of the Book object, you need to pass "publisher" in this case. You can also use createAlias() to generate the same query:

Criteria criteria = session.createCriteria(Book.class)
                .createAlias("publisher", "publisherAlias")
                .add(Restrictions.like("name", "%Hibernate%"))
                .add(Restrictions.eq("publisherAlias.name", "Manning"));
                List books = criteria.list();

In HQL, the query is as follows:

from Book book
where book.name like '%Hibernate%' and book.publisher.name = 'Manning'

As in HQL, you can specify the fetching strategy that Hibernate should follow when it loads data in case of associations. This strategy can also be set in the metadata configuration file. If the configuration needs to be overridden, then you can use the FetchMode API when you retrieve data using Criteria.

Following are the FetchMode options are available:

The following code uses the FetchMode.JOIN and FetchMode.SELECT options:

Criteria criteria = session.createCriteria(Book.class)
.add(Restrictions.like("name", "%Hibernate%"))
.setFetchMode("publisher", FetchMode.JOIN)
.setFetchMode("chapters", FetchMode.SELECT);
List books = criteria.list();

In this case, the associated Publisher object is fetched using an outer join, where Chapters is retrieved with a second SELECT query.

What are projections, and how do you use them in the Criteria API?

Until now, when you retrieved objects using Criteria, you fetched the complete object in the result set. What if you want to fetch only certain fields or columns in a table, and you don't want the complete object?

Projections help you filter data and return only those fields you need. You can use projections when you don't want the entire fetched entity and its associations. You can also use them when there is a requirement to get the results in a flat manner (not in an object graph). This approach improves performance, especially when you're dealing with lot of columns and the object graph is very deep.

To customize the fields of the result, you can use projections to specify the fields to be returned:

Criteria criteria = session.createCriteria(Book.class)
.setProjection(Projections.property("name"));
List books = criteria.list();

This is similar to the following SQL statement:

select book.name from Book book

This is better than

from Book book

which fetches the complete book object although you need only the book name.

select min(book.price) from Book book

Criteria criteria = session.createCriteria(Book.class)
.setProjection(Projections.avg("price"));
List books = criteria.list();

select avg(book.price) from Book book

Criteria criteria = session.createCriteria(Book.class)
.addOrder(Order.asc("name"))
.addOrder(Order.desc("publishDate"));
List books = criteria.list();

from Book book
order by book.name asc, book.publishDate desc

Criteria criteria = session.createCriteria(Book.class)
.setProjection(Projections.projectionList()

.add(Projections.groupProperty("publishDate"))
.add(Projections.avg("price")));
List books = criteria.list();

select book.publishDate, avg(book.price)
from Book book
group by book.publishDate

What is Query by Example (QBE), and how do you use it to retrieve data?

Suppose you need to retrieve data based on different input. The search criteria can be complex filtering data on various columns. Using Criteria, it might look like this:

Criteria criteria = getSession().createCriteria(Book.class);
        criteria.add(Restrictions.eq("name", "Hibernate")).
                add(Restrictions.eq("price",100))

If you have more columns to be filtered, the list increases. QBE makes this easy for you.

QBE returns a result set depending on the properties that were set on an instance of the queried class. You can also specify the properties that need to be excluded. This approach greatly reduces the amount of code you have to write.

Criteria queries can be constructed through an Example object. The object should be an instance of the persistent class you want to query. All null properties are ignored by default:

Book book = new Book();
book.setName("Hibernate");
book.setPrice(new Integer(100));
Example exampleBook = Example.create(book);
Criteria criteria = session.createCriteria(Book.class)
.add(exampleBook);
List books = criteria.list();

The HQL is similar to the following:

from Book book

where book.name = 'Hibernate' and book.price = 100

In this example, the instance of Book is created, and the search criteria are set: they include name and price. This Book instance is then passed while creating an Example object. Finally, the Criteria interface accepts the Example instance to retrieve the data based on the values set on the Book instance.

You can specify creation rules for the construction of the Example object. For example, you can exclude some of the properties or enable like for a string comparison:

Book book = new Book();
book.setName("%Hibernate%");
book.setPrice(new Integer(100));
Example exampleBook = Example.create(book)
.excludeProperty("price")
.enableLike();
Criteria criteria = session.createCriteria(Book.class)
.add(exampleBook);
List books = criteria.list();

The corresponding HQL is as follows:

from Book book
where book.name like '%Hibernate%'