001/**
002 * Copyright 2005-2016 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.docsearch.service;
017
018import org.kuali.rice.core.api.util.KeyValue;
019import org.kuali.rice.kew.api.document.search.DocumentSearchCriteria;
020import org.kuali.rice.kew.api.document.search.DocumentSearchResults;
021import org.kuali.rice.kew.impl.document.search.DocumentSearchGenerator;
022import org.kuali.rice.kew.doctype.bo.DocumentType;
023
024import java.util.List;
025
026
027/**
028 * Service for data access for document searches.
029 *
030 * @author Kuali Rice Team (rice.collab@kuali.org)
031 */
032public interface DocumentSearchService {
033
034    /**
035     * This method performs a standard document search for the given criteria.
036     *
037     * @param principalId the id of the principal who is executing the search, this may be null to indicate the
038     * search could be executed by an arbitrary user
039     * @param criteria criteria to use to search documents
040     * @return the results of the search, will never return null
041     */
042    DocumentSearchResults lookupDocuments(String principalId, DocumentSearchCriteria criteria);
043
044    /**
045     * Returns a saved search criteria, either explicitly named by the user, or saved automatically as a recent search
046     * @param principalId the user principal id
047     * @param key the user option key under which the criteria is saved
048     * @return the DocumentSearchCriteria or null if not found
049     */
050    DocumentSearchCriteria getSavedSearchCriteria(String principalId, String key);
051
052    /**
053     * Returns an explicitly named saved search criteria
054     * @param principalId the user principal id
055     * @param savedSearchName the user-provided saved search name
056     * @return the DocumentSearchCriteria or null if not found
057     */
058    DocumentSearchCriteria getNamedSearchCriteria(String principalId, String savedSearchName);
059
060    /**
061     * Clears all saved searches for the specified user (named and automatic)
062     * @param principalId user principal id
063     */
064    void clearNamedSearches(String principalId);
065
066    /**
067     * Returns named saved searches for the specified user
068     * @param principalId the user principal id
069     * @return list of search key/label
070     */
071    List<KeyValue> getNamedSearches(String principalId);
072
073    /**
074     * Returns automatically saved recent searches for the specified user
075     * @param principalId the user principal id
076     * @return list of search key/label
077     */
078    List<KeyValue> getMostRecentSearches(String principalId);
079
080    DocumentSearchCriteria clearCriteria(DocumentType documentType, DocumentSearchCriteria criteria);
081
082    DocumentSearchGenerator getStandardDocumentSearchGenerator();
083
084    void validateDocumentSearchCriteria(DocumentSearchGenerator docSearchGenerator, DocumentSearchCriteria.Builder criteria);
085
086    /**
087     * Returns the maximum number of results that should be returned from the document search.
088     *
089     * @param criteria the criteria in which to check for a max results value
090     * @return the maximum number of results that should be returned from a document search
091     */
092    public int getMaxResultCap(DocumentSearchCriteria criteria);
093
094    /**
095     * Returns the number of results that should be returned from an additional fetch against
096     * the document search.
097     *
098     * Default: {@link org.kuali.rice.kew.docsearch.dao.impl.DocumentSearchDAOJdbcImpl.DEFAULT_FETCH_MORE_ITERATION_LIMIT}
099     * Override: {@link org.kuali.rice.kew.api.KewApiConstants#DOC_SEARCH_FETCH_MORE_ITERATION_LIMIT}
100     * @return int
101     */
102    public int getFetchMoreIterationLimit();
103}