001: /*
002: * Copyright 2005-2007 The Kuali Foundation.
003: *
004: * Licensed under the Educational Community License, Version 1.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/ecl1.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.core.service;
017:
018: import java.util.Collection;
019: import java.util.Date;
020: import java.util.List;
021:
022: import org.kuali.core.bo.Note;
023: import org.kuali.core.bo.PersistableBusinessObject;
024: import org.kuali.core.document.Document;
025: import org.kuali.core.rule.event.SaveEvent;
026:
027: import edu.iu.uis.eden.exception.EdenUserNotFoundException;
028: import edu.iu.uis.eden.exception.WorkflowException;
029:
030: /**
031: * This is the DocumentService interface which must have an implementation that accompanies it. This interfaces defines all of the
032: * generally required methods for all document instances
033: *
034: *
035: */
036:
037: // TODO put exceptions that are kuali based into here instead of implementation based
038: public interface DocumentService {
039:
040: /**
041: * @param documentHeaderId
042: * @return true if a document with the given documentHeaderId exists
043: */
044: public boolean documentExists(String documentHeaderId);
045:
046: /**
047: * get a new blank document instance based on the document type name
048: *
049: * @param documentTypeName
050: * @return
051: * @throws EdenUserNotFoundException
052: * @throws EdenException
053: */
054: public Document getNewDocument(String documentTypeName)
055: throws WorkflowException;
056:
057: /**
058: * get a new blank document instance having the given Document class
059: *
060: * @param documentClass
061: * @return
062: * @throws EdenUserNotFoundException
063: * @throws EdenException
064: */
065: public Document getNewDocument(Class documentClass)
066: 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: * @throws EdenUserNotFoundException
074: * @throws EdenException
075: */
076: public Document getByDocumentHeaderId(String documentHeaderId)
077: throws WorkflowException;
078:
079: /**
080: * Retrieves a collection of documents with type of given Class, and with the passed status code.
081: *
082: * @param clazz
083: * @param statusCode
084: * @return
085: */
086: public Collection findByDocumentHeaderStatusCode(Class clazz,
087: String statusCode) throws WorkflowException;
088:
089: /**
090: * This method retrieves a list of fully-populated documents given a list of document header id values.
091: *
092: * @param clazz
093: * @param documentHeaderIds
094: * @return List of fully-populated documents
095: * @throws WorkflowException
096: */
097: public List getDocumentsByListOfDocumentHeaderIds(Class clazz,
098: List documentHeaderIds) throws WorkflowException;
099:
100: /**
101: * Retrieves a collection of DocumentHeaders by the date that they were finalized.
102: *
103: * @param documentFinalDate
104: * @return Collection of DocumentHeaders
105: * @throws WorkflowException
106: */
107: public Collection getFinalDocumentHeadersByDate(
108: Date documentFinalDate) throws WorkflowException;
109:
110: /**
111: *
112: * This method is to allow for documents to be updated which is currently used to update the document status as well as to allow
113: * for locked docs to be unlocked
114: *
115: * @param document
116: */
117: public void updateDocument(Document document);
118:
119: /**
120: * Calls validation methods to validate against the dictionary and run through the rules engine. If validation succeeds, the
121: * document is persisted and control returns back to the route action.
122: *
123: * @param document
124: * @param event
125: * @throws WorkflowException
126: * @throws ValidationException
127: */
128: // public void validateAndPersistDocument(Document document, KualiDocumentEvent event) throws WorkflowException, ValidationException;
129: /**
130: * This is a helper method that performs the same as the {@link #saveDocument(Document, Class)} method. The convenience
131: * of this method is that the event being used is the standard SaveDocumentEvent.
132: *
133: * @see org.kuali.core.service.DocumentService#saveDocument(Document, Class)
134: */
135: public Document saveDocument(Document document)
136: throws WorkflowException;
137:
138: /**
139: * Saves the passed-in document. This will persist it both to the Kuali database, and also initiate it (if necessary) within
140: * workflow, so its available in the initiator's action list. This method uses the passed in KualiDocumentEvent class when saving
141: * the document. The KualiDocumentEvent class must implement the {@link SaveEvent} interface.
142: *
143: * Note that the system does not support passing in Workflow Annotations or AdHoc Route Recipients on a SaveDocument call. These
144: * are sent to workflow on a routeDocument action, or any of the others which actually causes a routing action to happen in
145: * workflow.
146: *
147: * NOTE: This method will not check the document action flags to check if a save is valid
148: *
149: * @param document The document to be saved
150: * @param kualiDocumentEventClass The event class to use when saving (class must implement the SaveEvent interface)
151: * @return the document that was passed in
152: * @throws WorkflowException
153: */
154: public Document saveDocument(Document document,
155: Class kualiDocumentEventClass) throws WorkflowException;
156:
157: /**
158: * start the route the document for approval, optionally providing a list of ad hoc recipients, and additionally provideing a
159: * annotation to show up in the route log for the document
160: *
161: * @param document
162: * @param annotation
163: * @param adHocRoutingRecipients
164: * @return
165: * @throws EdenException
166: * @throws ValidationErrorList
167: */
168: public Document routeDocument(Document document, String annotation,
169: List adHocRoutingRecipients) throws WorkflowException;
170:
171: /**
172: * approve this document, optionally providing an annotation which will show up in the route log for this document for this
173: * action taken, and optionally providing a list of ad hoc recipients for the document
174: *
175: * @param document
176: * @param annotation
177: * @param adHocRoutingRecipients
178: * @return
179: * @throws EdenException
180: * @throws ValidationErrorList
181: */
182: public Document approveDocument(Document document,
183: String annotation, List adHocRoutingRecipients)
184: throws WorkflowException;
185:
186: /**
187: * approve this document as super user, optionally providing an annotation which will show up in the route log for this document
188: * for this action taken
189: *
190: * @param document
191: * @param annotation
192: * @return
193: * @throws EdenException
194: * @throws ValidationErrorList
195: */
196: public Document super UserApproveDocument(Document document,
197: String annotation) throws WorkflowException;
198:
199: /**
200: * cancel this document as super user, optionally providing an annotation which will show up in the route log for this document
201: * for this action taken
202: *
203: * @param document
204: * @param annotation
205: * @return
206: * @throws WorkflowException
207: */
208: public Document super UserCancelDocument(Document document,
209: String annotation) throws WorkflowException;
210:
211: /**
212: * disapprove this document as super user, optionally providing an annotation which will show up in the route log for this document
213: * for this action taken
214: *
215: * @param document
216: * @param annotation
217: * @return
218: * @throws WorkflowException
219: */
220: public Document super UserDisapproveDocument(Document document,
221: String annotation) throws WorkflowException;
222:
223: /**
224: * disapprove this document, optionally providing an annotation for the disapproval which will show up in the route log for the
225: * document for this action taken
226: *
227: * @param document
228: * @param annotation
229: * @return Document
230: * @throws Exception
231: */
232: public Document disapproveDocument(Document document,
233: String annotation) throws Exception;
234:
235: /**
236: * cancel this document, optionally providing an annotation for the disapproval which will show up in the route log for the
237: * document for this action taken
238: *
239: * @param document
240: * @param annotation
241: * @return
242: * @throws EdenException
243: */
244: public Document cancelDocument(Document document, String annotation)
245: throws WorkflowException;
246:
247: /**
248: * acknowledge this document, optionally providing an annotation for the acknowledgement which will show up in the route log for
249: * the document for this acknowledgement, additionally optionally provide a list of ad hoc recipients that should recieve this
250: * document. The list of ad hoc recipients for this document should have an action requested of acknowledge or fyi as all other
251: * actions requested will be discarded as invalid based on the action being taken being an acknowledgement.
252: *
253: * @param document
254: * @param annotation
255: * @param adHocRecipients
256: * @return
257: * @throws EdenException
258: */
259: public Document acknowledgeDocument(Document document,
260: String annotation, List adHocRecipients)
261: throws WorkflowException;
262:
263: /**
264: * blanket approve this document which will approve the document and stand in for an approve for all typically generated
265: * approval actions requested for this document. The user must have blanket approval authority for this document by being
266: * registered as a user in the blanket approval workgroup that is associated with this document type. Optionally an annotation
267: * can be provided which will show up for this action taken on the document in the route log. Additionally optionally provide a
268: * list of ad hoc recipients for this document, which should be restricted to actions requested of acknowledge and fyi as all
269: * other actions requested will be discarded
270: *
271: * @param document
272: * @param annotation
273: * @param adHocRecipients
274: * @return
275: * @throws EdenException
276: * @throws ValidationErrorList
277: */
278: public Document blanketApproveDocument(Document document,
279: String annotation, List adHocRecipients)
280: throws WorkflowException;
281:
282: /**
283: * clear the fyi request for this document, optionally providing a list of ad hoc recipients for this document, which should be
284: * restricted to action requested of fyi as all other actions requested will be discarded
285: *
286: * @param document
287: * @param adHocRecipients
288: * @return
289: * @throws EdenException
290: */
291: public Document clearDocumentFyi(Document document,
292: List adHocRecipients) throws WorkflowException;
293:
294: /**
295: * Sets the title and app document id in the flex document
296: *
297: * @param document
298: * @throws WorkflowException
299: */
300: public void prepareWorkflowDocument(Document document)
301: throws WorkflowException;
302:
303: /**
304: *
305: * This method creates a note from a given document and note text
306: * @param document
307: * @param text
308: * @return
309: * @throws Exception
310: */
311: public Note createNoteFromDocument(Document document, String text)
312: throws Exception;
313:
314: /**
315: *
316: * This method adds a note to a document
317: * @param document
318: * @param note
319: * @return the added Note
320: */
321: public boolean addNoteToDocument(Document document, Note note);
322:
323: /**
324: *
325: * This method gets the parent for a note from a document
326: * @param document
327: * @param newNote
328: * @return Business Object that the note is attached to.
329: */
330: public PersistableBusinessObject getNoteParent(Document document,
331: Note newNote);
332: }
|