001    /**
002     * Copyright 2005-2012 The Kuali Foundation
003     *
004     * Licensed under the Educational Community License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     * http://www.opensource.org/licenses/ecl2.php
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package org.kuali.rice.core.api.criteria;
017    
018    
019    import java.util.List;
020    
021    /**
022     * Contains a collection of results from a query.  This interface exists as a
023     * utility for services that want to implement it to represents results from
024     * criteria-based (or other) queries.
025     *
026     * <p>
027     * Also may  provide information related to the count of rows returned
028     * by the query as well as whether or not the query returned all available results.
029     * </p>
030     *
031     * <p>
032     * All the information in this interface is populated depending on the information
033     * requested via the {@link QueryByCriteria}.
034     * </p>
035     *
036     * @param <T> the type of the objects contained within the results list
037     *
038     * @author Kuali Rice Team (rice.collab@kuali.org)
039     *
040     */
041    public interface QueryResults<T> {
042    
043        /**
044             * Return the list of results that are contained within.  This list can
045             * be empty but it should never be null.
046             *
047             * @return the list of results
048             */
049            List<T> getResults();
050    
051            /**
052             * Gets the total number of records that match the executed query.  Note
053             * that this number will not necessarily match the number of results
054             * returned by {@link #getResults()} as the query may cut off the number
055             * of records returned by the actual query request.  In these cases, the
056             * total row count represents the total number of results which would be
057             * returned by the query if there was no cap on the results returned (i.e.
058             * the equivalent of the result of a "count" query in SQL).
059             * 
060             * <p>
061         * The total row count is optional depending on whether or not the
062             * client requested the total row count when invoking the query.  The client
063         * requests this information by setting the {@link CountFlag#INCLUDE} or
064         * {@link CountFlag#ONLY} on the {@link QueryByCriteria}.  It's also
065         * possible that the query is unable to produce a total row count depending
066             * on the back-end implementation, in which cases this value will also not
067             * be available.
068         * </p>
069         *
070         * <p>
071         * Will never be less than 0.
072         * <p>
073             * 
074             * @return the total number of rows, or null if the total row count was not
075             * requested by the query or could not be determined 
076             */
077            Integer getTotalRowCount();
078    
079            /**
080             * Indicates if there are more results available for the query immediately
081             * following the last result that was returned.  In this case, the records
082             * returned in {@link #getResults()} will not include the complete result
083             * set for the query.  This could be because the query only requested a
084             * certain number of rows, or that the query couldn't return the number
085             * of rows that were requested.
086             * 
087             * <p>
088         * It is intended that this value be used to facilitate paging or
089             * reporting in the client in cases where that is desired.
090         * </p>
091         *
092         * <p>
093         * This information will only be available if the client sets a limit on the
094         * results returned.  This limit is set with the maxResults field on the
095         * {@link QueryByCriteria}.
096         * </p>
097             * 
098             * @return true if there are more results available for the query, false otherwise
099             */
100            boolean isMoreResultsAvailable();
101    }