View Javadoc
1   /**
2    * Copyright 2005-2016 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;
17  
18  import java.util.List;
19  import java.util.Set;
20  
21  import org.kuali.rice.core.api.uif.RemotableAttributeErrorContract;
22  import org.kuali.rice.kew.api.action.ActionRequest;
23  import org.kuali.rice.kew.api.action.ActionRequestType;
24  import org.kuali.rice.kew.api.action.ActionTaken;
25  import org.kuali.rice.kew.api.action.ActionType;
26  import org.kuali.rice.kew.api.action.AdHocRevoke;
27  import org.kuali.rice.kew.api.action.AdHocToGroup;
28  import org.kuali.rice.kew.api.action.AdHocToPrincipal;
29  import org.kuali.rice.kew.api.action.MovePoint;
30  import org.kuali.rice.kew.api.action.RequestedActions;
31  import org.kuali.rice.kew.api.action.ReturnPoint;
32  import org.kuali.rice.kew.api.action.ValidActions;
33  import org.kuali.rice.kew.api.document.Document;
34  import org.kuali.rice.kew.api.document.DocumentContent;
35  import org.kuali.rice.kew.api.document.DocumentContentUpdate;
36  import org.kuali.rice.kew.api.document.DocumentContract;
37  import org.kuali.rice.kew.api.document.DocumentDetail;
38  import org.kuali.rice.kew.api.document.DocumentStatus;
39  import org.kuali.rice.kew.api.document.attribute.WorkflowAttributeDefinition;
40  import org.kuali.rice.kew.api.document.node.RouteNodeInstance;
41  
42  /**
43   * WorkflowDocument is the core client API for interaction with the Kuali Enterprise Workflow system.
44   * WorkflowDocument is an object-oriented facade/bridge to stateless KEW APIs, which maintains document
45   * state, and flushes updates as actions are taken.
46   *
47   * WorkflowDocuments cannot be constructed directly, create them via the {@link WorkflowDocumentFactory}
48   *
49   * <p><b>This class is *not* thread safe.</b> If you are operating on the same document, be sure to synchronize
50   * access to the {@link WorkflowDocument} instance.  If you are operating on different documents, obtain a distinct
51   * instance from the {@link WorkflowDocumentFactory}.</p>
52   */
53  public interface WorkflowDocument extends DocumentContract {
54      /**
55       * Returns the principalId with which this WorkflowDocument was constructed
56       * @return the principalId with which this WorkflowDocument was constructed
57       */
58      String getPrincipalId();
59      /**
60       * Switches the principalId under which WorkflowDocument API are performed.
61       * This method necessitates clearing of any state associated with the principalId
62       * such as requested and valid actions.
63       * @param principalId the new principalId
64       */
65      void switchPrincipal(String principalId);
66  
67      /**
68       * Returns a read-only view of the underlying document meta-data
69       * @return a read-only view of the underlying document meta-data
70       */
71      Document getDocument();
72  
73      /**
74       * Returns a read-only view of the underlying mutable document content
75       * @return a read-only view of the underlying mutable document content
76       */
77      DocumentContent getDocumentContent();
78  
79      /**
80       * Returns the currently set application content.
81       * @return the currently set application content.
82       * @see #getDocumentContent()
83       */
84      String getApplicationContent();
85  
86      /**
87       * Sets the document title. The update will be committed with the next document operation.
88       * @param title the document title to set
89       */
90      void setTitle(String title);
91  
92      /**
93       * Sets the application document id. The update will be committed with the next document operation.
94       * @param applicationDocumentId the application document id to set.
95       */
96      void setApplicationDocumentId(String applicationDocumentId);
97  
98      /**
99       * 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 }