1 /***
2 * Copyright 2003-2010 Terracotta, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package net.sf.ehcache.search;
18
19 import net.sf.ehcache.search.aggregator.Aggregator;
20 import net.sf.ehcache.search.aggregator.AggregatorException;
21 import net.sf.ehcache.search.expression.Criteria;
22
23 /***
24 * Creates queries for performing cache searches.
25 * <p/>
26 * Queries are created using our search DSL implemented using Java.
27 * <p/>
28 * A fluent interface provides a compact and yet easy-to-read representation. Fluent interfaces are implemented using method chaining.
29 * Static factory methods and imports are a great aid in creating a compact, yet readable DSL.
30 * <p/>
31 * Out API has the following features:
32 * <p/>
33 * Method Chaining - we return <code>this</code>.
34 * <p/>
35 * <p/>
36 * See http://www.infoq.com/articles/internal-dsls-java for a description of these conventions.
37 * <p/>
38 * A query can be executed and then modified and re-executed. If {@link #end} is called the query is made immutable.
39 * <p/>
40 * Both Element keys and attributes of Element can be queried. Attributes must be pre-defined for a cache. They are populated by extraction
41 * from an Element's value using an {@link net.sf.ehcache.search.attribute.AttributeExtractor} .
42 * <p/>
43 * Search results can either be Element keys (the default), values, or the result of an {@link Aggregator} function.
44 * <p/>
45 * A {@link Query} instance can be used by multiple threads
46 *
47 * @author teck
48 * @author Greg Luck
49 */
50 public interface Query {
51
52 /***
53 * The search attribute for a cache element's key.
54 *
55 * This will exist as a search attribute at runtime if the key is of a supported {@link net.sf.ehcache.search.attribute.AttributeType}
56 */
57 public static final Attribute KEY = new Attribute("key");
58
59 /***
60 * The search attribute for a cache element's value.
61 *
62 * This will exist as a search attribute at runtime if the value is of a supported {@link net.sf.ehcache.search.attribute.AttributeType}
63 */
64 public static final Attribute VALUE = new Attribute("value");
65
66 /***
67 * Request that the key object be present in the results.
68 *
69 * @return this
70 */
71 public Query includeKeys();
72
73 /***
74 * Request that the value object be present in the results.
75 *
76 * @return this
77 */
78 public Query includeValues();
79
80 /***
81 * Request that the given attribute(s) should be present in the result for
82 * this query. This call can be made multiple times to add to the set of
83 * selected attributes.
84 * <p/>
85 * Note that in a distributed cache attributes may need to come over the network. To prevent very large network transfers, consider
86 * limiting the results size with {@link #maxResults(int)} or by using {@link Results#range} rathern than {@link Results#all()}
87 *
88 * @param attributes the query attributes to select
89 * @return this
90 */
91 public Query includeAttribute(Attribute<?>... attributes);
92
93 /***
94 * Request this query to aggregate the results by the given Aggregator(s)
95 * <p/>
96 * This method may be called multiple times to request multiple aggregations
97 *
98 * @param aggregators
99 * @return this
100 * @throws SearchException
101 * @throws net.sf.ehcache.search.aggregator.AggregatorException
102 */
103 public Query includeAggregator(Aggregator... aggregators) throws SearchException, AggregatorException;
104
105 /***
106 * Request result set ordering by the given attribute and direction. This
107 * call can be made multiple times to specify second level. third level, etc
108 * orderings
109 *
110 * @param attribute The attribute to order the results by
111 * @param direction Ascending or descending
112 * @return this
113 */
114 public Query addOrderBy(Attribute<?> attribute, Direction direction);
115
116 /***
117 * Restrict the number of results returned from the search.
118 * <p/>
119 * By default an unlimited number of results can be returned. This could cause an OutOfMemoryError to be thrown. It is therefore
120 * recommended to add an <code>maxResults</code> clause to your query to limit the size.
121 *
122 * @param maxResults the maximum number of results to return
123 * @return this
124 */
125 public Query maxResults(int maxResults);
126
127 /***
128 * Adds a criteria to the query
129 */
130 public Query addCriteria(Criteria criteria);
131
132 /***
133 * Execute this query. Every call to this method will re-execute the query
134 * and return a distinct results object.
135 * <p/>
136 * An empty results object will be returned (on timeout) for non-stop enabled caches with {@link net.sf.ehcache.config.TimeoutBehaviorConfiguration.TimeoutBehaviorType#NOOP} and
137 * {@link net.sf.ehcache.config.TimeoutBehaviorConfiguration.TimeoutBehaviorType#LOCAL_READS} behavior
138 *
139 * @return query results
140 * @throws SearchException
141 */
142 public Results execute() throws SearchException;
143
144 /***
145 * Optional method for terminating query creation. If called the query becomes
146 * immutable, so that attempting any further mutations will result in an exception
147 */
148 public Query end();
149
150 }