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     * This method performs a standard document search for the given criteria.
046     *
047     * @param principalId the id of the principal who is executing the search, this may be null to indicate the
048     * search could be executed by an arbitrary user
049     * @param criteria criteria to use to search documents
050     * @param boolean to indicate if search criteria should be saved to the users preferences
051     * @return the results of the search, will never return null
052     */
053    DocumentSearchResults lookupDocuments(String principalId, DocumentSearchCriteria criteria, boolean saveSearch);
054
055    /**
056     * Returns a saved search criteria, either explicitly named by the user, or saved automatically as a recent search
057     * @param principalId the user principal id
058     * @param key the user option key under which the criteria is saved
059     * @return the DocumentSearchCriteria or null if not found
060     */
061    DocumentSearchCriteria getSavedSearchCriteria(String principalId, String key);
062
063    /**
064     * Returns an explicitly named saved search criteria
065     * @param principalId the user principal id
066     * @param savedSearchName the user-provided saved search name
067     * @return the DocumentSearchCriteria or null if not found
068     */
069    DocumentSearchCriteria getNamedSearchCriteria(String principalId, String savedSearchName);
070
071    /**
072     * Clears all saved searches for the specified user (named and automatic)
073     * @param principalId user principal id
074     */
075    void clearNamedSearches(String principalId);
076
077    /**
078     * Returns named saved searches for the specified user
079     * @param principalId the user principal id
080     * @return list of search key/label
081     */
082    List<KeyValue> getNamedSearches(String principalId);
083
084    /**
085     * Returns automatically saved recent searches for the specified user
086     * @param principalId the user principal id
087     * @return list of search key/label
088     */
089    List<KeyValue> getMostRecentSearches(String principalId);
090
091    DocumentSearchCriteria clearCriteria(DocumentType documentType, DocumentSearchCriteria criteria);
092
093    DocumentSearchGenerator getStandardDocumentSearchGenerator();
094
095    void validateDocumentSearchCriteria(DocumentSearchGenerator docSearchGenerator, DocumentSearchCriteria.Builder criteria);
096
097    /**
098     * Returns the maximum number of results that should be returned from the document search.
099     *
100     * @param criteria the criteria in which to check for a max results value
101     * @return the maximum number of results that should be returned from a document search
102     */
103    public int getMaxResultCap(DocumentSearchCriteria criteria);
104
105    /**
106     * Returns the number of results that should be returned from an additional fetch against
107     * the document search.
108     *
109     * Default: {@link org.kuali.rice.kew.docsearch.dao.impl.DocumentSearchDAOJdbcImpl.DEFAULT_FETCH_MORE_ITERATION_LIMIT}
110     * Override: {@link org.kuali.rice.kew.api.KewApiConstants#DOC_SEARCH_FETCH_MORE_ITERATION_LIMIT}
111     * @return int
112     */
113    public int getFetchMoreIterationLimit();
114}