Managing Documents and Folders

The Infinity Process Platform service DocumentManagementService provides functionality for Document Management operations in an Infinity Process Platform runtime environment.

Managing Documents

The following operations on documents are provided via the DocumentManagementService:

Retrieving Documents

To get a specific document or multiple documents, choose the appropriate method depending on which criteria the document search should be performed.

Retrieving Documents by ID or Path

Use the following method to get a document via document ID or path:

Document getDocument(String documentId) throws DocumentManagementServiceException;

If no document with such an ID or path exists, it returns null.

Retrieving Multiple Documents by ID or Path

In case you like to retrieve multiple documents, which you determine via a list of document IDs, use:

List/*<? extends Document>*/ getDocuments(List/*<String>*/ documentIds) throws DocumentManagementServiceException;

Retrieving Documents based on document query

The following method retrieves all documents satisfying the criteria specified in the provided query:

Documents findDocuments(DocumentQuery query);

The method returns a list of Document objects for a query of type DocumentQuery.

Retrieving Documents based on Name Pattern

Retrieving documents based on a given name pattern can be done via the following method:

List/*<? extends Document>*/ findDocumentsByName(String namePattern) throws DocumentManagementServiceException;

This method returns a list of documents matching the name pattern.

Note This method is deprecated and will be removed in a later release. Please use the method described in section Retrieving Documents based on document query instead.

Retrieving Documents based on the XPath query

The following methods returns a list of documents based on a given XPath query:

List/*<? extends Document>*/ findDocuments(String xpathQuery) throws DocumentManagementServiceException;

Note This method is deprecated and will be removed in a later release. Please use the method described in section Retrieving Documents based on document query instead.

Extending the search from the default repository to multiple repository instances

You can extend the document search from the default repository to either all repositories or to all specified repositories by setting a RepositoryPolicy. Refer to section Using Policies of chapter Building Queries for details on this policy.

The following example searches for documents in a specified list of repositories:

DocumentQuery query = DocumentQuery.findAll();
Documents findDocuments(DocumentQuery query);
query.setPolicy(new RepositoryPolicy(<list of repository Ids>));

Retrieving Document Versions

Document versions can be retrieved via the following method:

List/*<? extends Document>*/ getDocumentVersions(String documentId) throws DocumentManagementServiceException;

All versions of the document with the given document ID are returned in a list.

Returning a Document with Version Information

Version information like revisionId, revisionName and versionLabels are returned if a new version is created or via getDocumentVersions() as described in section Retrieving Document Versions.

Note that method calls that do not directly create or retrieve a document do not return version labels. They return revision id and revision name as org.eclipse.stardust.engine.core.spi.dms.RepositoryConstants.VERSION_VERSIONED = "VERSIONED", if the document has versions available.

The following DocumentManagementService methods return revisionId, revisionName and versionLabels:

List<Document< getDocumentVersions(String documentId) throws DocumentManagementServiceException;

Document updateDocument(Document document, boolean createNewRevision, String versionComment, String versionLabel, boolean keepLocked) throws DocumentManagementServiceException;

Document updateDocument(Document document, byte[] content, String encoding, boolean createNewRevision, String versionComment, String versionLabel, boolean keepLocked) throws DocumentManagementServiceException;

Document versionDocument(String documentId, String versionComment, String versionLabel) throws DocumentManagementServiceException;

Retrieving the Content of Documents

To retrieve the content of a document identified by a given document ID, use the following method:

byte[] retrieveDocumentContent(String documentId) throws DocumentManagementServiceException;

Note:
This method should only be used for documents of reasonable size as the full content will be materialized in memory both on the server as well as on the client. It is recommended to us the facilities provided by the DmsContentServlet for memory efficient content access.

Creating a Document

Creating an empty Document by document info

To create a document in a folder with a specific ID, described by an instance of DocumentInfo, use the following method:

Document createDocument(String folderId, DocumentInfo document) throws DocumentManagementServiceException;

