1 /**
2 * Copyright 2005-2011 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;
17
18 import org.kuali.rice.core.api.uif.RemotableAttributeError;
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.framework.document.search.DocumentSearchCriteriaConfiguration;
22 import org.kuali.rice.kew.framework.document.search.DocumentSearchResultSetConfiguration;
23 import org.kuali.rice.kew.framework.document.search.DocumentSearchResultValues;
24 import org.kuali.rice.kew.doctype.bo.DocumentType;
25
26 import java.util.List;
27
28 /**
29 * Handles communication between {@link org.kuali.rice.kew.framework.document.search.DocumentSearchCustomizationHandlerService}
30 * endpoints in order to invoke document search customizations which might be hosted from various applications.
31 *
32 * @author Kuali Rice Team (rice.collab@kuali.org)
33 */
34 public interface DocumentSearchCustomizationMediator {
35
36 /**
37 * Retrieves the document search criteria configuration for the given document type. This should include attribute
38 * fields that should be included in the document search user interface when displaying criteria by which a user
39 * can search for documents. If this method returns null then no additional criteria should be presented on the
40 * search screen.
41 *
42 * @param documentType the document type for which to find document search criteria configuration, must not be null
43 *
44 * @return configuration information containing additional criteria (beyond the default set) which should be
45 * displayed to the user when performing a search against documents of the given type, if null is returned this
46 * indicates that the default document search criteria configuration should be used
47 */
48 DocumentSearchCriteriaConfiguration getDocumentSearchCriteriaConfiguration(DocumentType documentType);
49
50 /**
51 * Performs optional validation of document search criteria prior to execution of the search.
52 *
53 * @param documentType the document type against which the lookup is being performed
54 * @param documentSearchCriteria the criteria representing the submission of the document search
55 *
56 * @return a list of error messages generated by the validation, may an empty list in which case the calling code
57 * may safely ignore the response and assume that the given criteria validated successfully
58 */
59 List<RemotableAttributeError> validateLookupFieldParameters(DocumentType documentType,
60 DocumentSearchCriteria documentSearchCriteria);
61
62 /**
63 * Optionally performs customization of the given document search criteria in the cases where the document type
64 * implements criteria customization. If this method returns a non-null value, then the calling code should use
65 * the returned criteria in order to execute the search. If this method returns a null value, it means the criteria
66 * that was given did not require any customization. In this case, the calling code should proceed with search
67 * execution using the originally provided criteria.
68 *
69 * @param documentType the document type against which to perform the criteria customization, should never be null
70 * @param documentSearchCriteria the criteria to use as the starting point for customization
71 *
72 * @return a customized version of the given criteria, or null if the criteria was not customized
73 */
74 DocumentSearchCriteria customizeCriteria(DocumentType documentType, DocumentSearchCriteria documentSearchCriteria);
75
76 /**
77 * Optionally performs a custom clearing of the given document search criteria if the given document type
78 * implements a customized clear algorithm. If this method returns a non-null value, then the value returned
79 * should be instated by the calling code as the "cleared" version of the criteria. If null is returned, then the
80 * default implementation of criteria clearing should be used.
81 *
82 * @param documentType the document type against which to check for a custom implementation of criteria clearing
83 * @param documentSearchCriteria the current criteria of the document search prior to being cleared
84 *
85 * @return the result of clearing the criteria, if this returns null it means the given document type does not
86 * implement custom clearing and the default behavior should be used
87 */
88 DocumentSearchCriteria customizeClearCriteria(DocumentType documentType,
89 DocumentSearchCriteria documentSearchCriteria);
90
91 /**
92 * Optionally performs customization on the given set of document search results. This could include changing
93 * existing document values or synthesizing new ones. The results of this method include a list of
94 * {@link org.kuali.rice.kew.framework.document.search.DocumentSearchResultValue} objects, each of which are mapped to a
95 * specific document id from the results and include additional key-value pairs for customized or synthesized
96 * values for that document. This method can return a null value if no customization was performed.
97 *
98 * @param documentType the document type to use when determining what customization logic (if any) should be invoked
99 * @param documentSearchCriteria the criteria of the document search which produced the supplied results
100 * @param results the results of the document search which are being considered for customization
101 *
102 * @return the customized result values, or null if not result customization was performed
103 */
104 DocumentSearchResultValues customizeResults(DocumentType documentType,
105 DocumentSearchCriteria documentSearchCriteria,
106 DocumentSearchResults results);
107
108 /**
109 * Optionally provides configuration information that allows for document search result set customization to occur.
110 * The resulting {@code DocumentSearchResultSetConfiguration} can be used by the calling code to determine how best
111 * to render the lookup results.
112 *
113 * @param documentType the document type for which to customize result set configuration
114 * @param documentSearchCriteria the criteria that was used to perform the lookup
115 *
116 * @return the customized document search result set configuration, or null if no result set customization was
117 * performed
118 */
119 DocumentSearchResultSetConfiguration customizeResultSetConfiguration(DocumentType documentType,
120 DocumentSearchCriteria documentSearchCriteria);
121
122 }
123
124