org.bonitasoft.engine.api

Interface DocumentAPI

All Known Subinterfaces:

ProcessAPI, ProcessAPI

public interface DocumentAPI

Manipulate documents that are attached to a process instance.

A document can be stored directly with the process instance, or by reference. If you store a document by reference, the process instance contains a document object that has metadata describing the document: its name, content MimeType, the name of the file of the document, and a URL giving the location of the document. The choice of direct local storage or storage by reference depends on the performance profile of document access within an instance of the process. If you require frequent and rapid access to update the document and the document is not large, use direct storage. If the document is large or is not accessed frequently within a process instance, or is not updated by the process, store it by reference.

Multiple versions of a document can be stored. You can retrieve the latest version or the version that was current at a given milestone (for example process instantiation, or activity completion).

Author:

Emmanuel Duchastenier, Baptiste Mesta

Method Summary

Methods

Modifier and Type	Method and Description
Document	addDocument(long processInstanceId, String documentName, String description, DocumentValue documentValue) Attach a new document to a process instance.
Document	attachDocument(long processInstanceId, String documentName, String fileName, String mimeType, byte[] documentContent) Attach the given document to the specified process instance. The content is stored to enable later retrieval.
Document	attachDocument(long processInstanceId, String documentName, String fileName, String mimeType, String url) Attach a document by reference to the specified process instance. The document itself does not contain content but is a reference to external content specified by its URL.
Document	attachNewDocumentVersion(long processInstanceId, String documentName, String contentFileName, String contentMimeType, byte[] documentContent) Attach a new document version to the specified process instance.
Document	attachNewDocumentVersion(long processInstanceId, String documentName, String fileName, String mimeType, String url) Attach a new version of a document by reference to the specified process instance.
void	deleteContentOfArchivedDocument(long archivedDocumentId) Remove the content of an archived document while keeping it's metadata.
ArchivedDocument	getArchivedProcessDocument(long sourceObjectId) Get an ArchivedDocument based on it's id.
ArchivedDocument	getArchivedVersionOfProcessDocument(long sourceObjectId) Get the original version of the document with the specified identifier.
Document	getDocument(long documentId) Get the document with the specified identifier.
Document	getDocumentAtActivityInstanceCompletion(long activityInstanceId, String documentName) Get the version of the named document when the specified activity completed.
Document	getDocumentAtProcessInstantiation(long processInstanceId, String documentName) Get the version of the named document that was current when the specified process instance is instantiated.
byte[]	getDocumentContent(String storageId) Get content of the document with the specified identifier.
List<Document>	getDocumentList(long processInstanceId, String name, int fromIndex, int numberOfResult) Get a document list that have the specified name on the process
Document	getLastDocument(long processInstanceId, String documentName) Get the last version of the named document for the specified process instance.
List<Document>	getLastVersionOfDocuments(long processInstanceId, int pageIndex, int numberPerPage, DocumentCriterion pagingCriterion) Get the latest version of all documents attached to the specified process instance.
long	getNumberOfDocuments(long processInstanceId) Get the number of documents attached to the specified process instance.
Document	removeDocument(long documentId) Remove the document with the specified identifier and returns it.
SearchResult<ArchivedDocument>	searchArchivedDocuments(SearchOptions searchOptions) Search for archived documents that meet the search options.
SearchResult<ArchivedDocument>	searchArchivedDocumentsSupervisedBy(long userId, SearchOptions searchOptions) Search for archived documents that match the search options and are supervised by the specified user.
SearchResult<Document>	searchDocuments(SearchOptions searchOptions) Search for documents that match the search options.
SearchResult<Document>	searchDocumentsSupervisedBy(long userId, SearchOptions searchOptions) Search for documents that match the search options and are supervised by the specified user.
void	setDocumentList(long processInstanceId, String name, List<DocumentValue> documentsValues) Get a document list that have the specified name on the process
Document	updateDocument(long documentId, DocumentValue documentValue) Attach a new document version to a process instance.

Method Detail

attachDocument

