org.kuali.rice.krad.service
Interface DocumentService

All Known Implementing Classes:

DocumentServiceImpl

public interface DocumentService

Defines various operations that support the Document framework. The calling code should always use any returned Document object for future operations since a new object will be created if a passed-in document is saved.

Author:

Kuali Rice Team (rice.collab@kuali.org)

Method Summary

Document	acknowledgeDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRecipients) Acknowledge the document, optionally providing an annotation for the acknowledgement which will show up in the route log of the document, and optionally providing a list of ad hoc recipients for the document.
Document	approveDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRoutingRecipients) Save and then approve the document, optionally providing an annotation which will show up in the route log of the document for the action taken, and optionally providing a list of ad hoc recipients for the document.
Document	blanketApproveDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRecipients) Blanket approve the document which will save the document, approve the document, and stand in for an approve for all typically generated approval actions requested for this document.
Document	cancelDocument(Document document, String annotation) Cancel the document, without saving, optionally providing an annotation for the disapproval which will show up in the route log of the document for the action taken.
Document	clearDocumentFyi(Document document, List<AdHocRouteRecipient> adHocRecipients) Clear the fyi requests for the document, optionally providing a list of ad hoc recipients for the document, which should be restricted to action requested of fyi as all other actions requested will be discarded.
Document	completeDocument(Document document, String annotation, List adHocRecipients) Save and then complete the document, optionally providing an annotation which will show up in the route log of the document for the action taken, and optionally providing a list of ad hoc recipients for the document
Note	createNoteFromDocument(Document document, String text) This method creates a note from the given document and note text.
Document	disapproveDocument(Document document, String annotation) Disapprove the document, without saving, optionally providing an annotation which will show up in the route log of the document for the action taken.
boolean	documentExists(String documentHeaderId)
Document	getByDocumentHeaderId(String documentHeaderId) get a document based on the document header id which is the primary key for all document types
Document	getByDocumentHeaderIdSessionless(String documentHeaderId) get a document based on the document header id which is the primary key for all document types.
List<Document>	getDocumentsByListOfDocumentHeaderIds(Class<? extends Document> documentClass, List<String> documentHeaderIds) This method retrieves a list of fully-populated documents given a list of document header id values.
Document	getNewDocument(Class<? extends Document> documentClass) get a new blank document instance having the given Document class
Document	getNewDocument(String documentTypeName) get a new blank document instance based on the document type name
Document	getNewDocument(String documentTypeName, String initiatorPrincipalNm) get a new blank document instance based on the document type name.
void	prepareWorkflowDocument(Document document) Sets the title and app document id in the workflow document
Document	recallDocument(Document document, String annotation, boolean cancel) Recall the document, optionally providing an annotation for the recall which will show up in the route log of the document for the action taken.
Document	routeDocument(Document document, String annotation, List<AdHocRouteRecipient> adHocRoutingRecipients) Save and then route the document, optionally providing an annotation which will show up in the route log of the document for the action taken, and optionally providing a list of ad hoc recipients for the document.
Document	saveDocument(Document document) This is a helper method that performs the same as the saveDocument(Document, Class) method.
Document	saveDocument(Document document, Class<? extends KualiDocumentEvent> kualiDocumentEventClass) Saves the passed-in document.
boolean	saveDocumentNotes(Document document) Saves the notes associated with the given document if they are in a state where they can be saved.
Document	sendAdHocRequests(Document document, String annotation, List<AdHocRouteRecipient> adHocRecipients) Send ad hoc requests for the given document, optionally providing an annotation which will show up in the route log of the document.
Document	sendNoteRouteNotification(Document document, Note note, Person sender) Builds an workflow notification request for the note and sends it to note recipient.
Document	superUserApproveDocument(Document document, String annotation) Save and then approve the document as a super user, optionally providing an annotation which will show up in the route log of the document for the action taken.
Document	superUserCancelDocument(Document document, String annotation) Save and then cancel the document as a super user, optionally providing an annotation which will show up in the route log of the document for the action taken.
Document	superUserDisapproveDocument(Document document, String annotation) Save and then disapprove the document as a super user, optionally providing an annotation which will show up in the route log of the document for the action taken.
Document	superUserDisapproveDocumentWithoutSaving(Document document, String annotation) Disapprove the document as super user, without saving, optionally providing an annotation which will show up in the route log of the document for the action taken.
Document	updateDocument(Document document) This method is to allow for documents to be updated.
Document	validateAndPersistDocument(Document document, KualiDocumentEvent event) Helper method used to save and validate a document

