JBoss Community Archive (Read Only)


Criteria Overview

The Criteria API is a a powerful mechanism for creating ad-hoc queries against the domain entities and composites. It is the preferred mechanism for fetching data unless there is some overriding reason to use a more direct mechanism, such as a NamedQuery.

You'll find that many of the Remote API classes offer remote methods named findXxxByCriteria(Subject, XxxCriteria), or something very close. The XxxCriteria classes all extend Criteria and they all have some similarities. They all:

There are more design details here: Criteria Design.


Although powerful, there are subtle pitfalls if you're not careful. Here are several things to be aware of.

Paging is active by default and will limit your results to 200 entries!

This is very important. This protects against an accidental fetch of a huge data-set. But it also surprises users when they don't see all the data they expect.

If you are positive the data-set will be manageable in a single fetch, you can call Criteria.clearPaging() to fetch an unlimited set.

If you need paging but don't like the defaults, you can call Criteria methods to override them.

If you want to easily support paging, see the CriteriaQuery wrapper class.

The CriteriaQuery wrapper class helps with paging

This class offers a simple way to iterate through a large data-set using the paging and sorting defined in your Criteria object. Note that with any
repeated searching of the database, changes to the underlying database tables can affect the results.

String searches are fuzzy by default!

This is very important. For any String filter, unless documented otherwise, the supplied filter String will be treated as substring matching. This can lead to more results than expected. Be very careful when using name-filters and the like, when it's very possible you want exact match.

If you need exact match String filtering then call Criteria.setStrict(true).

Note that the strict match setting is applied to all String filters in the Criteria.

String searches are case-INsensitive by default!

If you need case-sensitive searching, or you just want to be more efficient, then call Criteria.setCaseSensitive(true).

Building the Criteria queries has overhead - Performance Alert!

Criteria queries have great flexibility but remember that the ad-hoc nature of the querying means that the queries are assembled at call-time. Calling a fetchXxxByCriteria() method in a tight loop can be expensive. In certain situations it will be better to use existing lightweight convenience methods, like a getById(int id) method. Or, to add specific prepared statements/named queries, as needed.

As an aside, when working on SLSB code, remember that inter-EJB calling has transaction overhead. And repeating a lot of the same Authz checks can also slow things down considerably.

Beware of Criteria Class defaults!

Several Criteria classes have default filters enabled. Make sure you look at the jdoc, or in some cases it's helpful to look at the class itself. For example, ResourceCriteria will, by default, limit your results to COMMITTED resources. To get back resources with any InventoryStatus you need to disable the filter:


Use getSingleResult()

Since RHQ 4.6.

If you expect one and only one result object from your fetch, it's wise to wrap your call in a call to getSingleResult(). This will give you protection from unexpected result sets, analogous to what Query.getSingleResult() does in JPA.

ResourceCriteria c = new ResourceCriteria();
// This will thrown a RuntimeException if the call results in anything but one Resource
Resource r = ResourceCriteria.getSingleResult(resourceManager.findResourcesByCriteria(c));
JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-11 13:01:09 UTC, last content change 2013-02-11 17:26:23 UTC.