ehcache

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


ehcache

Copyright 2001-2014, Terracotta, Inc.