1 /**
2 * Copyright 2005-2013 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.api.document.search;
17
18 import org.joda.time.DateTime;
19 import org.kuali.rice.kew.api.document.DocumentStatus;
20 import org.kuali.rice.kew.api.document.DocumentStatusCategory;
21
22 import java.util.List;
23 import java.util.Map;
24
25 /**
26 * Defines the contract for criteria used to perform lookups of workflow document data. None of the elements that can
27 * be defined on the criteria are required. Therefore, any method on this class may return a null value, though in the
28 * case of collections, an empty collection will be returned instead.
29 *
30 * <p>In general, the different values on the criteria allow the standard lookup "operators" as defined by
31 * {@link org.kuali.rice.core.api.search.SearchOperator} unless otherwise noted. The primary place where this differs
32 * is on principal name-based criteria (see below).</p>
33 *
34 * <p><On criteria which contains a principal name, the rules are as follows:</p>
35 *
36 * <ul>
37 * <li>only literal principal names that resolve to a valid principal are allowed</li>
38 * <li>however, if the principal names don't resolve to valid prinicpals, this simply means the lookup will return no results</li>
39 * <li>"!" is allowed before a principal name</li>
40 * <li>when wanting to search for more than one principal, "|" and "&&" is allowed though they cannot be used together</li>
41 * </ul>
42 *
43 * <p>Wildcards, ranges, and other "inequality" operators (such as ">", "<", etc.) are not permitted on principal names.</p>
44 *
45 * <p>In cases where a criteria element takes a list of values, this should be treated as an implicit "OR" by the lookup
46 * implementation. This is true of document attribute values as well, which are passed as a map keyed off the
47 * document attribute name with a list of values representing the document attribute values to be searched for.</p>
48 *
49 * <p>The optional "save name" on the search defines a name under which the criteria can be stored so that it can be
50 * recalled and reused later.</p>
51 *
52 * @author Kuali Rice Team (rice.collab@kuali.org)
53 */
54 public interface DocumentSearchCriteriaContract {
55
56 /**
57 * Returns the document id criteria to search against when executing the document search.
58 *
59 * @return the document id criteria
60 */
61 String getDocumentId();
62
63 /**
64 * Returns an unmodifiable list of document statuses to search against when executing the document search. If there
65 * is more than one of these, then the search should treat this as an "OR" case (i.e. search for documents with one
66 * or more of these statuses).
67 *
68 * @return the document status criteria
69 */
70 List<DocumentStatus> getDocumentStatuses();
71
72 /**
73 * Returns an unmodifiable list of document status categories to search against when executing the document search.
74 * If there is more than one of these, then the search should treat this as an "OR" case (i.e. search for documents
75 * that have a status contained in one or more of these categories).
76 *
77 * @return the document status category criteria
78 */
79 List<DocumentStatusCategory> getDocumentStatusCategories();
80
81 /**
82 * Returns the document title criteria to search against when executing the document search.
83 *
84 * @return the title criteria
85 */
86 String getTitle();
87
88 /**
89 * Returns the application document id criteria to search against when executing the document search.
90 *
91 * @return the application document id criteria
92 */
93 String getApplicationDocumentId();
94
95 /**
96 * Returns the application document status criteria to search against when executing the document search.
97 *
98 * @return the application document status criteria
99 * @deprecated please use {@link #getApplicationDocumentStatuses()} instead
100 */
101 @Deprecated
102 String getApplicationDocumentStatus();
103
104 /**
105 * Returns the criteria for the principal name of the document initiator to search against when executing the
106 * document search. Follows the rules for principal name criteria (see class-level documentation).
107 *
108 * @return the initiator principal name criteria
109 */
110 String getInitiatorPrincipalName();
111
112 /**
113 * Returns the criteria for the principal id of the document initiator to search against when executing the
114 * document search.
115 *
116 * @return the initiator principal id criteria
117 */
118 String getInitiatorPrincipalId();
119
120 /**
121 * Returns the criteria for the principal name of a "viewer" of a document (someone who received an action request
122 * related to the document) to search against when executing the document search. Follows the rules for principal
123 * name criteria (see class-level documentation).
124 *
125 * @return the viewer principal name criteria
126 */
127 String getViewerPrincipalName();
128
129 /**
130 * Returns the criteria for the principal id of a "viewer" of a document (someone who received an action request
131 * related to the document) to search against when executing the document search.
132 *
133 * @return the viewer principal id criteria
134 */
135 String getViewerPrincipalId();
136
137 /**
138 * Returns the criteria for the id of a group who is a "viewer" of a document (a group who received an action request
139 * related to the document) to search against when executing the document search. Group id criteria follows rules
140 * similar to principal name criteria:
141 *
142 * <ul>
143 * <li>only literal group ids that resolve to a valid group are allowed</li>
144 * <li>however, if the group ids don't resolve to valid groups, this simply means the search will return no results</li>
145 * <li>"!" is allowed before a group id</li>
146 * <li>when wanting to search on more than one viewer group id, use of "|" and "&&" is allowed, though they cannot be used together</li>
147 * </ul>
148 *
149 * @return the viewer principal name criteria
150 */
151 String getGroupViewerId();
152
153 /**
154 * Returns the criteria for the name of a group who is a "viewer" of a document (a group who received an action request
155 * related to the document) to search against when executing the document search. Group name criteria follows rules
156 * similar to principal name criteria:
157 *
158 * <ul>
159 * <li>only literal group names that resolve to a valid group are allowed</li>
160 * <li>however, if the group names don't resolve to valid groups, this simply means the search will return no results</li>
161 * <li>"!" is allowed before a group id</li>
162 * <li>when wanting to search on more than one viewer group name, use of "|" and "&&" is allowed, though they cannot be used together</li>
163 * </ul>
164 *
165 * @return the viewer principal name criteria
166 */
167 String getGroupViewerName();
168
169 /**
170 * Returns the criteria for the principal name of an "approver" of a document (someone who took action against
171 * the document) to search against when executing the document search. Follows the rules for principal name
172 * criteria (see class-level documentation).
173 *
174 * @return the viewer principal name criteria
175 */
176 String getApproverPrincipalName();
177
178 /**
179 * Returns the criteria for the principal id of an "approver" of a document (someone who took action against
180 * the document) to search against when executing the document search.
181 *
182 * @return the viewer principal id criteria
183 */
184 String getApproverPrincipalId();
185
186 /**
187 * Returns the route node name criteria to search against when executing the document search. By default this will
188 * match only documents which are at the node with the given name, unless {@link #getRouteNodeLookupLogic()} returns
189 * a non-null value that specifies different criteria for how the route node-based lookup should be performed.
190 *
191 * @return the route node name criteria
192 */
193 String getRouteNodeName();
194
195 /**
196 * Returns the logic that should be used when performing a document search against the route name. This essentially
197 * allows for the criteria to specify whether or not it should look at documents which are currently before, exactly
198 * at, or after the specified route node. This value only has an effect if the route node name is also defined
199 * on this criteria.
200 *
201 * @return the route node lookup logic to use in conjunction with the route node name criteria
202 */
203 RouteNodeLookupLogic getRouteNodeLookupLogic();
204
205 /**
206 * Returns the document type name criteria to search against when executing the document search. If the document
207 * type name matches a single document type exactly, this might trigger document search customizations which are
208 * tied to that document type (assuming the document type has such customizations configured).
209 *
210 * <p>In order for the map of document attribute values to be properly searchable, this document type name should
211 * result to a valid document type. This is because the document type itself defines information about custom
212 * document attributes and the parameters around how searches against those attributes can be executed.</p>
213 *
214 * <p>Note that searches against a document type name should be document type hierarchy-aware. Meaning that the
215 * search should also return results for any documents that have document types that are children of the specified
216 * document type name (assuming that the specified document type name is valid and not wildcarded at all).</p>
217 *
218 * @return the document type name criteria
219 */
220 String getDocumentTypeName();
221
222 /**
223 * Returns an optional list of additional document type name criteria against which to search. The search should
224 * effectively return all documents that have a document type name within the set of the main document type name on
225 * the criteria as well as any additional document type names.
226 *
227 * <p>As with {@link #getDocumentTypeName()}, the additional document type name criteria is document type hierarchy
228 * aware.</p>
229 *
230 * @return the list of additional document type names to use on the search criteria
231 */
232 List<String> getAdditionalDocumentTypeNames();
233
234 /**
235 * Returns the inclusive lower end of the date created criteria to search against when executing the document search.
236 *
237 * @return the date created "from" criteria
238 */
239 DateTime getDateCreatedFrom();
240
241 /**
242 * Returns the inclusive upper end of the date created criteria to search against when executing the document search.
243 *
244 * @return the date created "to" criteria
245 */
246 DateTime getDateCreatedTo();
247
248 /**
249 * Returns the inclusive lower end of the date last modified criteria to search against when executing the document search.
250 *
251 * @return the date last modified "from" criteria
252 */
253 DateTime getDateLastModifiedFrom();
254
255 /**
256 * Returns the inclusive upper end of the date last modified criteria to search against when executing the document search.
257 *
258 * @return the date last modified "to" criteria
259 */
260 DateTime getDateLastModifiedTo();
261
262 /**
263 * Returns the inclusive lower end of the date approved criteria to search against when executing the document search.
264 *
265 * @return the date approved "from" criteria
266 */
267 DateTime getDateApprovedFrom();
268
269 /**
270 * Returns the inclusive upper end of the date approved criteria to search against when executing the document search.
271 *
272 * @return the date approved "tp" criteria
273 */
274 DateTime getDateApprovedTo();
275
276 /**
277 * Returns the inclusive lower end of the date finalized criteria to search against when executing the document search.
278 *
279 * @return the date finalized "from" criteria
280 */
281 DateTime getDateFinalizedFrom();
282
283 /**
284 * Returns the inclusive upper end of the date finalized criteria to search against when executing the document search.
285 *
286 * @return the date finalized "to" criteria
287 */
288 DateTime getDateFinalizedTo();
289
290 /**
291 * Returns the inclusive lower end of the date of application document status change criteria to search against when executing the document search.
292 *
293 * @return the date application document status changed "from" criteria
294 */
295 DateTime getDateApplicationDocumentStatusChangedFrom();
296
297 /**
298 * Returns the inclusive upper end of the date of application document status change criteria to search against when executing the document search.
299 *
300 * @return the date application document status changed "to" criteria
301 */
302 DateTime getDateApplicationDocumentStatusChangedTo();
303
304 /**
305 * Returns a map of document attribute values to search against when executing the document search. The key of the
306 * map is the name of the document attribute, while the list of values contains values of those attributes to search
307 * against. These individual attribute values support the different search operations where appropriate. The
308 * resulting List of criteria values however should ultimately be "or"-ed together when executing the document
309 * search.
310 *
311 * <p>In order for the document attribute values to be processed as part of the criteria during the search, the
312 * {@link #getDocumentTypeName()} must return a valid name of a document type which is configured to understand the
313 * attributes passed as part of the document attribute values map.</p>
314 * @return
315 */
316 Map<String, List<String>> getDocumentAttributeValues();
317
318 /**
319 * Returns a map of custom options for document search when either executing the document search or returning results.
320 * The key of the map is the name of the document attribute, while the list of values contains values of those
321 * attributes to customize against.
322 *
323 * <p>In order for the search options to be processed as part of the criteria during the search, a custom document
324 * search customizer must be used to fill and process these values.
325 * @since 2.1.1
326 * @return
327 */
328 Map<String, List<String>> getSearchOptions();
329
330 /**
331 * Return the name under which to save this criteria so that it can be recalled and used again in the future. If no
332 * save name is specified, then this criteria will not be saved for future use.
333 * @return
334 */
335 String getSaveName();
336
337 /**
338 * Returns the 0-based index in the result set at which to start returning results from a document search which is
339 * performed using this criteria. If not specified, results from the search should be returned starting at the
340 * beginning of the result set. If this index is larger then the total number of results returned by the actual
341 * search, then no values should be returned.
342 *
343 * @return the index in the result set at which to begin returning results
344 */
345 Integer getStartAtIndex();
346
347 /**
348 * Returns the requested maximum number of documents that should be returned from a document search performed using this
349 * criteria. If not specified, it is up to the document search implementation to decide how many results to return.
350 * It is likely in such cases that the implementation will use a default result cap in order to prevent too many
351 * documents from being returned.
352 *
353 * <p>It is important to note that this value is meant simply as a request to the document search for the number of
354 * results to return. The implementation may return fewer results then requested if it decides to impose it's own
355 * internal cap on results.</p>
356 *
357 * @return the requested number of maximum document results that should be returned from the search
358 */
359 Integer getMaxResults();
360
361 /**
362 * Returns a string that indicates if a query was run in advanced mode.
363 *
364 * @return whether or not the search was run in advanced mode
365 */
366 String getIsAdvancedSearch();
367
368 /**
369 * Return the list of application document statuses to match when executing the document search.
370 *
371 * @since 2.1.2
372 * @return the list of application document statuses to match
373 */
374 List<String> getApplicationDocumentStatuses();
375
376 /**
377 * Returns the principalId of the user performing the search
378 *
379 * @since 2.1.2
380 * @return
381 */
382 String getDocSearchUserId();
383 }