1 /*
2 * Copyright 2005-2007 The Kuali Foundation
3 *
4 *
5 * Licensed under the Educational Community License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.opensource.org/licenses/ecl2.php
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.kuali.rice.kew.postprocessor;
18
19 import java.rmi.RemoteException;
20
21 import org.kuali.rice.kew.dto.ActionTakenEventDTO;
22 import org.kuali.rice.kew.dto.AfterProcessEventDTO;
23 import org.kuali.rice.kew.dto.BeforeProcessEventDTO;
24 import org.kuali.rice.kew.dto.DeleteEventDTO;
25 import org.kuali.rice.kew.dto.DocumentLockingEventDTO;
26 import org.kuali.rice.kew.dto.DocumentRouteLevelChangeDTO;
27 import org.kuali.rice.kew.dto.DocumentRouteStatusChangeDTO;
28 import org.kuali.rice.kew.exception.ResourceUnavailableException;
29
30
31
32 /**
33 * A PostProcessor listens for events from the Workflow routing engine for it's DocumentType.
34 * It gives clients hooks into the routing process to perform operations at the various stages.
35 * Implementations of this Interface are potentially remotable, so this Interface uses
36 * value objects.
37 *
38 * @author Kuali Rice Team (rice.collab@kuali.org)
39 */
40 public interface PostProcessorRemote {
41
42 /**
43 * The document has changed route status. The docEvent contains the information about the change.
44 * This method should do what ever is appropriate for various route status changes to a document.
45 * The method should return true if the change is correct and all application actions as a result
46 * of the change are successful. It should return false if the application considers this an
47 * incorrect change.
48 *
49 * The method can throw a ResourceUnavailableException in order to requeue the
50 * document and try again later.
51 * @param statusChangeEvent
52 * @param msg any error message to be propagated back to users should be set here
53 * @return true if the status change is correct and application actions are successful
54 * later if this exception is thrown
55 * @see DocumentRouteStatusChange
56 */
57 public boolean doRouteStatusChange(DocumentRouteStatusChangeDTO statusChangeEvent) throws RemoteException;
58
59 /**
60 * The document has changed route level. The docEvent contains the information about the change.
61 * This method should do what ever is appropriate for various route level changes to a document.
62 * The method should return true if the change is correct and all application actions as a result
63 * of the change are successful. It should return false if the application considers this an
64 * incorrect change.
65 *
66 * The method can throw a ResourceUnavailableException in order to requeue the
67 * document and try again later.
68 * @param levelChangeEvent
69 * @param msg any error message to be propagated back to users should be set here
70 * @return true if the status change is correct and application actions are successful
71 * @throws java.lang.Exception A general Exception will put the document into Exception routing
72 * @throws ResourceUnavailableException requeue the document and try the change again
73 * later if this exception is thrown
74 * @see DocumentRouteLevelChangeDTO
75 */
76 public boolean doRouteLevelChange(DocumentRouteLevelChangeDTO levelChangeEvent) throws RemoteException;
77
78 /**
79 * KEW is signaling that the document should be deleted. The application can reject this by
80 * returning false. If an Exception is thrown the docuemnt will go to exception routing. If
81 * a ResourceUnavailableException is thrown, the doc will be requeued and will try again later to
82 * delete the document.
83 * @param event
84 * @param message
85 * @return
86 * @throws java.lang.Exception A general Exception will put the document into Exception routing
87 * @throws ResourceUnavailableException requeue the document and try the change again
88 */
89 public boolean doDeleteRouteHeader(DeleteEventDTO event) throws RemoteException;
90
91 /**
92 * KEW is signaling that the document has had an action taken on it by a user
93 *
94 * @param event
95 * @return
96 * @throws RemoteException
97 */
98 public boolean doActionTaken(ActionTakenEventDTO event) throws RemoteException;
99
100 /**
101 * The document is about to be processed by the Workflow engine.
102 *
103 * @param event - holder for data from the engine's process
104 * @return true if the method is successful, false otherwise
105 * @throws java.lang.Exception A general Exception will put the document into Exception routing
106 */
107 public boolean beforeProcess(BeforeProcessEventDTO event) throws Exception;
108
109 /**
110 * The document has just completed processing by the Workflow engine.
111 *
112 * @param event - holder for data from the engine's process including whether the engine was successful or not
113 * @return true if the method is successful, false otherwise
114 * @throws java.lang.Exception A general Exception will put the document into Exception routing
115 */
116 public boolean afterProcess(AfterProcessEventDTO event) throws Exception;
117
118 /**
119 * Executed prior to document locking in the workflow engine. This method returns an array of document
120 * ids to lock prior to execution of the document in the workflow engine. If the engine processing is
121 * going to result in updates to any other documents, they should be locked at the beginning of the engine
122 * processing transaction. This method facilitates that.
123 *
124 * <p>Note that, by default, the id of the document that is being processed by the engine is always
125 * locked. So there is no need to return that document id in the array of document ids to lock.
126 *
127 * @return an array of document ids to lock prior to execution of the workflow engine
128 */
129 public Long[] getDocumentIdsToLock(DocumentLockingEventDTO event) throws Exception;
130
131 }