1 /**
2 * Copyright 2005-2011 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.krad.service;
17
18 import org.kuali.rice.kew.api.exception.WorkflowException;
19 import org.kuali.rice.kim.api.identity.Person;
20 import org.kuali.rice.krad.bo.AdHocRouteRecipient;
21 import org.kuali.rice.krad.bo.Note;
22 import org.kuali.rice.krad.document.Document;
23 import org.kuali.rice.krad.rule.event.KualiDocumentEvent;
24 import org.kuali.rice.krad.rule.event.SaveEvent;
25
26 import java.util.List;
27
28 /**
29 * Defines various operations that support the Document framework.
30 *
31 * @author Kuali Rice Team (rice.collab@kuali.org)
32 */
33 public interface DocumentService {
34
35 /**
36 * @param documentHeaderId
37 * @return true if a document with the given documentHeaderId exists
38 */
39 public boolean documentExists(String documentHeaderId);
40
41 /**
42 * get a new blank document instance based on the document type name
43 *
44 * @param documentTypeName
45 * @return
46 */
47 public Document getNewDocument(String documentTypeName) throws WorkflowException;
48
49 /**
50 * get a new blank document instance having the given Document class
51 *
52 * @param documentClass
53 * @return
54 */
55 public Document getNewDocument(Class<? extends Document> documentClass) throws WorkflowException;
56
57 /**
58 * get a document based on the document header id which is the primary key for all document types
59 *
60 * @param documentHeaderId
61 * @return
62 */
63 public Document getByDocumentHeaderId(String documentHeaderId) throws WorkflowException;
64 /**
65 * get a document based on the document header id which is the primary key for all document types. Using this method
66 * does not require that GlobalVariables.getUserSession() be populated. Therefore, this method can be used when a HTTP request
67 * is not being processed (e.g. during workflow indexing/post-processing).
68 *
69 * @param documentHeaderId
70 * @return
71 */
72 public Document getByDocumentHeaderIdSessionless(String documentHeaderId) throws WorkflowException;
73
74 /**
75 * This method retrieves a list of fully-populated documents given a list of document header id values.
76 *
77 * @param clazz
78 * @param documentHeaderIds
79 * @return List of fully-populated documents
80 * @throws WorkflowException
81 */
82 public List<Document> getDocumentsByListOfDocumentHeaderIds(Class<? extends Document> documentClass, List<String> documentHeaderIds) throws WorkflowException;
83
84 /**
85 *
86 * This method is to allow for documents to be updated which is currently used to update the document status as well as to allow
87 * for locked docs to be unlocked
88 *
89 * @param document
90 */
91 public Document updateDocument(Document document);
92
93 /**
94 * This is a helper method that performs the same as the {@link #saveDocument(Document, Class)} method. The convenience
95 * of this method is that the event being used is the standard SaveDocumentEvent.
96 *
97 * @see org.kuali.rice.krad.service.DocumentService#saveDocument(Document, Class)
98 */
99 public Document saveDocument(Document document) throws WorkflowException;
100
101 /**
102 * Saves the passed-in document. This will persist it both to the Kuali database, and also initiate it (if necessary) within
103 * workflow, so its available in the initiator's action list. This method uses the passed in KualiDocumentEvent class when saving
104 * the document. The KualiDocumentEvent class must implement the {@link SaveEvent} interface.
105 *
106 * Note that the system does not support passing in Workflow Annotations or AdHoc Route Recipients on a SaveDocument call. These
107 * are sent to workflow on a routeDocument action, or any of the others which actually causes a routing action to happen in
108 * workflow.
109 *
110 * NOTE: This method will not check the document action flags to check if a save is valid
111 *
112 * @param document The document to be saved
113 * @param kualiDocumentEventClass The event class to use when saving (class must implement the SaveEvent interface)
114 * @return the document that was passed in
115 * @throws WorkflowException
116 */
117 public Document saveDocument(Document document, Class<? extends KualiDocumentEvent> kualiDocumentEventClass) throws WorkflowException;
118
119 /**
120 * start the route the document for approval, optionally providing a list of ad hoc recipients, and additionally provideing a
121 * annotation to show up in the route log for the document
122 *
123 * @param document
124 * @param annotation
125 * @param adHocRoutingRecipients
126 * @return
127 * @throws ValidationErrorList
128 */
129 public Document routeDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRoutingRecipients) throws WorkflowException;
130
131 /**
132 * approve this document, optionally providing an annotation which will show up in the route log for this document for this
133 * action taken, and optionally providing a list of ad hoc recipients for the document
134 *
135 * @param document
136 * @param annotation
137 * @param adHocRoutingRecipients
138 * @return
139 * @throws ValidationErrorList
140 */
141 public Document approveDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRoutingRecipients) throws WorkflowException;
142
143 /**
144 * approve this document as super user, optionally providing an annotation which will show up in the route log for this document
145 * for this action taken
146 *
147 * @param document
148 * @param annotation
149 * @return
150 * @throws ValidationErrorList
151 */
152 public Document superUserApproveDocument(Document document, String annotation) throws WorkflowException;
153
154 /**
155 * cancel this document as super user, optionally providing an annotation which will show up in the route log for this document
156 * for this action taken
157 *
158 * @param document
159 * @param annotation
160 * @return
161 * @throws WorkflowException
162 */
163 public Document superUserCancelDocument(Document document, String annotation) throws WorkflowException;
164
165 /**
166 * disapprove this document as super user, optionally providing an annotation which will show up in the route log for this document
167 * for this action taken
168 *
169 * @param document
170 * @param annotation
171 * @return
172 * @throws WorkflowException
173 */
174 public Document superUserDisapproveDocument(Document document, String annotation) throws WorkflowException;
175
176 /**
177 * disapprove this document, optionally providing an annotation for the disapproval which will show up in the route log for the
178 * document for this action taken
179 *
180 * @param document
181 * @param annotation
182 * @return Document
183 * @throws Exception
184 */
185 public Document disapproveDocument(Document document, String annotation) throws Exception;
186
187 /**
188 * cancel this document, optionally providing an annotation for the disapproval which will show up in the route log for the
189 * document for this action taken
190 *
191 * @param document
192 * @param annotation
193 * @return
194 */
195 public Document cancelDocument(Document document, String annotation) throws WorkflowException;
196
197 /**
198 * acknowledge this document, optionally providing an annotation for the acknowledgement which will show up in the route log for
199 * the document for this acknowledgement, additionally optionally provide a list of ad hoc recipients that should recieve this
200 * document. The list of ad hoc recipients for this document should have an action requested of acknowledge or fyi as all other
201 * actions requested will be discarded as invalid based on the action being taken being an acknowledgement.
202 *
203 * @param document
204 * @param annotation
205 * @param adHocRecipients
206 * @return
207 */
208 public Document acknowledgeDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
209
210 /**
211 * blanket approve this document which will approve the document and stand in for an approve for all typically generated
212 * approval actions requested for this document. The user must have blanket approval authority for this document by being
213 * registered as a user in the blanket approval workgroup that is associated with this document type. Optionally an annotation
214 * can be provided which will show up for this action taken on the document in the route log. Additionally optionally provide a
215 * list of ad hoc recipients for this document, which should be restricted to actions requested of acknowledge and fyi as all
216 * other actions requested will be discarded
217 *
218 * @param document
219 * @param annotation
220 * @param adHocRecipients
221 * @return
222 * @throws ValidationErrorList
223 */
224 public Document blanketApproveDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
225
226 /**
227 * clear the fyi request for this document, optionally providing a list of ad hoc recipients for this document, which should be
228 * restricted to action requested of fyi as all other actions requested will be discarded
229 *
230 * @param document
231 * @param adHocRecipients
232 * @return
233 */
234 public Document clearDocumentFyi(Document document, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
235
236 /**
237 * Sets the title and app document id in the workflow document
238 *
239 * @param document
240 * @throws WorkflowException
241 */
242 public void prepareWorkflowDocument(Document document) throws WorkflowException;
243
244
245 /**
246 * This method creates a note from a given document and note text. The resulting Note will
247 * have it's note type set to the value of {@link Document#getNoteType()}. Additionally, it's
248 * remoteObjectId will be set to the object id of the document's note target.
249 *
250 * @param document the document from which to use the note type and note target when creating the note
251 * @param text the text value to include in the resulting note
252 * @return the note that was created
253 */
254 public Note createNoteFromDocument(Document document, String text);
255
256 /**
257 * Saves the notes associated with the given document if they are in a state where they can be
258 * saved. In certain cases they may not be ready to be saved. For example, in maintenance documents
259 * where the notes are associated with the business object instead of the document header, the notes
260 * cannot be saved until the business object itself has been persisted.
261 *
262 * @param document the document for which to save notes
263 * @return true if the notes were saved, false if they were not
264 */
265 public boolean saveDocumentNotes(Document document);
266
267 public void sendAdHocRequests(Document document, String annotation, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
268
269 /**
270 * Builds an workflow notification request for the note and sends it to note recipient.
271 *
272 * @param document - document that contains the note
273 * @param note - note to notify
274 * @param sender - user who is sending the notification
275 * @throws WorkflowException
276 */
277 public void sendNoteRouteNotification(Document document, Note note, Person sender) throws WorkflowException;
278 }