Document attachDocument(long processInstanceId,
                      String documentName,
                      String fileName,
                      String mimeType,
                      String url)
                        throws ProcessInstanceNotFoundException,
                               DocumentAttachmentException

Attach a document by reference to the specified process instance.
The document itself does not contain content but is a reference to external content specified by its URL.

Parameters:

processInstanceId - The identifier of the process instance

documentName - The name of the document

fileName - The filename of the document content

mimeType - The MimeType of the document content (optional)

url - The URL of the document content

Returns:

a document object

Throws:

ProcessInstanceNotFoundException - If the identifier does not refer to an existing process instance.

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DocumentAttachmentException - when an error occurs while attaching the document

Since:

6.0

updateDocument

Document updateDocument(long documentId,
                      DocumentValue documentValue)
                        throws ProcessInstanceNotFoundException,
                               DocumentAttachmentException,
                               AlreadyExistsException

Attach a new document version to a process instance.

Depending on the DocumentValue given the document will be internal (with content) or external (with url). The document state is archived and is then updated to the new version

Parameters:

documentId - The identifier of the document to update

documentValue - The value of the document

Returns:

a document object

Throws:

ProcessInstanceNotFoundException - If the identifier does not refer to an existing process instance.

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DocumentAttachmentException - when an error occurs while attaching the document

AlreadyExistsException - If the document already exists.

Since:

6.4.0

addDocument

Document addDocument(long processInstanceId,
                   String documentName,
                   String description,
                   DocumentValue documentValue)
                     throws ProcessInstanceNotFoundException,
                            DocumentAttachmentException,
                            AlreadyExistsException

Attach a new document to a process instance.

Depending on the DocumentValue given the document will be internal (with content) or external (with url).

1. If the target document is a list of document then we append it to the list
2. If the target document is a list of document and the index is set on the document value then we insert the element in the list at the specified index
3. If the target single document or is non existent in the definition we create it
4. If the target single document and is already existent an exception is thrown

Parameters:

processInstanceId - The identifier of the process instance

documentName - The name of the document

description - The description of the document

documentValue - The value of the document

Returns:

a document object

Throws:

ProcessInstanceNotFoundException - If the identifier does not refer to an existing process instance.

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DocumentAttachmentException - when an error occurs while attaching the document

AlreadyExistsException - If the document already exists.

Since:

6.4.0

attachDocument

Document attachDocument(long processInstanceId,
                      String documentName,
                      String fileName,
                      String mimeType,
                      byte[] documentContent)
                        throws ProcessInstanceNotFoundException,
                               DocumentAttachmentException

Attach the given document to the specified process instance.
The content is stored to enable later retrieval.

Parameters:

processInstanceId - The identifier of the process instance

documentName - The name of the document

fileName - The name of the file containing the document

mimeType - The MimeType of the document content (optional)

documentContent - The content of the document

Returns:

a document object

Throws:

ProcessInstanceNotFoundException - If the identifier does not refer to an existing process instance.

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DocumentAttachmentException - when an error occurs while attaching the document

Since:

6.0

attachNewDocumentVersion

Document attachNewDocumentVersion(long processInstanceId,
                                String documentName,
                                String fileName,
                                String mimeType,
                                String url)
                                  throws DocumentAttachmentException

Attach a new version of a document by reference to the specified process instance. The referenced document is a new version of the named document.

Parameters:

processInstanceId - The identifier of the process instance

documentName - The name of the document

fileName - The name of the file containing the document

mimeType - The MimeType of the document content (optional)

url - The URL of the document content

Returns:

a document object

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DocumentAttachmentException - when an error occurs while attaching the new version of the document

Since:

6.0

attachNewDocumentVersion

Document attachNewDocumentVersion(long processInstanceId,
                                String documentName,
                                String contentFileName,
                                String contentMimeType,
                                byte[] documentContent)
                                  throws DocumentAttachmentException

Attach a new document version to the specified process instance. The document is a new version of the named document.
The content is stored to enable later retrieval.

Parameters:

processInstanceId - The identifier of the process instance

documentName - The name of the document

contentFileName - The name of the file containing the content of the document

