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	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.
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.
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.
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.

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 - when the processInstanceId does not refer to an existing process instance

InvalidSessionException - when the session is not valid

DocumentAttachmentException - when an error occurs while attaching the document

Since:

6.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 - when the processInstanceId does not refer to an existing process instance

InvalidSessionException - when the session is not valid

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 - when the session is not valid

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 - when the session is not valid

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 - when the document identifier does not refer to an existing document

InvalidSessionException - when the session is not valid

Since:

6.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 - when the specified processInstanceId does not refer to an existing process instance

InvalidSessionException - when the session is not valid

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 id of the document to retrive the content from

Returns:

document content as a byte array

Throws:

DocumentNotFoundException - when the specified documentId 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 - when the session is not valid

DocumentNotFoundException - when 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 - when the session is not valid

DocumentNotFoundException - when 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 - when the specified documentName does not refer to an existing document attached to the process instance that contains the activity

InvalidSessionException - when the session is not valid

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 - when the session is not valid

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 - when the session is not valid

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 - when the session is not valid

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 - when the session is not valid

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 - when the session is not valid

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 - when the session is not valid

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 - when the session is not valid

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

Since:

6.0