net.sourceforge.openutils.mgnlcriteria.jcr.query
Interface Criteria

All Superinterfaces:

ExecutableQuery

All Known Subinterfaces:

TranslatableCriteria

All Known Implementing Classes:

AbstractCriteriaImpl, AdvancedCriteriaImpl

public interface Criteria
extends ExecutableQuery

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.
The JCRCriteriaFactory is a factory for Criteria. Criterion instances are usually obtained via the factory methods on Restrictions. eg.

 Calendar begin = Calendar.getInstance();
 begin.set(1999, Calendar.JANUARY, 1);
 Calendar end = Calendar.getInstance();
 end.set(2001, Calendar.DECEMBER, 31);

 Criteria criteria = JCRCriteriaFactory.createCriteria().setWorkspace(ContentRepository.WEBSITE)
     .setBasePath("/pets")
     .add(Restrictions.contains("@title", "Lucky"))
     .add(Restrictions.eq("@petType", "dog"))
     .add(Restrictions.betweenDates("@birthDate", begin, end))
     .addOrder(Order.desc("@title"));
 

will be translated into the following xpath statement

  //pets//*[((jcr:contains(@title, 'Lucky')) and (@petType='dog')
    and (@birthDate >=xs:dateTime('1999-01-01T00:00:00.000+00:00')
    and @birthDate <=xs:dateTime('2001-12-31T23:59:59.999+00:00')))]
    order by @title descending
 

Furthermore, you may want to have only a subset of the whole result set returned, much like in a MySQL limit clause. In this case, you will use the setFirstResult and setMaxResults methods. Here is an example.

 Criteria criteria = JCRCriteriaFactory
     .createCriteria()
     .setWorkspace(ContentRepository.WEBSITE)
     .setBasePath("/pets")
     .add(Restrictions.betweenDates("@birthDate", begin, end))
     .addOrder(Order.asc("@birthDate"))
     .setFirstResult(5)
     .setMaxResults(5);

Notice the setFirstResult(int) and setMaxResults(int) methods. Now executing the query will return a subset of no more than five results, starting from the 6th item (counting starts from 0). If you dont specify these two calls, the entire result set will be returned. If you only call setMaxResults(int), the result set will be the subset of elements [0, maxResults] (firstResultValue is 0 by default).
Another way to paginate results is by using the setPaging method:

 Criteria criteria = JCRCriteriaFactory.createCriteria().setWorkspace(ContentRepository.WEBSITE)
     .setBasePath("/pets")
     .add(Restrictions.betweenDates("@birthDate", begin, end))
     .addOrder(Order.asc("@birthDate"))
     .setPaging(5, 2);

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.

This API was inspired by Hibernate's Criteria API.

Version:

$Id: Criteria.java 3369 2011-03-05 20:08:02Z fgiust $

Author:

Federico Grilli, fgiust

See Also:

JCRCriteriaFactory.createCriteria(), Order

Method Summary

Criteria	add(Criterion criterion) Add a restriction to constrain the results to be retrieved.
Criteria	addOrder(Order order) Add an ordering to the result set.
Criteria	setBasePath(String path) Sets the base path of the query, i.e.
Criteria	setFirstResult(int firstResult) Set the first result to be retrieved.
Criteria	setForcePagingWithDocumentOrder(boolean force) Enable paging while keeping results sorted in document order.
Criteria	setMaxResults(int maxResults) Set a limit upon the number of objects to be retrieved.
Criteria	setPaging(int itemsPerPage, int pageNumberStartingFromOne)
Criteria	setSpellCheckString(String spellCheckString) Sets the original input string for spell checking.
Criteria	setWorkspace(String workspace) Sets the name of the workspace where the search will take place
String	toXpathExpression() Returns the generated xpath expression

Methods inherited from interface net.sourceforge.openutils.mgnlcriteria.jcr.query.ExecutableQuery

execute

Method Detail

add

Criteria add(Criterion criterion)

Add a restriction to constrain the results to be retrieved.

Parameters:

criterion - The criterion object representing the restriction to be applied.

Returns:

this (for method chaining)

addOrder

Criteria addOrder(Order order)

Add an ordering to the result set. Only one Order criterion per query can be applied. Any Order added after the first one will be ignored.

Parameters:

order - The order object representing an ordering to be applied to the results.

Returns:

this (for method chaining)

setMaxResults

Criteria setMaxResults(int maxResults)

Set a limit upon the number of objects to be retrieved.

Parameters:

maxResults - the maximum number of results

Returns:

this (for method chaining)

setFirstResult

Criteria setFirstResult(int firstResult)

Set the first result to be retrieved.

Parameters:

firstResult - the first result to retrieve, numbered from 0

Returns:

this (for method chaining)

setBasePath

Criteria setBasePath(String path)

Sets the base path of the query, i.e. the branch in the repository tree where the search will take place

Parameters:

path - the handle of a node, or a xpath query prefix in the form //handle/of/a/node//*

Returns:

this (for method chaining)

setPaging

Criteria setPaging(int itemsPerPage,
                   int pageNumberStartingFromOne)

Parameters:

itemsPerPage - maximum number of results per page (i.e. page size)

pageNumberStartingFromOne - page number to retrieve (1, 2, 3, ...)

Returns:

this (for method chaining)

setSpellCheckString

Criteria setSpellCheckString(String spellCheckString)

Sets the original input string for spell checking.

Parameters:

spellCheckString - the actual input string for spell checking

Returns:

this (for method chaining)

setWorkspace

Criteria setWorkspace(String workspace)

Sets the name of the workspace where the search will take place

Parameters:

workspace - the name of a workspace

Returns:

this (for method chaining)

toXpathExpression

String toXpathExpression()

Returns the generated xpath expression

Returns:

the generated xpath expression

setForcePagingWithDocumentOrder

Criteria setForcePagingWithDocumentOrder(boolean force)

Enable paging while keeping results sorted in document order.

Document order is only applied by jackrabbit after the paginated result has been retrieved.

This means that if you have 20 nodes and you want to retrieve them in 2 pages containing 10 elements, only the order of elements in a single page is kept (but the "first" 10 noted in the first page will not be the nodes you are expecting in document order). Setting this flag to true forces the retrieval of the full list of nodes and a post-pagination which will mimic the behaviour you get when an "order by" is specified.

Warning: this has surely a performance hit, since jackrabbit applied document ordering by retrieving any single node (while normally pagination is applied directly on the luce index).

Parameters:

force - true to force paging while keeping results sorted in document order

Returns:

this (for method chaining)