contentMimeType - The MimeType of the document content (optional)

documentContent - The content of the document

Returns:

a document object

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DocumentAttachmentException - when an error occurs while attaching the new version of the document

Since:

6.0

getDocument

Document getDocument(long documentId)
                     throws DocumentNotFoundException

Get the document with the specified identifier.

Parameters:

documentId - The identifier of the document to retrieve

Returns:

a document object

Throws:

DocumentNotFoundException - If the specified identifier does not refer to an existing document.

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

Since:

6.0

removeDocument

Document removeDocument(long documentId)
                        throws DocumentNotFoundException,
                               DeletionException

Remove the document with the specified identifier and returns it.

this archive and delete mapping on the process, i.e. the content of the document itself will be kept in database, use deleteContentOfArchivedDocument(long) to delete the content

Parameters:

documentId - The identifier of the document to retrieve

Returns:

the removed document object

Throws:

DocumentNotFoundException - If the specified identifier does not refer to an existing document.

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DeletionException

Since:

6.4.0

getLastVersionOfDocuments

List<Document> getLastVersionOfDocuments(long processInstanceId,
                                       int pageIndex,
                                       int numberPerPage,
                                       DocumentCriterion pagingCriterion)
                                         throws ProcessInstanceNotFoundException,
                                                DocumentException

Get the latest version of all documents attached to the specified process instance.

Parameters:

processInstanceId - The identifier of the process instance

pageIndex - The index of the page

numberPerPage - The number of documents to list per page

pagingCriterion - The sort criterion for the returned list

Returns:

the matching list of documents a paginated list of the latest version of each document attached to the process instance

Throws:

ProcessInstanceNotFoundException - If the identifier does not refer to an existing process instance.

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DocumentException - when any other error occurs during document handling

Since:

6.0

getDocumentContent

byte[] getDocumentContent(String storageId)
                          throws DocumentNotFoundException

Get content of the document with the specified identifier.

Parameters:

storageId - The identifier of the document to retrieve the content from

Returns:

document content as a byte array

Throws:

DocumentNotFoundException - If the specified identifier does not refer to an existing document.

InvalidSessionException - when the session is note valid

Since:

6.0

getLastDocument

Document getLastDocument(long processInstanceId,
                       String documentName)
                         throws DocumentNotFoundException

Get the last version of the named document for the specified process instance.

Parameters:

processInstanceId - The identifier of the process instance that the document is attached to

documentName - The name of the document

Returns:

a document object

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DocumentNotFoundException - If the specified documentName does not refer to an existing document attached to this process instance

Since:

6.0

getDocumentAtProcessInstantiation

Document getDocumentAtProcessInstantiation(long processInstanceId,
                                         String documentName)
                                           throws DocumentNotFoundException

Get the version of the named document that was current when the specified process instance is instantiated.

Parameters:

processInstanceId - The identifier of the process instance

documentName - The name of the document

Returns:

a document object

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DocumentNotFoundException - If the specified documentName does not refer to a document attached to the specified process instance.

Since:

6.0

getDocumentAtActivityInstanceCompletion

Document getDocumentAtActivityInstanceCompletion(long activityInstanceId,
                                               String documentName)
                                                 throws DocumentNotFoundException

Get the version of the named document when the specified activity completed.

Parameters:

activityInstanceId - The identifier of the activity instance

documentName - The name of the document

Returns:

a document object

Throws:

DocumentNotFoundException - If the specified documentName does not refer to an existing document attached to the process instance that contains the activity.

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

Since:

6.0

getNumberOfDocuments

long getNumberOfDocuments(long processInstanceId)
                          throws DocumentException

Get the number of documents attached to the specified process instance. A document with multiple versions is counted once.

Parameters:

processInstanceId - The process instance identifier

Returns:

the number of documents in the specified process instance

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DocumentException - when an error occurs during document handling

Since:

6.0

searchDocuments

SearchResult<Document> searchDocuments(SearchOptions searchOptions)
                                       throws SearchException

Search for documents that match the search options.

Parameters:

searchOptions - A SearchOptions object defining the search options

Returns:

