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 java.util.List;
20
21 /***
22 * Results object for an execution of a {@link Query}. Instances of this class
23 * are thread safe
24 *
25 * @author teck
26 * @author Greg Luck
27 */
28 public interface Results {
29
30 /***
31 * Discard this query result. This call is not mandatory but is recommended after
32 * the caller is done with results. It can allow the cache, which may be distributed,
33 * to immediately free any resources associated with this result.
34 * <p/>
35 * Multiple calls are ignored. Attempting to read results from this instance after this method has been called will produce
36 * {@link SearchException}
37 */
38 void discard();
39
40 /***
41 * Retrieve all of the cache results in one shot. For large result sets this
42 * might consume large amount of memory
43 *
44 * @return a List of all the matching cache entries
45 * @throws SearchException
46 */
47 List<Result> all() throws SearchException;
48
49 /***
50 * Retrieve a subset of the cache results. This method is useful when
51 * showing "paged" results in a user interface or simply to keep memory overhead fixed
52 *
53 * @param start starting index to access
54 * @param count the number of results to return
55 * @return a List of the given size. This list will be smaller than the requested
56 * size if no more results are available. If there are no more results an empty
57 * list will be returned.
58 * @throws SearchException
59 */
60 List<Result> range(int start, int count) throws SearchException, IndexOutOfBoundsException;
61
62 /***
63 * Results size
64 *
65 * @return number of results present
66 */
67 int size();
68
69 /***
70 * Whether the Results have cache keys included.
71 * If so these can be extracted from the Result object.
72 *
73 * @return true if keys are included
74 */
75 boolean hasKeys();
76
77 /***
78 * Whether the Results have cache values included.
79 * If so these can be extracted from the Result object.
80 *
81 * @return true if values are included
82 */
83 boolean hasValues();
84
85 /***
86 * Whether the Results have cache attributes included.
87 * If so these can be extracted from the Result object.
88 *
89 * @return true if attributes are included
90 */
91 boolean hasAttributes();
92
93 /***
94 * Whether the results contains aggregates
95 *
96 * @return true if this is an aggregate
97 */
98 boolean hasAggregators();
99
100 }