001    /**
002     * Copyright 2005-2014 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.kew.docsearch.service;
017    
018    import org.kuali.rice.core.api.util.KeyValue;
019    import org.kuali.rice.kew.api.document.search.DocumentSearchCriteria;
020    import org.kuali.rice.kew.api.document.search.DocumentSearchResults;
021    import org.kuali.rice.kew.impl.document.search.DocumentSearchGenerator;
022    import org.kuali.rice.kew.doctype.bo.DocumentType;
023    
024    import 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     */
032    public 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    }