Method Detail

documentExists

boolean documentExists(String documentHeaderId)

Parameters:

documentHeaderId -

Returns:

true if a document with the given documentHeaderId exists

getNewDocument

Document getNewDocument(String documentTypeName)
                        throws WorkflowException

get a new blank document instance based on the document type name

Parameters:

documentTypeName -

Returns:

new document instance

Throws:

WorkflowException

getNewDocument

Document getNewDocument(Class<? extends Document> documentClass)
                        throws WorkflowException

get a new blank document instance having the given Document class

Parameters:

documentClass -

Returns:

new document instance

Throws:

WorkflowException

getNewDocument

Document getNewDocument(String documentTypeName,
                        String initiatorPrincipalNm)
                        throws WorkflowException

get a new blank document instance based on the document type name. The principal name passed in will be used as the document initiator.

Parameters:

documentTypeName -

initiatorPrincipalNm -

Returns:

new document instance

Throws:

WorkflowException

getByDocumentHeaderId

Document getByDocumentHeaderId(String documentHeaderId)
                               throws WorkflowException

get a document based on the document header id which is the primary key for all document types

Parameters:

documentHeaderId -

Returns:

document, by id

Throws:

WorkflowException

getByDocumentHeaderIdSessionless

Document getByDocumentHeaderIdSessionless(String documentHeaderId)
                                          throws WorkflowException

get a document based on the document header id which is the primary key for all document types. Using this method does not require that GlobalVariables.getUserSession() be populated. Therefore, this method can be used when a HTTP request is not being processed (e.g. during workflow indexing/post-processing).

Parameters:

documentHeaderId -

Returns:

document, by id

Throws:

WorkflowException

getDocumentsByListOfDocumentHeaderIds

List<Document> getDocumentsByListOfDocumentHeaderIds(Class<? extends Document> documentClass,
                                                     List<String> documentHeaderIds)
                                                     throws WorkflowException

This method retrieves a list of fully-populated documents given a list of document header id values.

Parameters:

documentClass -

documentHeaderIds -

Returns:

list of fully-populated documents

Throws:

WorkflowException

updateDocument

Document updateDocument(Document document)

This method is to allow for documents to be updated. It is currently used to update the document status as well as to allow for locked docs to be unlocked

Parameters:

document - the document to be updated

Returns:

the updated document

saveDocument

Document saveDocument(Document document)
                      throws WorkflowException

This is a helper method that performs the same as the saveDocument(Document, Class) method. The convenience of this method is that the event being used is the standard SaveDocumentEvent.

Throws:

WorkflowException

See Also:

saveDocument(Document, Class)

saveDocument

Document saveDocument(Document document,
                      Class<? extends KualiDocumentEvent> kualiDocumentEventClass)
                      throws WorkflowException

Saves the passed-in document. This will persist it both to the Kuali database, and also initiate it (if necessary) within workflow, so its available in the initiator's action list. This method uses the passed in KualiDocumentEvent class when saving the document. The KualiDocumentEvent class must implement the SaveEvent interface. Note that the system does not support passing in Workflow Annotations or AdHoc Route Recipients on a SaveDocument call. These are sent to workflow on a routeDocument action, or any of the others which actually causes a routing action to happen in workflow. Also note that this method will not check the document action flags to check if a save is valid The calling code should always use the object returned from this method for future operations since a new object is created when the passed-in document is saved.

Parameters:

document - the document to be saved

kualiDocumentEventClass - the event class to use when saving (class must implement the SaveEvent interface)

Returns:

the saved document

Throws:

WorkflowException

routeDocument

Document routeDocument(Document document,
                       String annotation,
                       List<AdHocRouteRecipient> adHocRoutingRecipients)
                       throws WorkflowException

Save and then route the document, optionally providing an annotation which will show up in the route log of the document for the action taken, and optionally providing a list of ad hoc recipients for the document.

