001 /**
002 * Copyright 2005-2012 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.kuali.rice.kew.api;
017
018 import java.util.List;
019 import java.util.Set;
020
021 import org.kuali.rice.core.api.uif.RemotableAttributeErrorContract;
022 import org.kuali.rice.kew.api.action.ActionRequest;
023 import org.kuali.rice.kew.api.action.ActionRequestType;
024 import org.kuali.rice.kew.api.action.ActionTaken;
025 import org.kuali.rice.kew.api.action.ActionType;
026 import org.kuali.rice.kew.api.action.AdHocRevoke;
027 import org.kuali.rice.kew.api.action.AdHocToGroup;
028 import org.kuali.rice.kew.api.action.AdHocToPrincipal;
029 import org.kuali.rice.kew.api.action.MovePoint;
030 import org.kuali.rice.kew.api.action.RequestedActions;
031 import org.kuali.rice.kew.api.action.ReturnPoint;
032 import org.kuali.rice.kew.api.action.ValidActions;
033 import org.kuali.rice.kew.api.document.Document;
034 import org.kuali.rice.kew.api.document.DocumentContent;
035 import org.kuali.rice.kew.api.document.DocumentContentUpdate;
036 import org.kuali.rice.kew.api.document.DocumentContract;
037 import org.kuali.rice.kew.api.document.DocumentDetail;
038 import org.kuali.rice.kew.api.document.DocumentStatus;
039 import org.kuali.rice.kew.api.document.attribute.WorkflowAttributeDefinition;
040 import org.kuali.rice.kew.api.document.node.RouteNodeInstance;
041
042 /**
043 * WorkflowDocument is the core client API for interaction with the Kuali Enterprise Workflow system.
044 * WorkflowDocument is an object-oriented facade/bridge to stateless KEW APIs, which maintains document
045 * state, and flushes updates as actions are taken.
046 *
047 * WorkflowDocuments cannot be constructed directly, create them via the {@link WorkflowDocumentFactory}
048 *
049 * <p><b>This class is *not* thread safe.</b> If you are operating on the same document, be sure to synchronize
050 * access to the {@link WorkflowDocument} instance. If you are operating on different documents, obtain a distinct
051 * instance from the {@link WorkflowDocumentFactory}.</p>
052 */
053 public interface WorkflowDocument extends DocumentContract {
054 /**
055 * Returns the principalId with which this WorkflowDocument was constructed
056 * @return the principalId with which this WorkflowDocument was constructed
057 */
058 String getPrincipalId();
059 /**
060 * Switches the principalId under which WorkflowDocument API are performed.
061 * This method necessitates clearing of any state associated with the principalId
062 * such as requested and valid actions.
063 * @param principalId the new principalId
064 */
065 void switchPrincipal(String principalId);
066
067 /**
068 * Returns a read-only view of the underlying document meta-data
069 * @return a read-only view of the underlying document meta-data
070 */
071 Document getDocument();
072
073 /**
074 * Returns a read-only view of the underlying mutable document content
075 * @return a read-only view of the underlying mutable document content
076 */
077 DocumentContent getDocumentContent();
078
079 /**
080 * Returns the currently set application content.
081 * @return the currently set application content.
082 * @see #getDocumentContent()
083 */
084 String getApplicationContent();
085
086 /**
087 * Sets the document title. The update will be committed with the next document operation.
088 * @param title the document title to set
089 */
090 void setTitle(String title);
091
092 /**
093 * Sets the application document id. The update will be committed with the next document operation.
094 * @param applicationDocumentId the application document id to set.
095 */
096 void setApplicationDocumentId(String applicationDocumentId);
097
098 /**
099 * Sets the application document status. The update will be committed with the next document operation.
100 * @param applicationDocumentStatus the application document status to set
101 */
102 void setApplicationDocumentStatus(String applicationDocumentStatus);
103
104 /**
105 * Sets the document's application content. The update will be committed with the next document operation.
106 * @param applicationContent the document application content to set
107 */
108 void setApplicationContent(String applicationContent);
109
110 /**
111 * Sets the document's attribute content. The update will be committed with the next document operation.
112 * @param attributeContent the document attribute content to set
113 */
114 void setAttributeContent(String attributeContent);
115 /**
116 * Clears the document's attribute content. The update will be committed with the next document operation.
117 */
118 void clearAttributeContent();
119 /**
120 * Returns the currently set document attribute content.
121 */
122 String getAttributeContent();
123
124 /**
125 * Adds a workflow attribute definition. The update will be committed with the next document operation.
126 * @param attributeDefinition the WorkflowAttributeDefinition to add
127 */
128 void addAttributeDefinition(WorkflowAttributeDefinition attributeDefinition);
129 /**
130 * Removes a workflow attribute definition. The update will be committed with the next document operation.
131 * Equality is determined on the basis of WorkflowAttributeDefinition fields.
132 * @see org.kuali.rice.core.api.mo.AbstractDataTransferObject#equals(Object)
133 * @param attributeDefinition the WorkflowAttributeDefinition to remove
134 */
135 void removeAttributeDefinition(WorkflowAttributeDefinition attributeDefinition);
136 /**
137 * Clears workflow attribute definitions. The update will be committed with the next document operation.
138 */
139 void clearAttributeDefinitions();
140 /**
141 * Returns the currently set workflow attribute definitions
142 * @return the currently set workflow attribute definitions
143 */
144 List<WorkflowAttributeDefinition> getAttributeDefinitions();
145
146 /**
147 * Sets the document's searchable content. The update will be committed with the next document operation.
148 * @param searchableContent the searchable content to set
149 */
150 public void setSearchableContent(String searchableContent);
151 /**
152 * Adds a searchable workflow attribute definition. The update will be committed with the next document operation.
153 * @param searchableDefinition the WorkflowAttributeDefinition to add
154 */
155 void addSearchableDefinition(WorkflowAttributeDefinition searchableDefinition);
156 /**
157 * Removes a searchable workflow attribute definition. The update will be committed with the next document operation.
158 * Equality is determined on the basis of WorkflowAttributeDefinition fields.
159 * @see org.kuali.rice.core.api.mo.AbstractDataTransferObject#equals(Object)
160 * @param searchableDefinition the WorkflowAttributeDefinition to remove
161 */
162 void removeSearchableDefinition(WorkflowAttributeDefinition searchableDefinition);
163 /**
164 * Clears searchable workflow attribute definitions. The update will be committed with the next document operation.
165 */
166 void clearSearchableDefinitions();
167 /**
168 * Clears the searchable content. The update will be committed with the next document operation.
169 */
170 void clearSearchableContent();
171 /**
172 * Returns the currently set searchable workflow attribute definitions
173 * @return the currently set searchable workflow attribute definitions
174 */
175 List<WorkflowAttributeDefinition> getSearchableDefinitions();
176
177 /**
178 * Sets a workflow variable. The update will be committed with the next document operation.
179 * @see #getVariables()
180 * @param name variable name
181 * @param value variable value
182 */
183 void setVariable(String name, String value);
184 /**
185 * Gets a workflow variable value.
186 * @see #getVariables()
187 * @param name variable name
188 */
189 String getVariableValue(String name);
190 /**
191 * Sets the workflow variable that specifies that this principal should receive future requests
192 * @see KewApiConstants#RECEIVE_FUTURE_REQUESTS_BRANCH_STATE_KEY
193 * @see KewApiConstants#RECEIVE_FUTURE_REQUESTS_BRANCH_STATE_VALUE
194 */
195 void setReceiveFutureRequests();
196 /**
197 * Sets the workflow variable that specifies that this principal should NOT receive future requests
198 * @see KewApiConstants#RECEIVE_FUTURE_REQUESTS_BRANCH_STATE_KEY
199 * @see KewApiConstants#DONT_RECEIVE_FUTURE_REQUESTS_BRANCH_STATE_VALUE
200 */
201 void setDoNotReceiveFutureRequests();
202 /**
203 * Sets the workflow variable that specifies that ...
204 * TODO: what does this do? (org.kuali.rice.kew.util.FutureRequestDocumentStateManager#clearStateFromDocument)
205 * @see KewApiConstants#RECEIVE_FUTURE_REQUESTS_BRANCH_STATE_KEY
206 * @see KewApiConstants#CLEAR_FUTURE_REQUESTS_BRANCH_STATE_VALUE
207 */
208 void setClearFutureRequests();
209 /**
210 * Returns whether the workflow variable that specifies that this principal should receive future requests has been set
211 * @see #setReceiveFutureRequests()
212 * @return whether the workflow variable that specifies that this principal should receive future requests has been set
213 */
214 String getReceiveFutureRequestsValue();
215 /**
216 * Returns whether the workflow variable that specifies that this principal should NOT receive future requests has been set
217 * @see #setDoNotReceiveFutureRequests()
218 * @return whether the workflow variable that specifies that this principal should NOT receive future requests has been set
219 */
220 String getDoNotReceiveFutureRequestsValue();
221 /**
222 * Returns whether the workflow variable that specifies that ... has been set
223 * @return whether the workflow variable that specifies that ... has been set
224 */
225 String getClearFutureRequestsValue();
226
227 /**
228 * Validates a workflow attribute definition and returns a list of validation errors.
229 * This action is stateless and does not cause a commit of document updates.
230 *
231 * Implementation note: this is currently only used by EDL.
232 *
233 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#validateWorkflowAttributeDefinition(org.kuali.rice.kew.api.document.attribute.WorkflowAttributeDefinition)
234 * @param attributeDefinition the workflow attribute definition to validate
235 * @return list of attribute validation errors
236 */
237 List<? extends RemotableAttributeErrorContract> validateAttributeDefinition(WorkflowAttributeDefinition attributeDefinition);
238
239 /**
240 * Return the list of root action requests on the document.
241 * @return the list of root action requests on the document.
242 * @see org.kuali.rice.kew.api.document.WorkflowDocumentService#getRootActionRequests(String)
243 */
244 List<ActionRequest> getRootActionRequests();
245
246 /**
247 * Return the list of past actions taken on the document
248 * @return the list of past actions taken on the document
249 * @see org.kuali.rice.kew.api.document.WorkflowDocumentService#getActionsTaken(String)
250 */
251 List<ActionTaken> getActionsTaken();
252
253 /**
254 * Returns the list of valid actions on this document for the current user
255 * @return the list of valid actions on this document for the current user
256 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#determineValidActions(String, String)
257 */
258 ValidActions getValidActions();
259
260 /**
261 * Returns the list of requested actions on this document for the current user
262 * @return the list of requested actions on this document for the current user
263 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#determineRequestedActions(String, String)
264 */
265 RequestedActions getRequestedActions();
266
267 /**
268 * Saves the document, commits updates.
269 * @param annotation the document action annotation
270 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#save(org.kuali.rice.kew.api.action.DocumentActionParameters)
271 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
272 */
273 void saveDocument(String annotation);
274 /**
275 * Routes the document, commits updates.
276 * @param annotation the document action annotation
277 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#route(org.kuali.rice.kew.api.action.DocumentActionParameters)
278 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
279 */
280 void route(String annotation);
281 /**
282 * Completes the document, commits updates.
283 * @param annotation the document action annotation
284 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#complete(org.kuali.rice.kew.api.action.DocumentActionParameters)
285 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
286 */
287 void complete(String annotation);
288 /**
289 * Disapproves the document, commits updates.
290 * @param annotation the document action annotation
291 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#route(org.kuali.rice.kew.api.action.DocumentActionParameters)
292 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
293 */
294 void disapprove(String annotation);
295 /**
296 * Approves the document, commits updates.
297 * @param annotation the document action annotation
298 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#approve(org.kuali.rice.kew.api.action.DocumentActionParameters)
299 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
300 */
301 void approve(String annotation);
302 /**
303 * Approves the document, commits updates.
304 * @param annotation the document action annotation
305 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#approve(org.kuali.rice.kew.api.action.DocumentActionParameters)
306 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
307 */
308 void cancel(String annotation);
309 /**
310 * Recalls the document, commits updates.
311 * @since 2.1
312 * @param annotation the document action annotation
313 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#approve(org.kuali.rice.kew.api.action.DocumentActionParameters)
314 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
315 */
316 void recall(String annotation, boolean cancel);
317 /**
318 * Cancels the document, commits updates.
319 * @param annotation the document action annotation
320 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#cancel(org.kuali.rice.kew.api.action.DocumentActionParameters)
321 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
322 */
323 void blanketApprove(String annotation);
324 /**
325 * Blanket-approves the document, commits updates.
326 * @param annotation the document action annotation
327 * @param nodeNames a set of node names to which to blanket approve the given document
328 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#blanketApproveToNodes(org.kuali.rice.kew.api.action.DocumentActionParameters, java.util.Set)
329 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
330 */
331 void blanketApprove(String annotation, String... nodeNames);
332 /**
333 * Save the document data without affecting routing, commits updates.
334 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#saveDocumentData(org.kuali.rice.kew.api.action.DocumentActionParameters)
335 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
336 */
337 void saveDocumentData();
338 /**
339 * Acknowledges the document, commits updates.
340 * @param annotation the document action annotation
341 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#acknowledge(org.kuali.rice.kew.api.action.DocumentActionParameters)
342 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
343 */
344 void acknowledge(String annotation);
345 /**
346 * Clears an outstanding FYI on the document, commits updates.
347 * @param annotation the document action annotation
348 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#clearFyi(org.kuali.rice.kew.api.action.DocumentActionParameters)
349 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
350 */
351 void fyi(String annotation);
352 /**
353 * Clears an outstanding FYI on the document without an annotation, commits updates.
354 * @see #fyi(String)
355 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
356 */
357 void fyi();
358 /**
359 * Deletes the document. Any pending updates are <b>NOT</b> committed, they are discarded.
360 * After deletion this WorkflowDocument object will no longer be valid, and any operations
361 * that interact with the workflow system will throws an {@link IllegalStateException}
362 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#delete(String, String)
363 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidActionTakenException
364 */
365 void delete();
366 /**
367 * Reloads the document state, any pending changes will be <i><b>discarded</b></i>
368 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
369 * @see org.kuali.rice.kew.api.document.WorkflowDocumentService#getDocument(String)
370 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
371 */
372 void refresh();
373 /**
374 * Sends an "ad-hoc" action request to the specified principal; commits updates.
375 * @param actionRequested the request action type
376 * @param annotation the route annotation
377 * @param targetPrincipalId the target principal id
378 * @param responsibilityDescription description of the responsibility
379 * @param forceAction whether the adhoc requests forces action by the recipient
380 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#adHocToPrincipal(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.AdHocToPrincipal)
381 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
382 */
383 void adHocToPrincipal(ActionRequestType actionRequested, String annotation,
384 String targetPrincipalId, String responsibilityDescription,
385 boolean forceAction);
386 /**
387 * Sends an "ad-hoc" action request to the specified principal; commits updates.
388 * @param actionRequested the request action type
389 * @param nodeName the node on which to generate the adhoc request
390 * @param annotation the route annotation
391 * @param targetPrincipalId the target principal id
392 * @param responsibilityDescription description of the responsibility
393 * @param forceAction whether the adhoc requests forces action by the recipient
394 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#adHocToPrincipal(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.AdHocToPrincipal)
395 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
396 */
397 void adHocToPrincipal(ActionRequestType actionRequested, String nodeName,
398 String annotation, String targetPrincipalId,
399 String responsibilityDescription, boolean forceAction);
400 /**
401 * Sends an "ad-hoc" action request to the specified principal; commits updates.
402 * @param actionRequested the request action type
403 * @param nodeName the node on which to generate the adhoc request
404 * @param annotation the route annotation
405 * @param targetPrincipalId the target principal id
406 * @param responsibilityDescription description of the responsibility
407 * @param forceAction whether the adhoc requests forces action by the recipient
408 * @param requestLabel the request label
409 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#adHocToPrincipal(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.AdHocToPrincipal)
410 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
411 */
412 void adHocToPrincipal(ActionRequestType actionRequested, String nodeName,
413 String annotation, String targetPrincipalId,
414 String responsibilityDescription, boolean forceAction,
415 String requestLabel);
416 /**
417 * Sends an "ad-hoc" action request to the specified principal; commits updates.
418 * @param adHocToPrincipal a pre-constructed AdHocToPrincipal object
419 * @param annotation the route annotation
420 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#adHocToPrincipal(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.AdHocToPrincipal)
421 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
422 */
423 void adHocToPrincipal(AdHocToPrincipal adHocToPrincipal, String annotation);
424 /**
425 * Sends an "ad-hoc" action request to the specified group; commits updates.
426 * @param actionRequested the request action type
427 * @param annotation the route annotation
428 * @param targetGroupId the target group id
429 * @param responsibilityDescription description of the responsibility
430 * @param forceAction whether the adhoc requests forces action by the recipient
431 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#adHocToGroup(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.AdHocToGroup)
432 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
433 */
434 void adHocToGroup(ActionRequestType actionRequested, String annotation,
435 String targetGroupId, String responsibilityDescription,
436 boolean forceAction);
437 /**
438 * Sends an "ad-hoc" action request to the specified group; commits updates.
439 * @param actionRequested the request action type
440 * @param nodeName the node on which to generate the adhoc request
441 * @param annotation the route annotation
442 * @param targetGroupId the target group id
443 * @param responsibilityDescription description of the responsibility
444 * @param forceAction whether the adhoc requests forces action by the recipient
445 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#adHocToGroup(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.AdHocToGroup)
446 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
447 */
448 void adHocToGroup(ActionRequestType actionRequested, String nodeName,
449 String annotation, String targetGroupId,
450 String responsibilityDescription, boolean forceAction);
451 /**
452 * Sends an "ad-hoc" action request to the specified principal; commits updates.
453 * @param actionRequested the request action type
454 * @param nodeName the node on which to generate the adhoc request
455 * @param annotation the route annotation
456 * @param targetGroupId the target group id
457 * @param responsibilityDescription description of the responsibility
458 * @param forceAction whether the adhoc requests forces action by the recipient
459 * @param requestLabel the request label
460 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#adHocToGroup(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.AdHocToGroup)
461 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
462 */
463 void adHocToGroup(ActionRequestType actionRequested, String nodeName,
464 String annotation, String targetGroupId,
465 String responsibilityDescription, boolean forceAction,
466 String requestLabel);
467 /**
468 * Sends an "ad-hoc" action request to the specified principal; commits updates.
469 * @param adHocToGroup a pre-constructed AdHocToGroup object
470 * @param annotation the route annotation
471 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#adHocToPrincipal(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.AdHocToPrincipal)
472 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
473 */
474 void adHocToGroup(AdHocToGroup adHocToGroup, String annotation);
475 /**
476 * Revokes an Ad-Hoc request by id; commits updates.
477 * @param actionRequestId the action request id to revoke
478 * @param annotation the routing annotation
479 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#revokeAdHocRequestById(org.kuali.rice.kew.api.action.DocumentActionParameters, String)
480 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
481 */
482 void revokeAdHocRequestById(String actionRequestId, String annotation);
483 /**
484 * Revokes an Ad-Hoc request by the specified criteria; commits updates.
485 * @param revoke the criteria for matching ad hoc action requests on the specified document that
486 * should be revoked
487 * @param annotation the routing annotation
488 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#revokeAdHocRequests(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.AdHocRevoke)
489 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
490 */
491 void revokeAdHocRequests(AdHocRevoke revoke, String annotation);
492 /**
493 * Revokes all Ad-Hoc requests; commits updates; commits updates.
494 * @param annotation the routing annotation
495 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#revokeAllAdHocRequests(org.kuali.rice.kew.api.action.DocumentActionParameters)
496 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
497 */
498 void revokeAllAdHocRequests(String annotation);
499 /**
500 * Returns the document to a previous node; commits updates.
501 * @param annotation the routing annotation
502 * @param nodeName the node to return to
503 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#returnToPreviousNode(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.ReturnPoint)
504 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
505 */
506 void returnToPreviousNode(String annotation, String nodeName);
507 /**
508 * Returns the document to a previous node; commits updates.
509 * @param annotation the routing annotation
510 * @param returnPoint the node to return to
511 * @see #returnToPreviousNode(String, String)
512 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#returnToPreviousNode(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.ReturnPoint)
513 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
514 */
515 void returnToPreviousNode(String annotation, ReturnPoint returnPoint);
516 /**
517 * Moves the document to a different node; commits updates.
518 * @param movePoint the node to move to
519 * @param annotation the routing annotation
520 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#move(org.kuali.rice.kew.api.action.DocumentActionParameters, org.kuali.rice.kew.api.action.MovePoint)
521 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
522 */
523 void move(MovePoint movePoint, String annotation);
524 /**
525 * Takes authority of a group by a member of that group; commits updates.
526 * @param annotation the routing annotation
527 * @param groupId the group for which to take authority
528 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#takeGroupAuthority(org.kuali.rice.kew.api.action.DocumentActionParameters, String)
529 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
530 */
531 void takeGroupAuthority(String annotation, String groupId);
532 /**
533 * Releases authority of a group by a member of that group; commits updates.
534 * @param annotation the routing annotation
535 * @param groupId the group for which to take authority
536 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#releaseGroupAuthority(org.kuali.rice.kew.api.action.DocumentActionParameters, String)
537 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
538 */
539 void releaseGroupAuthority(String annotation, String groupId);
540
541 /**
542 * Places the document in exception routing; commits updates.
543 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#placeInExceptionRouting(org.kuali.rice.kew.api.action.DocumentActionParameters)
544 * @param annotation the routing annotation
545 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
546 */
547 void placeInExceptionRouting(String annotation);
548
549 /**
550 * Performs a super-user blanket-approve action; commits updates.
551 * The current user must be a super-user for this document.
552 * @param annotation the routing annotation
553 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#superUserBlanketApprove(org.kuali.rice.kew.api.action.DocumentActionParameters, boolean)
554 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
555 */
556 void superUserBlanketApprove(String annotation);
557 /**
558 * Performs a super-user approve action for the specified node; commits updates.
559 * The current user must be a super-user for this document.
560 * @param nodeName the node to super-user approve
561 * @param annotation the routing annotation
562 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#superUserNodeApprove(org.kuali.rice.kew.api.action.DocumentActionParameters, boolean, String)
563 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
564 */
565 void superUserNodeApprove(String nodeName, String annotation);
566 /**
567 * Performs a super-user approve action for the specified node; commits updates.
568 * The current user must be a super-user for this document.
569 * @param actionRequestId the action request to satisfy/approve
570 * @param annotation the routing annotation
571 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#superUserTakeRequestedAction(org.kuali.rice.kew.api.action.DocumentActionParameters, boolean, String)
572 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
573 */
574 void superUserTakeRequestedAction(String actionRequestId, String annotation);
575 /**
576 * Performs a super-user disapprove action; commits updates.
577 * The current user must be a super-user for this document.
578 * @param annotation the routing annotation
579 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#superUserDisapprove(org.kuali.rice.kew.api.action.DocumentActionParameters, boolean)
580 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
581 */
582 void superUserDisapprove(String annotation);
583 /**
584 * Performs a super-user cancel action; commits updates.
585 * The current user must be a super-user for this document.
586 * @param annotation the routing annotation
587 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#superUserCancel(org.kuali.rice.kew.api.action.DocumentActionParameters, boolean)
588 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
589 */
590 void superUserCancel(String annotation);
591 /**
592 * Performs a super-user "return to previous node" action; commits updates.
593 * The current user must be a super-user for this document.
594 * @param returnPoint the node to return to
595 * @param annotation the routing annotation
596 * @see org.kuali.rice.kew.api.action.WorkflowDocumentActionsService#superUserReturnToPreviousNode(org.kuali.rice.kew.api.action.DocumentActionParameters, boolean, org.kuali.rice.kew.api.action.ReturnPoint)
597 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
598 */
599 void superUserReturnToPreviousNode(ReturnPoint returnPoint, String annotation);
600 /**
601 * Records a log action which adds an annotation on the document but does not affect routing.
602 * This action is stateless and does not cause a commit of document updates.
603 * @param annotation the annotation to log
604 * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidActionTakenException
605 */
606 void logAnnotation(String annotation);
607
608 /**
609 * Returns whether a completion request is one of the requested actions.
610 * @see #getRequestedActions()
611 * @return whether a completion request is one of the requested actions.
612 */
613 boolean isCompletionRequested();
614 /**
615 * Returns whether an approval request is one of the requested actions.
616 * @see #getRequestedActions()
617 * @return whether an approval request is one of the requested actions.
618 */
619 boolean isApprovalRequested();
620 /**
621 * Returns whether an acknowledge request is one of the requested actions.
622 * @see #getRequestedActions()
623 * @return whether an acknowledge request is one of the requested actions.
624 */
625 boolean isAcknowledgeRequested();
626 /**
627 * Returns whether an FYI is one of the requested actions.
628 * @see #getRequestedActions()
629 * @return whether an FYI is one of the requested actions.
630 */
631 boolean isFYIRequested();
632
633 /**
634 * Returns whether a blank-approve action is a valid action.
635 * @see #getValidActions()
636 * @return whether a blank-approve action is a valid action.
637 */
638 boolean isBlanketApproveCapable();
639 /**
640 * Returns whether a route action is a valid action.
641 * @see #getValidActions()
642 * @return whether a route action is a valid action.
643 */
644 boolean isRouteCapable();
645 /**
646 * Returns whether the specified action type is valid
647 * @param actionType the non-null ActionType to check
648 * @see #getValidActions()
649 * @return whether the specified action type is valid
650 */
651 boolean isValidAction(ActionType actionType);
652
653 /**
654 * Helper that checks whether the document has the given status
655 * NOTE: does this really need to be in the public API? it only appears to be used internally
656 * @see #getStatus()
657 * @param status the status to check
658 * @return whether the document status is the specified status
659 */
660 boolean checkStatus(DocumentStatus status);
661 /**
662 * Indicates if the document is in the initiated state or not.
663 * @see #getStatus()
664 * @return true if in the specified state
665 */
666 boolean isInitiated();
667 /**
668 * Indicates if the document is in the saved state or not.
669 * @see #getStatus()
670 * @return true if in the specified state
671 */
672 boolean isSaved();
673 /**
674 * Indicates if the document is in the enroute state or not.
675 * @see #getStatus()
676 * @return true if in the specified state
677 */
678 boolean isEnroute();
679 /**
680 * Indicates if the document is in the exception state or not.
681 * @see #getStatus()
682 * @return true if in the specified state
683 */
684 boolean isException();
685 /**
686 * Indicates if the document is in the canceled state or not.
687 * @see #getStatus()
688 * @return true if in the specified state
689 */
690 boolean isCanceled();
691 /**
692 * Indicates if the document is in the recalled state or not.
693 * @since 2.1
694 * @see #getStatus()
695 * @return true if in the specified state
696 */
697 boolean isRecalled();
698 /**
699 * Indicates if the document is in the disapproved state or not.
700 * @see #getStatus()
701 * @return true if in the specified state
702 */
703 boolean isDisapproved();
704 /**
705 * Indicates if the document is in the Processed or Finalized state.
706 * @see #getStatus()
707 * @return true if in the specified state
708 */
709 boolean isApproved();
710 /**
711 * Indicates if the document is in the processed state or not.
712 * @see #getStatus()
713 * @return true if in the specified state
714 */
715 boolean isProcessed();
716 /**
717 * Indicates if the document is in the final state or not.
718 * @see #getStatus()
719 * @return true if in the specified state
720 */
721 boolean isFinal();
722
723 /**
724 * Returns the names of the route nodes on the document which are currently active.
725 *
726 * <p>If the document has completed its routing (i.e. it is in processed or final status) then this method may
727 * return an empty set since no nodes are active at that time. In order to get either the active *or* terminal
728 * nodes, use the {@link #getCurrentNodeNames()} method.</p>
729 *
730 * @see #getActiveRouteNodeInstances()
731 * @see org.kuali.rice.kew.api.document.WorkflowDocumentService#getActiveRouteNodeInstances(String)
732 * @return an unmodifiable set containing the names of the active nodes for this document
733 */
734 Set<String> getNodeNames();
735 /**
736 * Returns the names of the nodes at which the document is currently at in it's route path.
737 *
738 * <p>This method differs from {@link #getNodeNames()} in the fact that if there are no active nodes, it will
739 * return the last nodes on the document instead (a.k.a. the document's terminal nodes).</p>
740 *
741 * @see #getCurrentRouteNodeInstances()
742 * @see org.kuali.rice.kew.api.document.WorkflowDocumentService#getCurrentRouteNodeInstances(String)
743 * @return an unmodifiable set containing the names of the nodes at which this document is currently located within it's route path
744 */
745 Set<String> getCurrentNodeNames();
746 /**
747 * Returns the list of active route node instances
748 * @see org.kuali.rice.kew.api.document.WorkflowDocumentService#getActiveRouteNodeInstances(String)
749 * @return the list of active route node instances
750 */
751 List<RouteNodeInstance> getActiveRouteNodeInstances();
752 /**
753 * Returns the list of active route node instances
754 * @see org.kuali.rice.kew.api.document.WorkflowDocumentService#getCurrentRouteNodeInstances(String)
755 * @return the list of active route node instances
756 */
757 List<RouteNodeInstance> getCurrentRouteNodeInstances();
758 /**
759 * Returns the flattened list of route node instances
760 * @see org.kuali.rice.kew.api.document.WorkflowDocumentService#getRouteNodeInstances(String)
761 * @return the flattened list of route node instances
762 */
763 List<RouteNodeInstance> getRouteNodeInstances();
764 /**
765 * Returns the list of previous route node names
766 * @see org.kuali.rice.kew.api.document.WorkflowDocumentService#getPreviousRouteNodeNames(String)
767 * @return the list of previous route node names
768 */
769 List<String> getPreviousNodeNames();
770
771
772 /**
773 * Returns detailed document information
774 * TODO: consolidate with Document/ModifiableDocument or eliminate? currently bypasses
775 * locally cached Document data
776 * @see org.kuali.rice.kew.api.document.WorkflowDocumentService#getDocumentDetail(String)
777 * @return detailed document information
778 */
779 DocumentDetail getDocumentDetail();
780 /**
781 * Sets internal DocumentContentUpdate object
782 * TODO: exposes internal API and used only by tests, candidate for elimination?
783 * @param documentContentUpdate the DocumentContentUpdate to set
784 */
785 void updateDocumentContent(DocumentContentUpdate documentContentUpdate);
786 }