the matching document list and its total number

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

SearchException - when an error occurs during the search

Since:

6.0

searchDocumentsSupervisedBy

SearchResult<Document> searchDocumentsSupervisedBy(long userId,
                                                 SearchOptions searchOptions)
                                                   throws UserNotFoundException,
                                                          SearchException

Search for documents that match the search options and are supervised by the specified user.

Parameters:

userId - The identifier of the supervising user

searchOptions - A SearchOptions object defining the search options

Returns:

the list of matching documents and the number of such documents

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

UserNotFoundException - when the specified userId does not refer to an existing user

SearchException - when an error occurs during the search

Since:

6.0

searchArchivedDocuments

SearchResult<ArchivedDocument> searchArchivedDocuments(SearchOptions searchOptions)
                                                       throws SearchException

Search for archived documents that meet the search options. An archived document is a document that is not the latest version.

Parameters:

searchOptions - A SearchOptions object defining the search options

Returns:

the matching archived document list and its total number

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

SearchException - when an error occurs during the search

Since:

6.0

searchArchivedDocumentsSupervisedBy

SearchResult<ArchivedDocument> searchArchivedDocumentsSupervisedBy(long userId,
                                                                 SearchOptions searchOptions)
                                                                   throws UserNotFoundException,
                                                                          SearchException

Search for archived documents that match the search options and are supervised by the specified user. An archived document is a document that is not the latest version.

Parameters:

userId - The identifier of the supervising user

searchOptions - A SearchOptions object defining the search options

Returns:

the matching archived document list and its total number

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

UserNotFoundException - when the specified userId does not refer to an existing user

SearchException - when an error occurs during the search

Since:

6.0

getArchivedProcessDocument

ArchivedDocument getArchivedProcessDocument(long sourceObjectId)
                                            throws ArchivedDocumentNotFoundException

Get an ArchivedDocument based on it's id.

Parameters:

sourceObjectId - The identifier of the document

Returns:

an archived document

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

ArchivedDocumentNotFoundException - when the specified identifier does not refer to an archived document

Since:

6.0

getArchivedVersionOfProcessDocument

ArchivedDocument getArchivedVersionOfProcessDocument(long sourceObjectId)
                                                     throws ArchivedDocumentNotFoundException

Get the original version of the document with the specified identifier.

Parameters:

sourceObjectId - The identifier of the document

Returns:

an archived document

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

ArchivedDocumentNotFoundException - If the identifier does not refer to any existing archived document.

Since:

6.0

getDocumentList

List<Document> getDocumentList(long processInstanceId,
                             String name,
                             int fromIndex,
                             int numberOfResult)
                               throws DocumentNotFoundException

Get a document list that have the specified name on the process

Parameters:

processInstanceId - The identifier of the process instance that contains the list

name - The name of the document

fromIndex - The index of the first element to be retrieved (it starts from zero)

numberOfResult - The max number of result to get

Returns:

The document list

Throws:

DocumentNotFoundException

Since:

6.4.0

setDocumentList

void setDocumentList(long processInstanceId,
                   String name,
                   List<DocumentValue> documentsValues)
                     throws DocumentNotFoundException,
                            DocumentException

Get a document list that have the specified name on the process

Parameters:

processInstanceId - The identifier of the process instance that contains the list

name - The name of the document list

documentsValues - the values to set the list with

Throws:

DocumentException - If an error occurs

DocumentNotFoundException

Since:

6.4.0

See Also:

BaseElement.getId()

deleteContentOfArchivedDocument

void deleteContentOfArchivedDocument(long archivedDocumentId)
                                     throws DocumentException,
                                            DocumentNotFoundException

Remove the content of an archived document while keeping it's metadata.

After calling this method you will not be able to retrieve the content of the document since it will be erased from the database. This method can be useful for keeping history of a document without overloading the database.

Parameters:

archivedDocumentId - The identifier of the archived document to remove content on

Throws:

DocumentNotFoundException - If the identifier does not refer to any existing archived document.

DocumentException - If an error occurs

Since:

6.4.0

See Also:

BaseElement.getId()