The parameter folderId specifies the ID or path of the folder to create the document in. The value "/" designates the top-level folder. The new document will have no content.

Note that it is also possible to target a different repository.

Creating a Document with content by document info

In case you like to create a document in a folder with a specific ID, described by an instance of DocumentInfo and write a given content to it, use:

Document createDocument(String folderId, DocumentInfo document, byte[] content,
         String encoding) throws DocumentManagementServiceException;

The parameter folderId specifies the ID or path of the folder to create the document in. The value "/" designates the top-level folder. The content of the document will be the content of parameter content.

Note:
This method should only be used for documents of reasonable size as the full content will be materialized in memory both on the server as well as on the client. It is recommended to us the facilities provided by the DmsContentServlet for memory efficient content access.

Creating a New Document Version

Use the following method to create a new document version for a document with a given ID or path:

Document versionDocument(String documentId, String versionComment, String versionLabel) throws DocumentManagementServiceException;

The method returns a document describing the new document version. Parameter versionLabel defines the label for the new revision. Note that the label must be unique per document. Via versionCommentcomment you can add a comment for the new revision.

Updating a Document

You have the option to update a document without updating its content or including its content by providing a new content.

Updating a Document except the content

The following method performs an update on a document without updating the content:

Document updateDocument(Document document, boolean createNewRevision, 
   String versionComment, String versionLabel, boolean keepLocked) throws DocumentManagementServiceException;

The parameter createNewRevision determines if a new revision of the document should be created or not. If createNewRevision is true, the new revision will be labeled with the label specified via versionLabel. Note that the label must be unique per document. Parameter keepLocked determines if the document will be kept locked after update. A versionComment can be specified to comment the version operation.

Updating a Document and its content

To update a document including its content, use:

Document updateDocument(Document document, byte[] content, String encoding,
         boolean createNewRevision, String versionComment, String versionLabel, boolean keepLocked) throws DocumentManagementServiceException;

The document will be updated with the content provided via the content parameter by using the encoding specified via the encoding parameter. Parameter createNewRevision determines if a new revision of the document should be created or not. If createNewRevision is true, the new revision will be labeled with the label specified via versionLabel. Note that the label must be unique per document. Parameter keepLocked determines if the document will be kept locked after update. A versionComment can be specified to comment the version operation.

Note:
This method should only be used for documents of reasonable size as the full content will be materialized in memory both on the server as well as on the client. It is recommended to us the facilities provided by the DmsContentServlet for memory efficient content access.

Deleting a Document

Deleting a document is possible by ID or Path with the following method:

void removeDocument(String documentId) throws DocumentManagementServiceException;

Removing a Document Version

A version of a document can be removed via the following method:

void removeDocumentVersion(String documentId, String documentRevisionId) throws DocumentManagementServiceException;

Parameters are the Id of the document and the Id of the document revision. Note that at least one version has to remain. A call to remove the last remaining version leads to a DocumentManagementServiceException.

Also, in case the document exists, but the documentRevisionId cannot be resolved to a version of the document, a DocumentManagementServiceException is thrown.

Note that it is also possible to target a document of a different repository.

Moving a Document to a Target Path

Use the following method to move a document to a specified path:

Document moveDocument(final String documentId, final String targetPath) throws DocumentManagementServiceException;

Parameters are the Id of the document to be moved and the target path or Id of the folder to move the document to. The targetPath is given as String value. Return value is the moved document.

In case of Document Management specific errors a DocumentManagementServiceException is thrown.

Note that if the target path or folder Id points to a different repository than the source document is located in, only the latest version is moved to the targeted repository.

Moving a Document to a different Repository

In case you move a document with a target path or target folder Id that resides in a different repository than the source document, the latest document version is copied to the target repository.

If the file size of source and target document match, the source document is removed including all older document versions. Note that in case the file size is different, the source document is not removed and an exception is thrown.

To get the root folder of the target repository instead of the default repository, use method getFolder(String folderId). Refer to section Retrieving a Folder by ID for details on using this method.

Another way is to use a target folder when moving to another folder.

