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.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 name of a "viewer" of a document (someone who received an action request
114 * related to the document) to search against when executing the document search. Follows the rules for principal
115 * name criteria (see class-level documentation).
116 *
117 * @return the viewer principal name criteria
118 */
119 String getViewerPrincipalName();
120
121 /**
122 * Returns the criteria for the id of a group who is a "viewer" of a document (a group who received an action request
123 * related to the document) to search against when executing the document search. Group id criteria follows rules
124 * similar to principal name criteria:
125 *
126 * <ul>
127 * <li>only literal group ids that resolve to a valid group are allowed</li>
128 * <li>however, if the group ids don't resolve to valid groups, this simply means the search will return no results</li>
129 * <li>"!" is allowed before a group id</li>
130 * <li>when wanting to search on more than one viewer group id, use of "|" and "&&" is allowed, though they cannot be used together</li>
131 * </ul>
132 *
133 * @return the viewer principal name criteria
134 */
135 String getGroupViewerId();
136
137 /**
138 * Returns the criteria for the name 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 name criteria follows rules
140 * similar to principal name criteria:
141 *
142 * <ul>
143 * <li>only literal group names that resolve to a valid group are allowed</li>
144 * <li>however, if the group names 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 name, 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 getGroupViewerName();
152
153 /**
154 * Returns the criteria for the principal name of an "approver" of a document (someone who took action against
155 * the document) to search against when executing the document search. Follows the rules for principal name
156 * criteria (see class-level documentation).
157 *
158 * @return the viewer principal name criteria
159 */
160 String getApproverPrincipalName();
161
162 /**
163 * Returns the route node name criteria to search against when executing the document search. By default this will
164 * match only documents which are at the node with the given name, unless {@link #getRouteNodeLookupLogic()} returns
165 * a non-null value that specifies different criteria for how the route node-based lookup should be performed.
166 *
167 * @return the route node name criteria
168 */
169 String getRouteNodeName();
170
171 /**
172 * Returns the logic that should be used when performing a document search against the route name. This essentially
173 * allows for the criteria to specify whether or not it should look at documents which are currently before, exactly
174 * at, or after the specified route node. This value only has an effect if the route node name is also defined
175 * on this criteria.
176 *
177 * @return the route node lookup logic to use in conjunction with the route node name criteria
178 */
179 RouteNodeLookupLogic getRouteNodeLookupLogic();
180
181 /**
182 * Returns the document type name criteria to search against when executing the document search. If the document
183 * type name matches a single document type exactly, this might trigger document search customizations which are
184 * tied to that document type (assuming the document type has such customizations configured).
185 *
186 * <p>In order for the map of document attribute values to be properly searchable, this document type name should
187 * result to a valid document type. This is because the document type itself defines information about custom
188 * document attributes and the parameters around how searches against those attributes can be executed.</p>
189 *
190 * <p>Note that searches against a document type name should be document type hierarchy-aware. Meaning that the
191 * search should also return results for any documents that have document types that are children of the specified
192 * document type name (assuming that the specified document type name is valid and not wildcarded at all).</p>
193 *
194 * @return the document type name criteria
195 */
196 String getDocumentTypeName();
197
198 /**
199 * Returns an optional list of additional document type name criteria against which to search. The search should
200 * effectively return all documents that have a document type name within the set of the main document type name on
201 * the criteria as well as any additional document type names.
202 *
203 * <p>As with {@link #getDocumentTypeName()}, the additional document type name criteria is document type hierarchy
204 * aware.</p>
205 *
206 * @return the list of additional document type names to use on the search criteria
207 */
208 List<String> getAdditionalDocumentTypeNames();
209
210 /**
211 * Returns the inclusive lower end of the date created criteria to search against when executing the document search.
212 *
213 * @return the date created "from" criteria
214 */
215 DateTime getDateCreatedFrom();
216
217 /**
218 * Returns the inclusive upper end of the date created criteria to search against when executing the document search.
219 *
220 * @return the date created "to" criteria
221 */
222 DateTime getDateCreatedTo();
223
224 /**
225 * Returns the inclusive lower end of the date last modified criteria to search against when executing the document search.
226 *
227 * @return the date last modified "from" criteria
228 */
229 DateTime getDateLastModifiedFrom();
230
231 /**
232 * Returns the inclusive upper end of the date last modified criteria to search against when executing the document search.
233 *
234 * @return the date last modified "to" criteria
235 */
236 DateTime getDateLastModifiedTo();
237
238 /**
239 * Returns the inclusive lower end of the date approved criteria to search against when executing the document search.
240 *
241 * @return the date approved "from" criteria
242 */
243 DateTime getDateApprovedFrom();
244
245 /**
246 * Returns the inclusive upper end of the date approved criteria to search against when executing the document search.
247 *
248 * @return the date approved "tp" criteria
249 */
250 DateTime getDateApprovedTo();
251
252 /**
253 * Returns the inclusive lower end of the date finalized criteria to search against when executing the document search.
254 *
255 * @return the date finalized "from" criteria
256 */
257 DateTime getDateFinalizedFrom();
258
259 /**
260 * Returns the inclusive upper end of the date finalized criteria to search against when executing the document search.
261 *
262 * @return the date finalized "to" criteria
263 */
264 DateTime getDateFinalizedTo();
265
266 /**
267 * Returns the inclusive lower end of the date of application document status change criteria to search against when executing the document search.
268 *
269 * @return the date application document status changed "from" criteria
270 */
271 DateTime getDateApplicationDocumentStatusChangedFrom();
272
273 /**
274 * Returns the inclusive upper end of the date of application document status change criteria to search against when executing the document search.
275 *
276 * @return the date application document status changed "to" criteria
277 */
278 DateTime getDateApplicationDocumentStatusChangedTo();
279
280 /**
281 * Returns a map of document attribute values to search against when executing the document search. The key of the
282 * map is the name of the document attribute, while the list of values contains values of those attributes to search
283 * against. These individual attribute values support the different search operations where appropriate. The
284 * resulting List of criteria values however should ultimately be "or"-ed together when executing the document
285 * search.
286 *
287 * <p>In order for the document attribute values to be processed as part of the criteria during the search, the
288 * {@link #getDocumentTypeName()} must return a valid name of a document type which is configured to understand the
289 * attributes passed as part of the document attribute values map.</p>
290 * @return
291 */
292 Map<String, List<String>> getDocumentAttributeValues();
293
294 /**
295 * Returns a map of custom options for document search when either executing the document search or returning results.
296 * The key of the map is the name of the document attribute, while the list of values contains values of those
297 * attributes to customize against.
298 *
299 * <p>In order for the search options to be processed as part of the criteria during the search, a custom document
300 * search customizer must be used to fill and process these values.
301 * @since 2.1.1
302 * @return
303 */
304 Map<String, List<String>> getSearchOptions();
305
306 /**
307 * Return the name under which to save this criteria so that it can be recalled and used again in the future. If no
308 * save name is specified, then this criteria will not be saved for future use.
309 * @return
310 */
311 String getSaveName();
312
313 /**
314 * Returns the 0-based index in the result set at which to start returning results from a document search which is
315 * performed using this criteria. If not specified, results from the search should be returned starting at the
316 * beginning of the result set. If this index is larger then the total number of results returned by the actual
317 * search, then no values should be returned.
318 *
319 * @return the index in the result set at which to begin returning results
320 */
321 Integer getStartAtIndex();
322
323 /**
324 * Returns the requested maximum number of documents that should be returned from a document search performed using this
325 * criteria. If not specified, it is up to the document search implementation to decide how many results to return.
326 * It is likely in such cases that the implementation will use a default result cap in order to prevent too many
327 * documents from being returned.
328 *
329 * <p>It is important to note that this value is meant simply as a request to the document search for the number of
330 * results to return. The implementation may return fewer results then requested if it decides to impose it's own
331 * internal cap on results.</p>
332 *
333 * @return the requested number of maximum document results that should be returned from the search
334 */
335 Integer getMaxResults();
336
337 /**
338 * Returns a string that indicates if a query was run in advanced mode.
339 *
340 * @return whether or not the search was run in advanced mode
341 */
342 String getIsAdvancedSearch();
343
344 /**
345 * Return the list of application document statuses to match when executing the document search.
346 *
347 * @since 2.1.2
348 * @return the list of application document statuses to match
349 */
350 List<String> getApplicationDocumentStatuses();
351
352 /**
353 * Returns the principalId of the user performing the search
354 *
355 * @since 2.1.2
356 * @return
357 */
358 String getDocSearchUserId();
359 }