Parameters:

document - the document to be routed

annotation - the annotation to appear in the route log of the document

adHocRoutingRecipients - list of ad hoc recipients to which the document will be routed

Returns:

the saved and routed document

Throws:

WorkflowException

approveDocument

Document approveDocument(Document document,
                         String annotation,
                         List<AdHocRouteRecipient> adHocRoutingRecipients)
                         throws WorkflowException

Save and then approve the document, optionally providing an annotation which will show up in the route log of the document for the action taken, and optionally providing a list of ad hoc recipients for the document.

Parameters:

document - the document to be approved

annotation - the annotation to appear in the route log of the document

adHocRoutingRecipients - list of ad hoc recipients to which the document will be routed

Returns:

the saved and approved document

Throws:

WorkflowException

superUserApproveDocument

Document superUserApproveDocument(Document document,
                                  String annotation)
                                  throws WorkflowException

Save and then approve the document as a super user, optionally providing an annotation which will show up in the route log of the document for the action taken.

Parameters:

document - the document to be super user approved

annotation - the annotation to appear in the route log of the document

Returns:

the saved and super user approved document

Throws:

WorkflowException

superUserCancelDocument

Document superUserCancelDocument(Document document,
                                 String annotation)
                                 throws WorkflowException

Save and then cancel the document as a super user, optionally providing an annotation which will show up in the route log of the document for the action taken.

Parameters:

document - the document to be super user canceled

annotation - the annotation to appear in the route log of the document

Returns:

the saved and super user canceled document

Throws:

WorkflowException

superUserDisapproveDocument

Document superUserDisapproveDocument(Document document,
                                     String annotation)
                                     throws WorkflowException

Save and then disapprove the document as a super user, optionally providing an annotation which will show up in the route log of the document for the action taken.

Parameters:

document - the document to be super user disapproved

annotation - the annotation to appear in the route log of the document

Returns:

the saved and super user disapproved document

Throws:

WorkflowException

superUserDisapproveDocumentWithoutSaving

Document superUserDisapproveDocumentWithoutSaving(Document document,
                                                  String annotation)
                                                  throws WorkflowException

Disapprove the document as super user, without saving, optionally providing an annotation which will show up in the route log of the document for the action taken.

Parameters:

document - the document to be super user disapproved

annotation - the annotation to appear in the route log of the document

Returns:

the super user disapproved document

Throws:

WorkflowException

disapproveDocument

Document disapproveDocument(Document document,
                            String annotation)
                            throws Exception

Disapprove the document, without saving, optionally providing an annotation which will show up in the route log of the document for the action taken.

Parameters:

document - the document to be disapproved

annotation - the annotation to appear in the route log of the document

Returns:

the disapproved document

Throws:

Exception

cancelDocument

Document cancelDocument(Document document,
                        String annotation)
                        throws WorkflowException

Cancel the document, without saving, optionally providing an annotation for the disapproval which will show up in the route log of the document for the action taken.

Parameters:

document - the document to be canceled

annotation - the annotation to appear in the route log of the document

Returns:

the canceled document

Throws:

WorkflowException

acknowledgeDocument

Document acknowledgeDocument(Document document,
                             String annotation,
                             List<AdHocRouteRecipient> adHocRecipients)
                             throws WorkflowException

Acknowledge the document, optionally providing an annotation for the acknowledgement which will show up in the route log of the document, and optionally providing a list of ad hoc recipients for the document. The list of ad hoc recipients for this document should have an action requested of acknowledge or fyi as all other actions requested will be discarded as invalid due to the fact that this action being taken is an acknowledgement.

Parameters:

document - the document to be acknowledged

annotation - the annotation to appear in the route log of the document

adHocRecipients - list of ad hoc recipients to which the document will be routed

Returns:

the acknowledged document

Throws:

WorkflowException

blanketApproveDocument

Document blanketApproveDocument(Document document,
                                String annotation,
                                List<AdHocRouteRecipient> adHocRecipients)
                                throws WorkflowException