Example usage

The following code moves a document text.txt from the default repository to a repository with Id TEST_REPO_ID:

   Document doc = getDms().getDocument(RepositoryIdUtils.addRepositoryId("/test.txt", TEST_REPO_ID));

   Document movedDoc = getDms().moveDocument(doc.getId(), 
   RepositoryIdUtils.addRepositoryId("/", TEST_REPO_ID));

Now we move the document from the repository with Id TEST_REPO_ID to the system repository:

   Document movedDocSys = getDms().moveDocument(movedDoc.getId(),
   RepositoryIdUtils.addRepositoryId("/", RepositoryManager.SYSTEM_REPOSITORY_ID));

Note that the retrieved document Id is only required if you like to access one of the non-default repositories per path.

The next example moves a document using a target path:

   Document doc = getDms().getDocument(RepositoryIdUtils.addRepositoryId("/test.txt", TEST_REPO_ID));

   // moving the document from the test repository to the default system repository path
   Folder targetFolder = getDms().getFolder(RepositoryIdUtils.addRepositoryId("/", SYSTEM_REPO_ID));
   Document movedDoc = getDms().moveDocument(doc.getId(), targetFolder.getId());

   // moving the document from the default repository to the test repository path
   Folder targetFolder2 = getDms().getFolder(RepositoryIdUtils.addRepositoryId("/", TEST_REPO_ID));
   Document movedDoc2 = getDms().moveDocument(movedDoc.getId(), targetFolder2.getId());

Managing Folders

The following operations on folders are possible:

Retrieving Folders

Folders can be retrieved in different ways:

Retrieving a Folder by ID

To retrieve a folder by ID or path, use the following method:

Folder getFolder(String folderId) throws DocumentManagementServiceException;

Retrieving a Folder by ID controlled by level of detail

In case you like to get a folder by ID or path that is controlled by a given level of details, use:

Folder getFolder(String folderId, int levelOfDetail)
			throws DocumentManagementServiceException;

The levelOfDetail parameter can be one of the following:

The method returns the folder to be retrieved or null, if no folder with such an ID or path exists.

Retrieving multiple folders by ID or path

In case you like to get a list of folders that are controlled by a given level of details, use:

List/*<? extends Folder>*/ getFolders(List/*<String>*/ folderIds, int levelOfDetail) throws DocumentManagementServiceException;

Parameter folderIds should contain a list of IDs or paths identifying the folders to be retrieved. The levelOfDetail parameter can be one of the following:

Retrieving a Folder based on name pattern search

To get folders based on a name pattern search, use the following method:

List/* <? extends Folder> */findFoldersByName(String namePattern,
			int levelOfDetail) throws DocumentManagementServiceException;

Parameter namePattern determines the name pattern to search for. The levelOfDetail parameter can be one of the following:

Retrieving Folders based on XPath query

Use the following method to get a list of folders based on a specific XPath query:

List/*<? extends Folder>*/ findFolders(String xpathQuery, int levelOfDetail) throws DocumentManagementServiceException;

Determine the XPath query via parameter xpathQuery. The levelOfDetail parameter can be one of the following:

Creating a Folder

To create a folder in a specified parent folder, use the following method:

Folder createFolder(String parentFolderId, FolderInfo folder) throws DocumentManagementServiceException;

To describe the folder to be created, use parameter folder as an instance of FolderInfo. Parameter parentFolderId specifies the ID or path of the folder to create the folder in. Value "/" designates the top-level folder.

Note that it is also possible to target a different repository.

Updating a Folder

Use the following method to update a specific folder:

Folder updateFolder(Folder folder) throws DocumentManagementServiceException;

Removing Folders

To delete a folder with a given ID or path, use the following method:

void removeFolder(String folderId, boolean recursive) throws DocumentManagementServiceException;

Parameter recursive determines if the deletion should apply to all children and thus documents and sub-folders in this folder should be removed also (true) or if only the folder itself should be removed (false).

Note that it is also possible to target a folder of a different repository.