ehcache-core 2.10.9.2 · net.sf.ehcache.search.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 net.sf.ehcache.search.attribute.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

Field Summary

Modifier and Type	Field and Description
public static final Attribute<T>	KEY The search attribute for a cache element's key.
public static final Attribute<T>	VALUE The search attribute for a cache element's value.

Method Summary

Modifier and Type	Method and Description
public Query	addCriteria(Criteria criteria) Adds a criteria to the query
public Query	addGroupBy(Attribute<?>... attribute) Group result set by unique value(s) of specified attribute(s).
public Query	Returns: this addOrderBy(Attribute<?> The attribute to order the results by attribute, Direction Ascending or descending direction) Request result set ordering by the given attribute and direction.
public Query	end() Optional method for terminating query creation.
public Results	Returns: query results execute() Execute this query.
public Results	execute(ExecutionHints hints) Like `execute()`, but with specified execution parameters.
public Query	Returns: this 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
public Query	Returns: this includeAttribute(Attribute<?>... the query attributes to select attributes) Request that the given attribute(s) should be present in the result for this query.
public Query	Returns: this includeKeys() Request that the key object be present in the results.
public Query	Returns: this includeValues() Request that the value object be present in the results.
public Query	Returns: this maxResults(int the maximum number of results to return maxResults) Restrict the number of results returned from the search.

Field Detail

KEY	back to summary
public static final Attribute<T> 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 `net.sf.ehcache.search.attribute.AttributeType`

VALUE	back to summary
public static final Attribute<T> 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 `net.sf.ehcache.search.attribute.AttributeType`

Method Detail

addCriteria	back to summary
public Query addCriteria(Criteria criteria) Adds a criteria to the query

addGroupBy	back to summary
public 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. Since 2.6

addGroupBy

back to summary

public 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.

Since: 2.6

addOrderBy	back to summary
public 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:Attribute<?> The attribute to order the results by direction:Direction Ascending or descending Returns:Query this

addOrderBy

back to summary

public 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:Attribute<?>: The attribute to order the results by
direction:Direction: Ascending or descending

Returns:Query

this

end	back to summary
public 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

execute back to summary

execute	back to summary
public 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 `net.sf.ehcache.config.TimeoutBehaviorConfiguration.TimeoutBehaviorType#NOOP` and `net.sf.ehcache.config.TimeoutBehaviorConfiguration.TimeoutBehaviorType#LOCAL_READS` behavior Returns:Results query results

public 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 net.sf.ehcache.config.TimeoutBehaviorConfiguration.TimeoutBehaviorType#NOOP and net.sf.ehcache.config.TimeoutBehaviorConfiguration.TimeoutBehaviorType#LOCAL_READS behavior

Returns:Results: query results

execute	back to summary
public Results execute(ExecutionHints hints) throws SearchException Like `execute()`, but with specified execution parameters.

includeAggregator	back to summary
public 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 Returns:Query this

includeAggregator

back to summary

public 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

Returns:Query: this

includeAttribute back to summary

includeAttribute	back to summary
public 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` rathern than `Results#all()` Parameters attributes:Attribute<?>[] the query attributes to select Returns:Query this

public 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 rathern than Results#all()

Parameters

attributes:Attribute<?>[]: the query attributes to select

Returns:Query

this

includeKeys	back to summary
public Query includeKeys() Request that the key object be present in the results. Returns:Query this

includeKeys

back to summary

public Query includeKeys()

Request that the key object be present in the results.

Returns:Query: this

includeValues	back to summary
public Query includeValues() Request that the value object be present in the results. Returns:Query this

includeValues

back to summary

public Query includeValues()

Request that the value object be present in the results.

Returns:Query: this

maxResults back to summary

maxResults	back to summary
public 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:int the maximum number of results to return Returns:Query this

public 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:int: the maximum number of results to return

Returns:Query

this

public Interface Query

Field Summary

Method Summary

Field Detail

Method Detail