The Stardust service DocumentManagementService provides functionality for Document Management operations in an Stardust runtime environment.
The following operations on documents are provided via the DocumentManagementService:
To get a specific document or multiple documents, choose the appropriate method depending on which criteria the document search should be performed.
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.
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;
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 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.
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.
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>));
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.
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;
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.
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.
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.
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.
You have the option to update a document without updating its content or including its content by providing a new 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.
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 is possible by ID or Path with the following method:
void removeDocument(String documentId) throws DocumentManagementServiceException;
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.
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.
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.
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());
The following operations on folders are possible:
Folders can be retrieved in different ways:
To retrieve a folder by ID or path, use the following method:
Folder getFolder(String folderId) throws DocumentManagementServiceException;
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:
Folder.LOD_NO_MEMBERSFolder.LOD_LIST_MEMBERSFolder.LOD_LIST_MEMBERS_OF_MEMBERSThe method returns the folder to be retrieved or null,
if no folder with such an ID or path exists.
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:
Folder.LOD_NO_MEMBERSFolder.LOD_LIST_MEMBERSFolder.LOD_LIST_MEMBERS_OF_MEMBERSTo 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:
Folder.LOD_NO_MEMBERSFolder.LOD_LIST_MEMBERSFolder.LOD_LIST_MEMBERS_OF_MEMBERSUse 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:
Folder.LOD_NO_MEMBERSFolder.LOD_LIST_MEMBERSFolder.LOD_LIST_MEMBERS_OF_MEMBERSTo 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.
Use the following method to update a specific folder:
Folder updateFolder(Folder folder) throws DocumentManagementServiceException;
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.