net.sf.ehcache.search
Interface Query

public interface Query

Creates queries for performing cache searches.

Queries are created using our search DSL implemented using Java.

A fluent interface provides a compact and yet easy-to-read representation. Fluent interfaces are implemented using method chaining. Static factory methods and imports are a great aid in creating a compact, yet readable DSL.

Out API has the following features:

Method Chaining - we return this.

See http://www.infoq.com/articles/internal-dsls-java for a description of these conventions.

A query can be executed and then modified and re-executed. If end() is called the query is made immutable.

Both Element keys and attributes of Element can be queried. Attributes must be pre-defined for a cache. They are populated by extraction from an Element's value using an AttributeExtractor .

Search results can either be Element keys (the default), values, or the result of an Aggregator function.

A Query instance can be used by multiple threads

Author:

teck, Greg Luck

Field Summary

static Attribute	KEY The search attribute for a cache element's key.
static Attribute	VALUE The search attribute for a cache element's value.

Method Summary

Query	addCriteria(Criteria criteria) Adds a criteria to the query
Query	addGroupBy(Attribute<?>... attribute) Group result set by unique value(s) of specified attribute(s).
Query	addOrderBy(Attribute<?> attribute, Direction direction) Request result set ordering by the given attribute and direction.
Query	end() Optional method for terminating query creation.
Results	execute() Execute this query.
Results	execute(ExecutionHints hints) Like execute(), but with specified execution parameters.
Query	includeAggregator(Aggregator... aggregators) Request this query to aggregate the results by the given Aggregator(s) This method may be called multiple times to request multiple aggregations
Query	includeAttribute(Attribute<?>... attributes) Request that the given attribute(s) should be present in the result for this query.
Query	includeKeys() Request that the key object be present in the results.
Query	includeValues() Request that the value object be present in the results.
Query	maxResults(int maxResults) Restrict the number of results returned from the search.

Field Detail

KEY

static final Attribute KEY

The search attribute for a cache element's key. This will exist as a search attribute at runtime if the key is of a supported AttributeType

VALUE

static final Attribute VALUE

The search attribute for a cache element's value. This will exist as a search attribute at runtime if the value is of a supported AttributeType

Method Detail

includeKeys

Query includeKeys()

Request that the key object be present in the results.

Returns:

this

includeValues

Query includeValues()

Request that the value object be present in the results.

Returns:

this

includeAttribute

Query includeAttribute(Attribute<?>... attributes)

Request that the given attribute(s) should be present in the result for this query. This call can be made multiple times to add to the set of selected attributes.

Note that in a distributed cache attributes may need to come over the network. To prevent very large network transfers, consider limiting the results size with maxResults(int) or by using Results.range(int, int) rathern than Results.all()

Parameters:

attributes - the query attributes to select

Returns:

this

includeAggregator

Query includeAggregator(Aggregator... aggregators)
                        throws SearchException,
                               AggregatorException

Request this query to aggregate the results by the given Aggregator(s)

This method may be called multiple times to request multiple aggregations

Parameters:

aggregators -

Returns:

this

Throws:

SearchException

AggregatorException

addOrderBy

Query addOrderBy(Attribute<?> attribute,
                 Direction direction)

Request result set ordering by the given attribute and direction. This call can be made multiple times to specify second level. third level, etc orderings

Parameters:

attribute - The attribute to order the results by

direction - Ascending or descending

Returns:

this

addGroupBy

Query addGroupBy(Attribute<?>... attribute)

Group result set by unique value(s) of specified attribute(s). Rows with duplicate values for these attributes will be removed. This method may also be chained to achieve the same effect.

Parameters:

attribute -

Returns:

Since:

2.6

maxResults

Query maxResults(int maxResults)

Restrict the number of results returned from the search.

By default an unlimited number of results can be returned. This could cause an OutOfMemoryError to be thrown. It is therefore recommended to add an maxResults clause to your query to limit the size.

Negative values are ignored and result in the default behaviour: unlimited number of results.

Parameters:

maxResults - the maximum number of results to return

Returns:

this

addCriteria

Query addCriteria(Criteria criteria)

Adds a criteria to the query

execute

Results execute()
                throws SearchException

Execute this query. Every call to this method will re-execute the query and return a distinct results object.

An empty results object will be returned (on timeout) for non-stop enabled caches with TimeoutBehaviorConfiguration.TimeoutBehaviorType.NOOP and TimeoutBehaviorConfiguration.TimeoutBehaviorType.LOCAL_READS behavior

Returns:

query results

Throws:

SearchException

execute

Results execute(ExecutionHints hints)
                throws SearchException

Like execute(), but with specified execution parameters.

Parameters:

hints -

Returns:

Throws:

SearchException

end

Query end()

Optional method for terminating query creation. If called the query becomes immutable, so that attempting any further mutations will result in an exception