001/**
002 * Copyright 2005-2018 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 */
016package org.kuali.rice.kew.api.document.search;
017
018import java.util.List;
019
020/**
021 * Defines the contract for results returned from a document search.  A document search returns multiple results, each
022 * one representing a document and it's document attributes.  The results additional include information about the
023 * criteria that was used to execute the search, as well as whether or not it was modified after it was submitted for
024 * execution of the document search.
025 *
026 * <p>Additionally, results from the document search might be filtered for a particular principal for security purposes.
027 * In these cases, the document search results include information on the number of results that were filtered out
028 * because the principal executing the search did not have permission to view them.</p>
029 *
030 * @author Kuali Rice Team (rice.collab@kuali.org)
031 */
032public interface DocumentSearchResultsContract {
033
034    /**
035     * Returns the unmodifiable list of search results.  Each of these result objects represents a document returned
036     * from the search.
037     *
038     * @return an unmodifiable list of search results, will never be null but may be null
039     */
040    List<? extends DocumentSearchResultContract> getSearchResults();
041
042    /**
043     * Returns the criteria that was used to execute the search.  This may not be the same criteria that was submitted
044     * to the document search api since it is possible for criteria to be modified by backend processing of the
045     * submitted criteria.  See {@link #isCriteriaModified()} for more information.
046     *
047     * @return the criteria used to execute this search, will never be null
048     */
049    DocumentSearchCriteriaContract getCriteria();
050
051    /**
052     * Returns true if the criteria on this search result was modified from the original criteria submitted by the
053     * executor of the document search.  This may happen in cases where the document search implementation modifies the
054     * given criteria.  This may be possible through document search customization hooks, or may happen as part of a
055     * process of "defaulting" certain portions of the criteria.
056     *
057     * @return a boolean indicating whether or not the criteria was modified from it's original form prior to search
058     * execution
059     */
060    boolean isCriteriaModified();
061
062    /**
063     * Returns true if the results of the search returned more rows then the document search framework is allowed to
064     * return back to the caller of the api.  The implementation of the document search is permitted to cap the number
065     * of results returned and a result cap can also be specified on the criteria itself.
066     *
067     * @return true if there are more results available for the requested search then can be included in the list of
068     * results
069     */
070    boolean isOverThreshold();
071
072    /**
073     * Return the number of results that matched the criteria but are not included on this results instance because they
074     * principal executing the document search did not have permissions to view them.
075     *
076     * @return the number of results that were filtered for security reasons
077     */
078    int getNumberOfSecurityFilteredResults();
079
080}