1 /**
2 * Copyright 2005-2014 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.rice.kew.docsearch.service;
17
18 import org.kuali.rice.core.api.util.KeyValue;
19 import org.kuali.rice.kew.api.document.search.DocumentSearchCriteria;
20 import org.kuali.rice.kew.api.document.search.DocumentSearchResults;
21 import org.kuali.rice.kew.impl.document.search.DocumentSearchGenerator;
22 import org.kuali.rice.kew.doctype.bo.DocumentType;
23
24 import java.util.List;
25
26
27 /**
28 * Service for data access for document searches.
29 *
30 * @author Kuali Rice Team (rice.collab@kuali.org)
31 */
32 public interface DocumentSearchService {
33
34 /**
35 * This method performs a standard document search for the given criteria.
36 *
37 * @param principalId the id of the principal who is executing the search, this may be null to indicate the
38 * search could be executed by an arbitrary user
39 * @param criteria criteria to use to search documents
40 * @return the results of the search, will never return null
41 */
42 DocumentSearchResults lookupDocuments(String principalId, DocumentSearchCriteria criteria);
43
44 /**
45 * This method performs a standard document search for the given criteria.
46 *
47 * @param principalId the id of the principal who is executing the search, this may be null to indicate the
48 * search could be executed by an arbitrary user
49 * @param criteria criteria to use to search documents
50 * @param boolean to indicate if search criteria should be saved to the users preferences
51 * @return the results of the search, will never return null
52 */
53 DocumentSearchResults lookupDocuments(String principalId, DocumentSearchCriteria criteria, boolean saveSearch);
54
55 /**
56 * Returns a saved search criteria, either explicitly named by the user, or saved automatically as a recent search
57 * @param principalId the user principal id
58 * @param key the user option key under which the criteria is saved
59 * @return the DocumentSearchCriteria or null if not found
60 */
61 DocumentSearchCriteria getSavedSearchCriteria(String principalId, String key);
62
63 /**
64 * Returns an explicitly named saved search criteria
65 * @param principalId the user principal id
66 * @param savedSearchName the user-provided saved search name
67 * @return the DocumentSearchCriteria or null if not found
68 */
69 DocumentSearchCriteria getNamedSearchCriteria(String principalId, String savedSearchName);
70
71 /**
72 * Clears all saved searches for the specified user (named and automatic)
73 * @param principalId user principal id
74 */
75 void clearNamedSearches(String principalId);
76
77 /**
78 * Returns named saved searches for the specified user
79 * @param principalId the user principal id
80 * @return list of search key/label
81 */
82 List<KeyValue> getNamedSearches(String principalId);
83
84 /**
85 * Returns automatically saved recent searches for the specified user
86 * @param principalId the user principal id
87 * @return list of search key/label
88 */
89 List<KeyValue> getMostRecentSearches(String principalId);
90
91 DocumentSearchCriteria clearCriteria(DocumentType documentType, DocumentSearchCriteria criteria);
92
93 DocumentSearchGenerator getStandardDocumentSearchGenerator();
94
95 void validateDocumentSearchCriteria(DocumentSearchGenerator docSearchGenerator, DocumentSearchCriteria.Builder criteria);
96
97 /**
98 * Returns the maximum number of results that should be returned from the document search.
99 *
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 }