001 /**
002 * Copyright 2005-2014 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.krad.service;
017
018 import org.kuali.rice.kew.api.exception.WorkflowException;
019 import org.kuali.rice.kim.api.identity.Person;
020 import org.kuali.rice.krad.bo.AdHocRouteRecipient;
021 import org.kuali.rice.krad.bo.Note;
022 import org.kuali.rice.krad.document.Document;
023 import org.kuali.rice.krad.exception.ValidationException;
024 import org.kuali.rice.krad.rules.rule.event.KualiDocumentEvent;
025 import org.kuali.rice.krad.rules.rule.event.SaveEvent;
026
027 import java.util.List;
028
029 /**
030 * Defines various operations that support the Document framework.
031 *
032 * The calling code should always use any returned Document object for future operations since a new object will be
033 * created if a passed-in document is saved.
034 *
035 * @author Kuali Rice Team (rice.collab@kuali.org)
036 */
037 public interface DocumentService {
038
039 /**
040 * @param documentHeaderId
041 * @return true if a document with the given documentHeaderId exists
042 */
043 public boolean documentExists(String documentHeaderId);
044
045 /**
046 * get a new blank document instance based on the document type name
047 *
048 * @param documentTypeName
049 * @return new document instance
050 */
051 public Document getNewDocument(String documentTypeName) throws WorkflowException;
052
053 /**
054 * get a new blank document instance having the given Document class
055 *
056 * @param documentClass
057 * @return new document instance
058 */
059 public Document getNewDocument(Class<? extends Document> documentClass) throws WorkflowException;
060
061 /**
062 * get a new blank document instance based on the document type name. The principal name
063 * passed in will be used as the document initiator.
064 *
065 * @param documentTypeName
066 * @param initiatorPrincipalNm
067 * @return new document instance
068 */
069 public Document getNewDocument(String documentTypeName, String initiatorPrincipalNm) throws WorkflowException;
070
071 /**
072 * get a document based on the document header id which is the primary key for all document types
073 *
074 * @param documentHeaderId
075 * @return document, by id
076 */
077 public Document getByDocumentHeaderId(String documentHeaderId) throws WorkflowException;
078 /**
079 * get a document based on the document header id which is the primary key for all document types. Using this
080 * method does not require that GlobalVariables.getUserSession() be populated. Therefore, this method can be used
081 * when a HTTP request is not being processed (e.g. during workflow indexing/post-processing).
082 *
083 * @param documentHeaderId
084 * @return document, by id
085 */
086 public Document getByDocumentHeaderIdSessionless(String documentHeaderId) throws WorkflowException;
087
088 /**
089 * This method retrieves a list of fully-populated documents given a list of document header id values.
090 *
091 * @param documentClass
092 * @param documentHeaderIds
093 * @return list of fully-populated documents
094 * @throws WorkflowException
095 */
096 public List<Document> getDocumentsByListOfDocumentHeaderIds(Class<? extends Document> documentClass, List<String> documentHeaderIds) throws WorkflowException;
097
098 /**
099 * This method is to allow for documents to be updated. It is currently used to update the document status as
100 * well as to allow for locked docs to be unlocked
101 *
102 * @param document the document to be updated
103 * @return the updated document
104 */
105 public Document updateDocument(Document document);
106
107 /**
108 * This is a helper method that performs the same as the {@link #saveDocument(Document, Class)} method. The
109 * convenience of this method is that the event being used is the standard SaveDocumentEvent.
110 *
111 * @see org.kuali.rice.krad.service.DocumentService#saveDocument(Document, Class)
112 */
113 public Document saveDocument(Document document) throws WorkflowException;
114
115 /**
116 * Saves the passed-in document. This will persist it both to the Kuali database, and also initiate it
117 * (if necessary) within workflow, so its available in the initiator's action list. This method uses the
118 * passed in KualiDocumentEvent class when saving the document. The KualiDocumentEvent class must implement
119 * the {@link SaveEvent} interface.
120 *
121 * Note that the system does not support passing in Workflow Annotations or AdHoc Route Recipients on a SaveDocument
122 * call. These are sent to workflow on a routeDocument action, or any of the others which actually causes a
123 * routing action to happen in workflow.
124 *
125 * Also note that this method will not check the document action flags to check if a save is valid
126 *
127 * The calling code should always use the object returned from this method for future operations since a new
128 * object is created when the passed-in document is saved.
129 *
130 * @param document the document to be saved
131 * @param kualiDocumentEventClass the event class to use when saving (class must implement the SaveEvent interface)
132 * @return the saved document
133 * @throws WorkflowException
134 */
135 public Document saveDocument(Document document, Class<? extends KualiDocumentEvent> kualiDocumentEventClass) throws WorkflowException;
136
137 /**
138 * Save and then route the document, optionally providing an annotation which will show up in the route log
139 * of the document for the action taken, and optionally providing a list of ad hoc recipients for the document.
140 *
141 * @param document the document to be routed
142 * @param annotation the annotation to appear in the route log of the document
143 * @param adHocRoutingRecipients list of ad hoc recipients to which the document will be routed
144 * @return the saved and routed document
145 * @throws WorkflowException
146 */
147 public Document routeDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRoutingRecipients) throws WorkflowException;
148
149 /**
150 * Save and then approve the document, optionally providing an annotation which will show up in the route log
151 * of the document for the action taken, and optionally providing a list of ad hoc recipients for the document.
152 *
153 * @param document the document to be approved
154 * @param annotation the annotation to appear in the route log of the document
155 * @param adHocRoutingRecipients list of ad hoc recipients to which the document will be routed
156 * @return the saved and approved document
157 * @throws WorkflowException
158 */
159 public Document approveDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRoutingRecipients) throws WorkflowException;
160
161 /**
162 * Save and then approve the document as a super user, optionally providing an annotation which will show up in the
163 * route log of the document for the action taken.
164 *
165 * @param document the document to be super user approved
166 * @param annotation the annotation to appear in the route log of the document
167 * @return the saved and super user approved document
168 * @throws WorkflowException
169 */
170 public Document superUserApproveDocument(Document document, String annotation) throws WorkflowException;
171
172 /**
173 * Save and then cancel the document as a super user, optionally providing an annotation which will show up in the
174 * route log of the document for the action taken.
175 *
176 * @param document the document to be super user canceled
177 * @param annotation the annotation to appear in the route log of the document
178 * @return the saved and super user canceled document
179 * @throws WorkflowException
180 */
181 public Document superUserCancelDocument(Document document, String annotation) throws WorkflowException;
182
183 /**
184 * Save and then disapprove the document as a super user, optionally providing an annotation which will show up
185 * in the route log of the document for the action taken.
186 *
187 * @param document the document to be super user disapproved
188 * @param annotation the annotation to appear in the route log of the document
189 * @return the saved and super user disapproved document
190 * @throws WorkflowException
191 */
192 public Document superUserDisapproveDocument(Document document, String annotation) throws WorkflowException;
193
194 /**
195 * Disapprove the document as super user, without saving, optionally providing an annotation which will show
196 * up in the route log of the document for the action taken.
197 *
198 * @param document the document to be super user disapproved
199 * @param annotation the annotation to appear in the route log of the document
200 * @return the super user disapproved document
201 * @throws WorkflowException
202 */
203 public Document superUserDisapproveDocumentWithoutSaving(Document document, String annotation) throws WorkflowException;
204
205 /**
206 * Disapprove the document, without saving, optionally providing an annotation which will show up in the route log
207 * of the document for the action taken.
208 *
209 * @param document the document to be disapproved
210 * @param annotation the annotation to appear in the route log of the document
211 * @return the disapproved document
212 * @throws Exception
213 */
214 public Document disapproveDocument(Document document, String annotation) throws Exception;
215
216 /**
217 * Cancel the document, without saving, optionally providing an annotation for the disapproval which will show
218 * up in the route log of the document for the action taken.
219 *
220 * @param document the document to be canceled
221 * @param annotation the annotation to appear in the route log of the document
222 * @return the canceled document
223 * @throws WorkflowException
224 */
225 public Document cancelDocument(Document document, String annotation) throws WorkflowException;
226
227 /**
228 * Acknowledge the document, optionally providing an annotation for the acknowledgement which will show up in the
229 * route log of the document, and optionally providing a list of ad hoc recipients for the document. The list of
230 * ad hoc recipients for this document should have an action requested of acknowledge or fyi as all other actions
231 * requested will be discarded as invalid due to the fact that this action being taken is an acknowledgement.
232 *
233 * @param document the document to be acknowledged
234 * @param annotation the annotation to appear in the route log of the document
235 * @param adHocRecipients list of ad hoc recipients to which the document will be routed
236 * @return the acknowledged document
237 * @throws WorkflowException
238 */
239 public Document acknowledgeDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
240
241 /**
242 * Blanket approve the document which will save the document, approve the document, and stand in for an
243 * approve for all typically generated approval actions requested for this document. The user must have blanket
244 * approval authority for this document by being registered as a user in the blanket approval workgroup that is
245 * associated with this document type. Optionally an annotation can be provided which will show up for the
246 * action taken on the document in the route log. Also optionally a list of ad hoc recipients can be provided
247 * for the document, which should be restricted to actions requested of acknowledge and fyi as all other actions
248 * requested will be discarded.
249 *
250 * @param document the document to be blanket approved
251 * @param annotation the annotation to appear in the route log of the document
252 * @param adHocRecipients list of ad hoc recipients to which the document will be routed
253 * @return the saved and blanket approved document
254 * @throws WorkflowException
255 */
256 public Document blanketApproveDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
257
258 /**
259 * Clear the fyi requests for the document, optionally providing a list of ad hoc recipients for the document,
260 * which should be restricted to action requested of fyi as all other actions requested will be discarded.
261 *
262 * @param document the document to clear of fyi requests
263 * @param adHocRecipients list of ad hoc recipients to which the document will be routed
264 * @return the document
265 * @throws WorkflowException
266 */
267 public Document clearDocumentFyi(Document document, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
268
269 /**
270 * Sets the title and app document id in the workflow document
271 *
272 * @param document the document to prepare
273 * @throws WorkflowException
274 */
275 public void prepareWorkflowDocument(Document document) throws WorkflowException;
276
277 /**
278 * This method creates a note from the given document and note text. The resulting Note will
279 * have it's note type set to the value of {@link Document#getNoteType()}. Additionally, it's
280 * remoteObjectId will be set to the object id of the document's note target.
281 *
282 * @param document the document from which to use the note type and note target when creating the note
283 * @param text the text value to include in the resulting note
284 * @return the note that was created
285 */
286 public Note createNoteFromDocument(Document document, String text);
287
288 /**
289 * Saves the notes associated with the given document if they are in a state where they can be
290 * saved. In certain cases they may not be ready to be saved. For example, in maintenance documents
291 * where the notes are associated with the business object instead of the document header, the notes
292 * cannot be saved until the business object itself has been persisted.
293 *
294 * @param document the document for which to save notes
295 * @return true if the notes were saved, false if they were not
296 */
297 public boolean saveDocumentNotes(Document document);
298
299 /**
300 * Send ad hoc requests for the given document, optionally providing an annotation which will show up in the route
301 * log of the document. Also optionally providing a list of ad hoc recipients for the document. However if
302 * no ad hoc recipients are provided, no ad hoc requests will be sent.
303 *
304 * @param document the document for which the ad hoc requests are sent
305 * @param annotation the annotation to appear in the route log of the document
306 * @param adHocRecipients list of ad hoc recipients to which the document will be routed
307 * @return the document
308 * @throws WorkflowException
309 */
310 public Document sendAdHocRequests(Document document, String annotation, List<AdHocRouteRecipient> adHocRecipients) throws WorkflowException;
311
312 /**
313 * Builds an workflow notification request for the note and sends it to note recipient.
314 *
315 * @param document - document that contains the note
316 * @param note - note to notify
317 * @param sender - user who is sending the notification
318 * @return the document
319 * @throws WorkflowException
320 */
321 public Document sendNoteRouteNotification(Document document, Note note, Person sender) throws WorkflowException;
322
323 /**
324 * Recall the document, optionally providing an annotation for the recall which will show up in the route
325 * log of the document for the action taken.
326 *
327 * @since 2.1
328 * @param document the document to recall
329 * @param annotation the annotation to appear in the route log of the document
330 * @param cancel indicates if the document should be canceled as part of the recall
331 * @return the recalled document
332 * @throws WorkflowException
333 */
334 public Document recallDocument(Document document, String annotation, boolean cancel) throws WorkflowException;
335
336 /**
337 * Save and then complete the document, optionally providing an annotation which will show up in the route log
338 * of the document for the action taken, and optionally providing a list of ad hoc recipients for the document
339 *
340 * @param document the document to complete
341 * @param annotation the annotation to appear in the route log of the document
342 * @param adHocRecipients list of ad hoc recipients to which the document will be routed
343 * @return the saved and completed document
344 */
345 public Document completeDocument(Document document, String annotation, List adHocRecipients) throws WorkflowException;
346
347 /**
348 * Helper method used to save and validate a document
349 *
350 * @param document document to be validated and persisted
351 * @param event indicates which kualiDocumentEvent was requested
352 * @return the saved document
353 */
354 public Document validateAndPersistDocument(Document document, KualiDocumentEvent event) throws ValidationException;
355 }