org.kuali.rice.krad.document
Interface Document

All Superinterfaces:

BusinessObject, GloballyUnique, ModelObjectBasic, PersistableBusinessObject, Serializable, Versioned

All Known Subinterfaces:

MaintenanceDocument, MaintenanceDocument, TransactionalDocument

All Known Implementing Classes:

BookOrderDocument, DocumentBase, IdentityManagementGroupDocument, IdentityManagementKimDocument, IdentityManagementPersonDocument, IdentityManagementRoleDocument, IdentityManagementTypeAttributeTransactionalDocument, MaintenanceDocumentBase, MaintenanceDocumentBase, RuleDocument, TransactionalDocumentBase, TravelAuthorizationDocument, TravelDocument2

public interface Document
extends PersistableBusinessObject

This is the Document interface. All entities that are regarded as "eDocs" in the system, including Maintenance documents and Transaction Processing documents should implement this interface as it defines methods that are necessary to interact with the underlying frameworks and components (i.e. notes, attachments, workflow, etc).

Author:

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

Method Summary

void	addNote(Note note) Adds the given Note to the document's list of Notes.
void	addPessimisticLock(PessimisticLock lock) This method adds a new PessimisticLock to the document NOTE: LOCKS ADDED VIA THIS METHOD WILL NOT BE SAVED WITH THE DOCUMENT
void	afterActionTaken(ActionType performed, ActionTakenEvent event) method to integrate with workflow where we will be able to perform logic after an action taken being performed on a document
void	afterWorkflowEngineProcess(boolean successfullyProcessed) This method will be called after the Workflow engine has completely finished processing a document.
void	beforeWorkflowEngineProcess() This method will be called before the Workflow engine has begun processing a document.
void	doActionTaken(ActionTakenEvent event) method to integrate with workflow where we will be able to perform logic for an action taken being performed on a document
void	doRouteLevelChange(DocumentRouteLevelChange levelChangeEvent) method to integrate with workflow, where we will actually handle the transitions of levels for documents
void	doRouteStatusChange(DocumentRouteStatusChange statusChangeEvent) Handle the doRouteStatusChange event from the post processor
List<KualiDocumentEvent>	generateSaveEvents() Generate any necessary events required during the save event generation
List<AdHocRoutePerson>	getAdHocRoutePersons() getter method to get the list of ad hoc route persons associated with a document at a point in time, this list is only valid for a given users version of a document as this state is only persisted in workflow itself when someone takes an action on a document
List<AdHocRouteWorkgroup>	getAdHocRouteWorkgroups() getter method to get the list of ad hoc route workgroups associated with a document at a point in time, this list is only valid for a given users version of a document as this state is only persisted in workflow itself when someone takes an action on a document
boolean	getAllowsCopy() This method returns whether or not this document can be copied.
String	getBasePathToDocumentDuringSerialization() Returns an evaluator object that determines whether a given property relative to the root object (wrapDocumentWithMetadataForXmlSerialization() is serializable during the document serialization process.
String	getCustomLockDescriptor(Person user) Generates a custom lock descriptor for pessimistic locking.
DocumentHeader	getDocumentHeader() This retrieves the standard DocumentHeader object, which contains standard meta-data about a document.
String	getDocumentNumber() All documents have a document header id.
PropertySerializabilityEvaluator	getDocumentPropertySerizabilityEvaluator() Returns an evaluator object that determines whether a given property relative to the root object (wrapDocumentWithMetadataForXmlSerialization() is serializable during the document serialization process.
String	getDocumentTitle() Getter method to get the document title as it will appear in and be searchable in workflow.
List<String>	getLockClearingMethodNames() This is a method that is used by Kuali Pessimistic Locking to get the names (method to call values) of the KNS KualiDocumentActionBase methods that should release locks
List<String>	getLockClearningMethodNames() Deprecated.
Note	getNote(int index) Retrieves the note at the given index.
List<Note>	getNotes() Returns a mutable list of all notes on the document.
PersistableBusinessObject	getNoteTarget() Return the target PersistableBusinessObject that notes associated with this document should be attached to.
NoteType	getNoteType() Returns the note type which should be used for notes associated with this document.
List<PessimisticLock>	getPessimisticLocks() This method gets a list of the PessimisticLock objects associated with this document
List<String>	getWorkflowEngineDocumentIdsToLock() This method will be called before the Workflow engine has begun processing a document.
String	getXmlForRouteReport() This method is used to get the xml that should be used in a Route Report.
void	populateDocumentForRouting() This is the method to integrate with workflow, where we will actually populate the workflow defined data structure(s) so that workflow can routed based on this data.
void	postProcessSave(KualiDocumentEvent event) Do any work on the document after the save.
void	prepareForSave() This method provides a hook that will be called before the document is saved.
void	prepareForSave(KualiDocumentEvent event) Do any work on the document that requires the KualiDocumentEvent before the save.
void	processAfterRetrieve() This method provides a hook that will be called after a document is retrieved, but before it is returned from the DocumentService.
void	refreshPessimisticLocks() This method updates the list of PessimisticLock objects on the document if changes could have been made
boolean	removeNote(Note note) Removes the given note from the document's list of notes.
String	serializeDocumentToXml() This is a method where we can get the xml of a document that the workflow system will use to base it's routing and search attributes on.
void	setAdHocRoutePersons(List<AdHocRoutePerson> adHocRoutePersons) setter method to set the list of ad hoc route persons associated with a document at a point in time, this list is only valid for a given users version of a document as this state is only persisted in workflow itself when someone takes an action on a document
void	setAdHocRouteWorkgroups(List<AdHocRouteWorkgroup> adHocRouteWorkgroups) setter method to set the list of ad hoc route workgroups associated with a document at a point in time, this list is only valid for a given users version of a document as this state is only persisted in workflow itself when someone takes an action on a document
void	setDocumentHeader(DocumentHeader documentHeader) Sets the associated DocumentHeader for this document.
void	setDocumentNumber(String documentHeaderId) setter for document header id
void	setNotes(List<Note> notes) Sets the document's list of notes to the given list.
boolean	useCustomLockDescriptors() This method returns whether or not this document supports custom lock descriptors for pessimistic locking.
void	validateBusinessRules(KualiDocumentEvent event) Sends document off to the rules engine to verify business rules.
Object	wrapDocumentWithMetadataForXmlSerialization() This method will return the root object to be serialized for workflow routing.

Methods inherited from interface org.kuali.rice.krad.bo.PersistableBusinessObject

buildListOfDeletionAwareLists, getExtension, isNewCollectionRecord, linkEditableUserFields, refreshNonUpdateableReferences, refreshReferenceObject, setExtension, setNewCollectionRecord, setObjectId, setVersionNumber

Methods inherited from interface org.kuali.rice.krad.bo.BusinessObject

refresh

Methods inherited from interface org.kuali.rice.core.api.mo.ModelObjectBasic

toString

Methods inherited from interface org.kuali.rice.core.api.mo.common.Versioned

getVersionNumber

Methods inherited from interface org.kuali.rice.core.api.mo.common.GloballyUnique

getObjectId

Method Detail

getDocumentHeader

DocumentHeader getDocumentHeader()

This retrieves the standard DocumentHeader object, which contains standard meta-data about a document.

Returns:

document header since all docs will have a document header

setDocumentHeader

void setDocumentHeader(DocumentHeader documentHeader)

Sets the associated DocumentHeader for this document.

Parameters:

documentHeader -

getDocumentNumber

String getDocumentNumber()

All documents have a document header id. This is the quick accessor to that unique identifier and should return the same value as documentHeader.getDocumentHeaderId().

Returns:

doc header id

setDocumentNumber

void setDocumentNumber(String documentHeaderId)

setter for document header id

Parameters:

documentHeaderId -

populateDocumentForRouting

void populateDocumentForRouting()

This is the method to integrate with workflow, where we will actually populate the workflow defined data structure(s) so that workflow can routed based on this data. This method is responsible for passing over the proper Kuali (client system) data that will be used by workflow to determine how the document is actually routed.

serializeDocumentToXml

String serializeDocumentToXml()

This is a method where we can get the xml of a document that the workflow system will use to base it's routing and search attributes on.

Returns:

the document serialized to an xml string

getXmlForRouteReport

String getXmlForRouteReport()

This method is used to get the xml that should be used in a Route Report. In it's default implementation this will call the methods prepareForSave() and populateDocumentForRouting().

Returns:

XML data for routing

doRouteLevelChange

void doRouteLevelChange(DocumentRouteLevelChange levelChangeEvent)

method to integrate with workflow, where we will actually handle the transitions of levels for documents

Parameters:

levelChangeEvent - route level change event

doActionTaken

void doActionTaken(ActionTakenEvent event)

method to integrate with workflow where we will be able to perform logic for an action taken being performed on a document

Parameters:

event - action taken event

afterActionTaken

void afterActionTaken(ActionType performed,
                      ActionTakenEvent event)

method to integrate with workflow where we will be able to perform logic after an action taken being performed on a document

Parameters:

performed - action type performed

event - action taken event

Since:

2.1

afterWorkflowEngineProcess

void afterWorkflowEngineProcess(boolean successfullyProcessed)

This method will be called after the Workflow engine has completely finished processing a document.

Parameters:

successfullyProcessed - - true if the document was processed successfully, false otherwise

beforeWorkflowEngineProcess

void beforeWorkflowEngineProcess()

This method will be called before the Workflow engine has begun processing a document.

getWorkflowEngineDocumentIdsToLock

List<String> getWorkflowEngineDocumentIdsToLock()

This method will be called before the Workflow engine has begun processing a document.

Returns:

additional document IDs to lock prior to processing

getDocumentTitle

String getDocumentTitle()

Getter method to get the document title as it will appear in and be searchable in workflow.

Returns:

document title

getAdHocRoutePersons

List<AdHocRoutePerson> getAdHocRoutePersons()

getter method to get the list of ad hoc route persons associated with a document at a point in time, this list is only valid for a given users version of a document as this state is only persisted in workflow itself when someone takes an action on a document

Returns:

list of ad hoc route persons

getAdHocRouteWorkgroups

List<AdHocRouteWorkgroup> getAdHocRouteWorkgroups()

getter method to get the list of ad hoc route workgroups associated with a document at a point in time, this list is only valid for a given users version of a document as this state is only persisted in workflow itself when someone takes an action on a document

Returns:

list of ad hoc route workgroups

setAdHocRoutePersons

void setAdHocRoutePersons(List<AdHocRoutePerson> adHocRoutePersons)

setter method to set the list of ad hoc route persons associated with a document at a point in time, this list is only valid for a given users version of a document as this state is only persisted in workflow itself when someone takes an action on a document

Parameters:

adHocRoutePersons -

setAdHocRouteWorkgroups

void setAdHocRouteWorkgroups(List<AdHocRouteWorkgroup> adHocRouteWorkgroups)

setter method to set the list of ad hoc route workgroups associated with a document at a point in time, this list is only valid for a given users version of a document as this state is only persisted in workflow itself when someone takes an action on a document

Parameters:

adHocRouteWorkgroups -

prepareForSave

void prepareForSave()

This method provides a hook that will be called before the document is saved. This method is useful for applying document level data to children. For example, if someone changes data at the document level, and that data needs to be propagated to child objects or child lists of objects, you can use this method to update the child object or iterate through the list of child objects and apply the document level data to them. Any document that follows this paradigm will need to make use of this method to apply all of those changes.

validateBusinessRules

void validateBusinessRules(KualiDocumentEvent event)

Sends document off to the rules engine to verify business rules.

Parameters:

event - - indicates which document event was requested

Throws:

ValidationException - - containing the MessageMap from the validation session.

prepareForSave

void prepareForSave(KualiDocumentEvent event)

Do any work on the document that requires the KualiDocumentEvent before the save.

Parameters:

event - - indicates which document event was requested

postProcessSave

void postProcessSave(KualiDocumentEvent event)

Do any work on the document after the save.

Parameters:

event - - indicates which document event was requested

processAfterRetrieve

void processAfterRetrieve()

This method provides a hook that will be called after a document is retrieved, but before it is returned from the DocumentService.

getAllowsCopy

boolean getAllowsCopy()

This method returns whether or not this document can be copied.

Returns:

True if it can be copied, false if not.

generateSaveEvents

List<KualiDocumentEvent> generateSaveEvents()

Generate any necessary events required during the save event generation

Returns:

a list of document events that were triggered by the save event

doRouteStatusChange

void doRouteStatusChange(DocumentRouteStatusChange statusChangeEvent)

Handle the doRouteStatusChange event from the post processor

Parameters:

statusChangeEvent - status change event

getNoteType

NoteType getNoteType()

Returns the note type which should be used for notes associated with this document. This method should never return null.

Returns:

the note type supported by this document, this value should never be null

getNoteTarget

PersistableBusinessObject getNoteTarget()

Return the target PersistableBusinessObject that notes associated with this document should be attached to. In general, this method should never return null. However, it is permissible that it will return a business object which has not been persisted yet (and therefore does not have it's unique object id established). This is only valid in cases where the note type is NoteType.BUSINESS_OBJECT. In these cases it's the responsibility for implementers of the Document interface to handle storing transient copies of the document notes (in XML or otherwise) until the underlying note target has been persisted and can be attached to the document's notes via it's object id.

Returns:

the PersistableBusinessObject with which notes on this document should be associated

addNote

void addNote(Note note)

Adds the given Note to the document's list of Notes.

Parameters:

note - the Note to add, must be non-null

getNotes

List<Note> getNotes()

Returns a mutable list of all notes on the document.

Returns:

the list of notes associated with this document, if this document has no notes then an empty list will be returned

setNotes

void setNotes(List<Note> notes)

Sets the document's list of notes to the given list.

Parameters:

notes - the list of notes to set on the document, must be non-null

getNote

Note getNote(int index)

Retrieves the note at the given index.

Parameters:

index - the zero-based index of the note to retrieve

Returns:

the note located at the given index

Throws:

IndexOutOfBoundsException - if the index is out of range

removeNote

boolean removeNote(Note note)

Removes the given note from the document's list of notes.

Parameters:

note - the note to remove from the document's list of notes, must be non-null

Returns:

true if the note was successfully removed, false if the list did not contain the given note

getPessimisticLocks

List<PessimisticLock> getPessimisticLocks()

This method gets a list of the PessimisticLock objects associated with this document

Returns:

list of pessimistic locks

refreshPessimisticLocks

void refreshPessimisticLocks()

This method updates the list of PessimisticLock objects on the document if changes could have been made

addPessimisticLock

void addPessimisticLock(PessimisticLock lock)

This method adds a new PessimisticLock to the document NOTE: LOCKS ADDED VIA THIS METHOD WILL NOT BE SAVED WITH THE DOCUMENT

Parameters:

lock - - the lock to add to the document

getLockClearningMethodNames

@Deprecated
List<String> getLockClearningMethodNames()

Deprecated.

Renamed:

Returns:

the list of method names of an action that should clear locks for the current user

See Also:

getLockClearingMethodNames()

getLockClearingMethodNames

List<String> getLockClearingMethodNames()

This is a method that is used by Kuali Pessimistic Locking to get the names (method to call values) of the KNS KualiDocumentActionBase methods that should release locks

Returns:

the list of method names of an action that should clear locks for the current user

getBasePathToDocumentDuringSerialization

String getBasePathToDocumentDuringSerialization()

Returns an evaluator object that determines whether a given property relative to the root object (wrapDocumentWithMetadataForXmlSerialization() is serializable during the document serialization process.

Returns:

a fully initialized evaluator object, ready to be used for workflow routing

See Also:

DocumentSerializerService, wrapDocumentWithMetadataForXmlSerialization()

getDocumentPropertySerizabilityEvaluator

PropertySerializabilityEvaluator getDocumentPropertySerizabilityEvaluator()

Returns an evaluator object that determines whether a given property relative to the root object (wrapDocumentWithMetadataForXmlSerialization() is serializable during the document serialization process.

Returns:

a fully initialized evaluator object, ready to be used for workflow routing

See Also:

DocumentSerializerService, wrapDocumentWithMetadataForXmlSerialization()

wrapDocumentWithMetadataForXmlSerialization

Object wrapDocumentWithMetadataForXmlSerialization()

This method will return the root object to be serialized for workflow routing. If necessary, this method will wrap this document object with a wrapper (i.e. contains a reference back to this document). This wrapper may also contain references to additional objects that provide metadata useful to the workflow engine. If no wrappers are necessary, then this object may return "this"

Returns:

a wrapper object (most likely containing a reference to "this"), or "this" itself.

See Also:

KualiDocumentXmlMaterializer

useCustomLockDescriptors

boolean useCustomLockDescriptors()

This method returns whether or not this document supports custom lock descriptors for pessimistic locking.

Returns:

True if the document can generate custom lock descriptors, false otherwise.

See Also:

getCustomLockDescriptor(Person)

getCustomLockDescriptor

String getCustomLockDescriptor(Person user)

Generates a custom lock descriptor for pessimistic locking. This method should not be called unless useCustomLockDescriptors() returns true.

Parameters:

user - The user trying to establish the lock.

Returns:

A String representing the lock descriptor.

See Also:

useCustomLockDescriptors(), PessimisticLockService