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