This is the genesis of openutils-mgnlcriteria.
Criteria is a simplified API for retrieving JCR Nodes by composing
Criterion objects. This is a very convenient approach for functionality like "search" screens where there is a variable number of conditions to be placed upon the result set.
JCRCriteriaFactory is a factory for
Criterion instances are usually obtained via the factory methods on
openutils-mgnlcriteria API is blatantly inspired by Hibernate's Criteria API.
openutils-mgnlcriteria requires JDK 1.5.x or superior
People already familiar with Hibernate's Criteria will find almost no difference (type names and methods have been kept the same on purpose, whenever possible): you create a
Criteria object with one of the static methods in
JCRCriteriaFactory and start adding
Restrictions and a final optional
Order. Then you call the
list() method to get your
Collection of results (that is instances of
info.magnolia.cms.core.Content). As in Hibernate's Criteria, method chaining is supported. Here is an example:
All this will be translated into the following xpath statement
You can also specify a different type to be returned in the Collection of results. eg.
Internally, this will use
info.magnolia.content2bean.Content2BeanUtil.toBean() to transform nodes into beans.
So, for example, if you have a domain
Pet class like this
Content nodes returned by the above query will be automatically converted to and populate instances of the
Furthermore, you may want to have only a subset of the whole resultset returned, much like in a MySQL limit clause. In this case, you will use the
JCRCriteriaFactory.createMgnlCriteriaWithLimit factory method. For this to work, the underlying JCR repository implementation must support this feature (Jackrabbit 1.4+ does).
Here is an example.
setMaxResults(int) methods. Now calling
list() will return a subset of only five
Pet objects, starting from the 6th item (counting starts from 0). If you dont specify these two calls,
list() will behave as usual by returning the entire result set. If you only call
setMaxResults(int), the result set will be the subset of elements
(0, maxResults) (firstResultValue is 0 by default).
A word of warning about implementations returned by
JCRCriteriaFactory. They are NOT thread-safe, therefore client code wishing to use one of them as a shared global variable MUST coordinate access to it. These objects are actually meant to be instantiated and used within a method scope (e.g. a service method), where no concurrent issues arise.
Finally, it is good to know that openutils-mgnlcriteria API catches all checked exceptions thrown by JCR and Magnolia and wraps them into its own runtime
net.sourceforge.openutils.mgnlcriteria.jcr.query.JCRQueryException, leaving to the API user the choice whether to catch it or not and, when needed, get to the original cause of error.
You can check out the openutils-mgnlcriteria from sourceforge svn (sorry, no Maven artifacts yet) here https://openutils.svn.sourceforge.net/svnroot/openutils/trunk/openutils-mgnlcriteria or, if you are using Maven, you can include it in your project as a dependency with the following snippet
See here for the latest artifact version http://mvnrepository.com/artifact/net.sourceforge.openutils/openutils-mgnlcriteria/