Blanket approve the document which will save the document, approve the document, and stand in for an approve for all typically generated approval actions requested for this document. The user must have blanket approval authority for this document by being registered as a user in the blanket approval workgroup that is associated with this document type. Optionally an annotation can be provided which will show up for the action taken on the document in the route log. Also optionally a list of ad hoc recipients can be provided for the document, which should be restricted to actions requested of acknowledge and fyi as all other actions requested will be discarded.

Parameters:

document - the document to be blanket approved

annotation - the annotation to appear in the route log of the document

adHocRecipients - list of ad hoc recipients to which the document will be routed

Returns:

the saved and blanket approved document

Throws:

WorkflowException

clearDocumentFyi

Document clearDocumentFyi(Document document,
                          List<AdHocRouteRecipient> adHocRecipients)
                          throws WorkflowException

Clear the fyi requests for the document, optionally providing a list of ad hoc recipients for the document, which should be restricted to action requested of fyi as all other actions requested will be discarded.

Parameters:

document - the document to clear of fyi requests

adHocRecipients - list of ad hoc recipients to which the document will be routed

Returns:

the document

Throws:

WorkflowException

prepareWorkflowDocument

void prepareWorkflowDocument(Document document)
                             throws WorkflowException

Sets the title and app document id in the workflow document

Parameters:

document - the document to prepare

Throws:

WorkflowException

createNoteFromDocument

Note createNoteFromDocument(Document document,
                            String text)

This method creates a note from the given document and note text. The resulting Note will have it's note type set to the value of Document.getNoteType(). Additionally, it's remoteObjectId will be set to the object id of the document's note target.

Parameters:

document - the document from which to use the note type and note target when creating the note

text - the text value to include in the resulting note

Returns:

the note that was created

saveDocumentNotes

boolean saveDocumentNotes(Document document)

Saves the notes associated with the given document if they are in a state where they can be saved. In certain cases they may not be ready to be saved. For example, in maintenance documents where the notes are associated with the business object instead of the document header, the notes cannot be saved until the business object itself has been persisted.

Parameters:

document - the document for which to save notes

Returns:

true if the notes were saved, false if they were not

sendAdHocRequests

Document sendAdHocRequests(Document document,
                           String annotation,
                           List<AdHocRouteRecipient> adHocRecipients)
                           throws WorkflowException

Send ad hoc requests for the given document, optionally providing an annotation which will show up in the route log of the document. Also optionally providing a list of ad hoc recipients for the document. However if no ad hoc recipients are provided, no ad hoc requests will be sent.

Parameters:

document - the document for which the ad hoc requests are sent

annotation - the annotation to appear in the route log of the document

adHocRecipients - list of ad hoc recipients to which the document will be routed

Returns:

the document

Throws:

WorkflowException

sendNoteRouteNotification

Document sendNoteRouteNotification(Document document,
                                   Note note,
                                   Person sender)
                                   throws WorkflowException

Builds an workflow notification request for the note and sends it to note recipient.

Parameters:

document - - document that contains the note

note - - note to notify

sender - - user who is sending the notification

Returns:

the document

Throws:

WorkflowException

recallDocument

Document recallDocument(Document document,
                        String annotation,
                        boolean cancel)
                        throws WorkflowException

Recall the document, optionally providing an annotation for the recall which will show up in the route log of the document for the action taken.

Parameters:

document - the document to recall

annotation - the annotation to appear in the route log of the document

cancel - indicates if the document should be canceled as part of the recall

Returns:

the recalled document

Throws:

WorkflowException

Since:

2.1

completeDocument

Document completeDocument(Document document,
                          String annotation,
                          List adHocRecipients)
                          throws WorkflowException

Save and then complete the document, optionally providing an annotation which will show up in the route log of the document for the action taken, and optionally providing a list of ad hoc recipients for the document

Parameters:

document - the document to complete

annotation - the annotation to appear in the route log of the document

adHocRecipients - list of ad hoc recipients to which the document will be routed

Returns:

the saved and completed document

Throws:

WorkflowException

validateAndPersistDocument

Document validateAndPersistDocument(Document document,
                                    KualiDocumentEvent event)
                                    throws ValidationException

Helper method used to save and validate a document

Parameters:

document - document to be validated and persisted

event - indicates which kualiDocumentEvent was requested

Returns:

the saved document

Throws:

ValidationException