net.sf.ehcache.search.Query Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ehcache-core Show documentation
Internal ehcache-core module. This artifact is not meant to be used directly for jdk 1.5
The newest version!
/**
 *  Copyright Terracotta, Inc.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package net.sf.ehcache.search;

import net.sf.ehcache.search.aggregator.Aggregator;
import net.sf.ehcache.search.aggregator.AggregatorException;
import net.sf.ehcache.search.expression.Criteria;

/**
 * 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 {@link #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 {@link net.sf.ehcache.search.attribute.AttributeExtractor} .
 * 

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

 * A {@link Query} instance can be used by multiple threads
 *
 * @author teck
 * @author Greg Luck
 */
public interface Query {

    /**
     * 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 {@link net.sf.ehcache.search.attribute.AttributeType}
     */
    public static final Attribute KEY = new Attribute("key");

    /**
     * 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 {@link net.sf.ehcache.search.attribute.AttributeType}
     */
    public static final Attribute VALUE = new Attribute("value");

    /**
     * Request that the key object be present in the results.
     *
     * @return this
     */
    public Query includeKeys();

    /**
     * Request that the value object be present in the results.
     *
     * @return this
     */
    public Query includeValues();

    /**
     * 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 {@link #maxResults(int)} or by using {@link Results#range} rathern than {@link Results#all()}
     *
     * @param attributes the query attributes to select
     * @return this
     */
    public Query includeAttribute(Attribute... attributes);

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

     * This method may be called multiple times to request multiple aggregations
     *
     * @param aggregators
     * @return this
     * @throws SearchException
     * @throws net.sf.ehcache.search.aggregator.AggregatorException
     */
    public Query includeAggregator(Aggregator... aggregators) throws SearchException, AggregatorException;

    /**
     * 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
     *
     * @param attribute The attribute to order the results by
     * @param direction Ascending or descending
     * @return this
     */
    public Query addOrderBy(Attribute attribute, Direction direction);

    /**
     * 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.
     * @param attribute
     * @return
     * @since 2.6
     */
    public Query addGroupBy(Attribute... attribute);

    /**
     * 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.
     *
     * @param maxResults the maximum number of results to return
     * @return this
     */
    public Query maxResults(int maxResults);

    /**
     * Adds a criteria to the query
     */
    public Query addCriteria(Criteria criteria);

    /**
     * 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 {@link net.sf.ehcache.config.TimeoutBehaviorConfiguration.TimeoutBehaviorType#NOOP} and
     * {@link net.sf.ehcache.config.TimeoutBehaviorConfiguration.TimeoutBehaviorType#LOCAL_READS} behavior
     *
     * @return query results
     * @throws SearchException
     */
    public Results execute() throws SearchException;
    
    /**
     * Like {@link #execute()}, but with specified execution parameters.
     * @param hints
     * @return
     * @throws SearchException
     */
    public Results execute(ExecutionHints hints) throws SearchException;

    /**
     * Optional method for terminating query creation. If called the query becomes
     * immutable, so that attempting any further mutations will result in an exception
     */
    public Query end();
}