1 /**
2 * Copyright 2005-2012 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.framework.document.search;
17
18 import org.kuali.rice.kew.api.document.search.DocumentSearchCriteria;
19 import org.kuali.rice.kew.api.document.search.DocumentSearchResult;
20
21 import java.util.List;
22
23 /**
24 * Provides various mechanisms for an application to customize the behavior of the Document Search functionality for
25 * their document types. Client applications should provide implementations of this interface if they need to
26 * enact some of these customizations on document searches. These customizers then get mapped to the appropriate
27 * document types via the KEW extension framework (see
28 * {@link org.kuali.rice.kew.api.extension.ExtensionRepositoryService}).
29 *
30 * <p>The customization functionality provided by this interface includes:</p>
31 *
32 * <ul>
33 * <li>The ability to customize document search criteria before it gets submitted.</li>
34 * <li>The ability to customize how document search criteria is cleared.</li>
35 * <li>The ability to customize how result data is processed and presented.</li>
36 * </ul>
37 *
38 * <p>Only one {@code DocumentSearchCustomizer} is supported for a given document type. It is important to note however
39 * that it is permitted that an implementation of this interface could be tied to more than one document type via the
40 * extension framework. This is why information about the specific document type for which the customizations is being
41 * applied is passed to all methods on this interface (note that the document type information is available from the
42 * {@code DocumentSearchCriteria} as well.</p>
43 *
44 * <p>Furthermore, the customization hooks afforded by this interface will only be executed when a valid document type
45 * has been specified as input to the document search. This is because the customizer is tied to the document type and
46 * the document search must therefore be able to resolve a valid document type from the user-supplied criteria in order
47 * to perform these customizations.</p>
48 *
49 * <p>Since some of the operations on this component could potentially add expense to the overall search process in the
50 * cases where customization is only done on certain document types or only certain customization features are being
51 * utilized, this interface provides for a set of boolean operations which indicate which customization
52 * features should be activated by the document search framework for a given document type. It's expected that KEW
53 * will check each of these flags prior to invoking the corresponding method that it "gaurds" and, if the customization
54 * flag is disabled, it should refrain from executing that method.</p>
55 *
56 * <p></p>Implementations of this interface are expected to return "true" for any of these operations for which they
57 * provide a custom implementation. <strong>It is important to note that callers are permitted to cache the results
58 * returned from these boolean methods for an unspecified length of time.</strong> So if there is any possibility that,
59 * for a given document type, the implementation might perform a particular customization, then "true" should be
60 * returned from the appropriate boolean method.</p>
61 *
62 * @author Kuali Rice Team (rice.collab@kuali.org)
63 */
64 public interface DocumentSearchCustomizer {
65
66 /**
67 * Performs customization on the given document search criteria. This method should return the customized version
68 * of the criteria, or null if no customizations were performed. This customization is invoked prior the actual
69 * search being executed, and the resulting customized criteria is what gets passed to the search implementation.
70 * It is also invoked in situtations where the document search is performed via the api or via the user interface.
71 *
72 * <p>It is guaranteed that the document type name on the given criteria will never be null and will always
73 * represent a valid document type.</p>
74 *
75 * @param documentSearchCriteria the original criteria against which to perform customization, will never be null
76 *
77 * @return the customized criteria, or null if no customization was performed
78 */
79 DocumentSearchCriteria customizeCriteria(DocumentSearchCriteria documentSearchCriteria);
80
81 /**
82 * Performs a customized "clear" of the given document search criteria. Clearing of the criteria is typically
83 * invoked whenever the user of the document search user interface clicks the "clear" button. By default all of
84 * the search criteria is cleared, but this method allows for certain criteria data to be preserved on a clear if
85 * desired.
86 *
87 * <p>A common use of this feature is to preserve the document type that has been selected when clearing criteria
88 * for a customized document search.
89 *
90 * <p>It is guaranteed that the document type name on the given criteria will never be null and will always
91 * represent a valid document type.</p>
92 *
93 * @param documentSearchCriteria the criteria to clear
94 *
95 * @return the cleared criteria, or null if no custom criteria clearing was performed
96 */
97 DocumentSearchCriteria customizeClearCriteria(DocumentSearchCriteria documentSearchCriteria);
98
99 /**
100 * Performs customization of the given list of document search results. This method is invoked after the search is
101 * executed but before results are returned to the caller. It is executed when a document search is executed via
102 * the api or from the document search user interface.
103 *
104 * <p>This method returns a {@code DocumentSearchResultValues} object which contains a list of
105 * {@link DocumentSearchResultValue} objects. Each of these result values maps to a specific document id and
106 * contains a list of {@link org.kuali.rice.kew.api.document.attribute.DocumentAttribute} values which can be used
107 * to modify existing document attributes or create new ones that are included as part of the search results. It
108 * is important to note that in order for these custom attribute values to be displayed in the result set in the
109 * document search user interface, there must be a corresponding entry in the
110 * {@link DocumentSearchResultSetConfiguration} returned by the
111 * {@link #customizeResultSetConfiguration(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria)} method
112 * on this customizer implementation.</p>
113 *
114 * <p>It is permissible that implementations of this method may not return result values for all of the document
115 * provided in the given list of document search results. It is important to note however that ommision from the
116 * returned result values does not filter or remove the result from the search results. Generally speaking, this
117 * method cannot be used to remove results from the result set.</p>
118 *
119 * <p>It is guaranteed that the document type name on the given criteria will never be null and will always
120 * represent a valid document type.</p>
121 *
122 * @param documentSearchCriteria the criteria against which the document search was executed
123 * @param defaultResults the results that were returned by the execution of the document search
124 *
125 * @return customized search result values for any of the document results requiring custom values, or null if no
126 * customization was performed
127 */
128 DocumentSearchResultValues customizeResults(DocumentSearchCriteria documentSearchCriteria, List<DocumentSearchResult> defaultResults);
129
130 /**
131 * Performs customization of what result fields should be displayed in the result set. Allows for hiding of
132 * standard fields, addition of custom fields, and the ability to override the default behavior of searchable
133 * attributes that are defined for the document type. Generally speaking, this controls which "columns" of data are
134 * displayed in the document search results.
135 *
136 * <p>This method is only invoked by the document search user interface whenever it is rendering document search
137 * results. It is not invoked when invoking document search using only the api.</p>
138 *
139 * <p>It is guaranteed that the document type name on the given criteria will never be null and will always
140 * represent a valid document type.</p>
141 *
142 * @param documentSearchCriteria the criteria against which the document search was executed
143 * @return the customized result set configuration, or null if no customization was performed
144 */
145 DocumentSearchResultSetConfiguration customizeResultSetConfiguration(DocumentSearchCriteria documentSearchCriteria);
146
147 /**
148 * Indicates if the {@link #customizeCriteria(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria)} on
149 * this customizer should be invoked for the document type with the given name. The caller of this method is
150 * permitted to cache the return value for a length of time of their choosing.
151 *
152 * @param documentTypeName the name of the document type against which this customizer is being applied
153 * @return true if the customization method should be executed, false otherwise
154 */
155 boolean isCustomizeCriteriaEnabled(String documentTypeName);
156
157 /**
158 * Indicates if the {@link #customizeClearCriteria(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria)}
159 * on this customizer should be invoked for the document type with the given name. The caller of this method is
160 * permitted to cache the return value for a length of time of their choosing.
161 *
162 * @param documentTypeName the name of the document type against which this customizer is being applied
163 * @return true if the customization method should be executed, false otherwise
164 */
165 boolean isCustomizeClearCriteriaEnabled(String documentTypeName);
166
167 /**
168 * Indicates if the {@link #customizeResults(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria, java.util.List)}
169 * on this customizer should be invoked for the document type with the given name. The caller of this method is
170 * permitted to cache the return value for a length of time of their choosing.
171 *
172 * @param documentTypeName the name of the document type against which this customizer is being applied
173 * @return true if the customization method should be executed, false otherwise
174 */
175 boolean isCustomizeResultsEnabled(String documentTypeName);
176
177 /**
178 * Indicates if the {@link #customizeResultSetConfiguration(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria)}
179 * on this customizer should be invoked for the document type with the given name. The caller of this method is
180 * permitted to cache the return value for a length of time of their choosing.
181 *
182 * @param documentTypeName the name of the document type against which this customizer is being applied
183 * @return true if the customization method should be executed, false otherwise
184 */
185 boolean isCustomizeResultSetFieldsEnabled(String documentTypeName);
186
187 }