1 /**
2 * Copyright 2005-2012 The Kuali Foundation
3 *
4 * Licensed under the Educational Community 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.opensource.org/licenses/ecl2.php
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 package org.kuali.rice.core.api.criteria;
17
18
19 import java.util.List;
20
21 /**
22 * Contains a collection of results from a query. This interface exists as a
23 * utility for services that want to implement it to represents results from
24 * criteria-based (or other) queries.
25 *
26 * <p>
27 * Also may provide information related to the count of rows returned
28 * by the query as well as whether or not the query returned all available results.
29 * </p>
30 *
31 * <p>
32 * All the information in this interface is populated depending on the information
33 * requested via the {@link QueryByCriteria}.
34 * </p>
35 *
36 * @param <T> the type of the objects contained within the results list
37 *
38 * @author Kuali Rice Team (rice.collab@kuali.org)
39 *
40 */
41 public interface QueryResults<T> {
42
43 /**
44 * Return the list of results that are contained within. This list can
45 * be empty but it should never be null.
46 *
47 * @return the list of results
48 */
49 List<T> getResults();
50
51 /**
52 * Gets the total number of records that match the executed query. Note
53 * that this number will not necessarily match the number of results
54 * returned by {@link #getResults()} as the query may cut off the number
55 * of records returned by the actual query request. In these cases, the
56 * total row count represents the total number of results which would be
57 * returned by the query if there was no cap on the results returned (i.e.
58 * the equivalent of the result of a "count" query in SQL).
59 *
60 * <p>
61 * The total row count is optional depending on whether or not the
62 * client requested the total row count when invoking the query. The client
63 * requests this information by setting the {@link CountFlag#INCLUDE} or
64 * {@link CountFlag#ONLY} on the {@link QueryByCriteria}. It's also
65 * possible that the query is unable to produce a total row count depending
66 * on the back-end implementation, in which cases this value will also not
67 * be available.
68 * </p>
69 *
70 * <p>
71 * Will never be less than 0.
72 * <p>
73 *
74 * @return the total number of rows, or null if the total row count was not
75 * requested by the query or could not be determined
76 */
77 Integer getTotalRowCount();
78
79 /**
80 * Indicates if there are more results available for the query immediately
81 * following the last result that was returned. In this case, the records
82 * returned in {@link #getResults()} will not include the complete result
83 * set for the query. This could be because the query only requested a
84 * certain number of rows, or that the query couldn't return the number
85 * of rows that were requested.
86 *
87 * <p>
88 * It is intended that this value be used to facilitate paging or
89 * reporting in the client in cases where that is desired.
90 * </p>
91 *
92 * <p>
93 * This information will only be available if the client sets a limit on the
94 * results returned. This limit is set with the maxResults field on the
95 * {@link QueryByCriteria}.
96 * </p>
97 *
98 * @return true if there are more results available for the query, false otherwise
99 */
100 boolean isMoreResultsAvailable();
101 }