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;
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.
The following methods returns a list of documents based on a given XPath query:
List/*<? extends Document>*/ findDocuments(String xpathQuery) throws DocumentManagementServiceException;
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.
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.
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.
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 path 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.
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:
The 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:
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:
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:
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.
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).
The Stardust QueryService provides functionality to filter for DocumentQuery types, which can be used to search for documents.
For details on filtering Document Types, refer to section Searching for Document Types of chapter Managing Document Types.
To define a filter on the document ID (ID) use the document Id as a predicate in a Document Query.
public static final FilterableAttribute ID = new Attribute("id");
To define a filter on the document name (NAME) use the document name as a predicate in a Document Query.
public static final FilterableAttribute NAME = new Attribute("name");
To define a filter on the document's content type (CONTENT_TYPE) use the document content type as a predicate in a Document Query.
public static final FilterableAttribute CONTENT_TYPE = new Attribute("contentType");
The following example uses the DocumentQuery for finding documents with a specific content type by using the CONTENT_TYPE filter:
private ServiceFactory sf = ServiceFactoryLocator.get("motu", "motu");
private static final String CONTENT_TYPE1 = "text/plain";
public void demoFindByContentType()
{
DocumentQuery query = DocumentQuery.findAll();
query.where(DocumentQuery.CONTENT_TYPE.isEqual(CONTENT_TYPE1));
Documents docs = sf.getQueryService().getAllDocuments(query);
}
To define a filter on the document's content itself (CONTENT) use the document content as a predicate in a Document Query. Note note that only some document types (like plain text, PDF, Microsoft Office documents) support content indexing. Which document types are supported is implied by the concrete Document Management Service.
public static final FilterableAttribute CONTENT = new Attribute("content");
To define a filter on the document's owner (OWNER) use the owner of the document as a predicate in a Document Query.
public static final FilterableAttribute OWNER = new Attribute("owner");
To define a filter on the creation date of the document (DATE_CREATED) use this date as a predicate in a Document Query.
public static final FilterableAttribute DATE_CREATED = new Attribute("dateCreated");
To define a filter on the last modification date of the document (DATE_LAST_MODIFIED) use this date as a predicate in a Document Query.
public static final FilterableAttribute DATE_LAST_MODIFIED = new Attribute(
"dateLastModified");
To define a filter on the meta-data attributes of the document (META_DATA) use the following method:
public static final MetadataFilterBuilder META_DATA = new MetadataFilterBuilder();
This method supports filters on any attribute (e.g. searching if there is any attribute containing a certain text fragment) or specific attributes (e.g. searching if there is an attribute with a given name, containing a certain text fragment).
In the following example, all documents containing any meta-data like a specified string are searched. Hereby the filter META_DATA is used.
private ServiceFactory sf = ServiceFactoryLocator.get("motu", "motu");
private static final String META_VALUE1 = "someMetaString";
public void demoFindMetaDataAnyLike()
{
DocumentQuery query = DocumentQuery.findAll();
query.where(DocumentQuery.META_DATA.any().like(META_VALUE1+"*"));
Documents docs = sf.getQueryService().getAllDocuments(query);
}
In the following example, all documents containing meta-data with an attribute with a given name containing a text like a specified string are searched. Hereby the filter META_DATA is used.
private ServiceFactory sf = ServiceFactoryLocator.get("motu", "motu");
private static final String META_VALUE1 = "someMetaString";
private static final String META_KEY1 = "name";
public void demoFindMetaDataNamedStringLike()
{
DocumentQuery query = DocumentQuery.findAll();
query.where(DocumentQuery.META_DATA.withName(META_KEY1).like(META_VALUE1+"*"));
Documents docs = sf.getQueryService().getAllDocuments(query);
printDocuments(docs);
assertEquals("Documents", 1, docs.size());
}
Use the method findAll() to create a query for finding all documents that currently exist.
public static DocumentQuery findAll()
{
return new DocumentQuery();
}