org.eclipse.stardust.engine.api.runtime
Interface DocumentManagementService

All Superinterfaces:

org.eclipse.stardust.engine.api.runtime.Service

public interface DocumentManagementService
extends org.eclipse.stardust.engine.api.runtime.Service

The DocumentManagementService provides all functionality for DMS operations in a CARNOT runtime environment.

This includes:

• retrieving, adding, updating and deleting documents and folders,
• versioning documents,
• retrieving and updating document content.

Version:

$Revision$

Author:

rsauer

Method Summary

Document	createDocument(java.lang.String folderId, DocumentInfo document) Creates document in a folder described by the document info.
Document	createDocument(java.lang.String folderId, DocumentInfo document, byte[] content, java.lang.String encoding) Creates document in a folder described by the document info.
Folder	createFolder(java.lang.String parentFolderId, FolderInfo folder) Creates document in a folder described by the document info.
java.util.List	findDocuments(java.lang.String xpathQuery) Gets documents based on the XPath query.
java.util.List	findDocumentsByName(java.lang.String namePattern) Gets documents based on the name pattern search.
java.util.List	findFolders(java.lang.String xpathQuery, int levelOfDetail) Gets folders based on the name XPath query.
java.util.List	findFoldersByName(java.lang.String namePattern, int levelOfDetail) Gets folders based on the name pattern search.
java.util.Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy>	getApplicablePolicies(java.lang.String resourceId) Returns the IAccessControlPolicy objects that can be set for the resource denoted by resourceId.
Document	getDocument(java.lang.String documentId) Gets the document by ID or path.
java.util.List	getDocuments(java.util.List documentIds) Gets multiple documents by ID or path.
java.util.List	getDocumentVersions(java.lang.String documentId) Gets all versions of the document by document ID (of any of its version).
java.util.Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy>	getEffectivePolicies(java.lang.String resourceId) Returns the IAccessControlPolicy objects that currently are in effect on the resource denoted by resourceId (cumulated).
Folder	getFolder(java.lang.String folderId) Retrieves a folder and lists its members.
Folder	getFolder(java.lang.String folderId, int levelOfDetail) Retrieves a folder.
java.util.List	getFolders(java.util.List folderIds, int levelOfDetail) Gets multiple folders by ID or path.
java.util.Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy>	getPolicies(java.lang.String resourceId) Returns the IAccessControlPolicy objects that are currently set for the resource denoted by resourceId.
java.util.Set<org.eclipse.stardust.engine.api.runtime.Privilege>	getPrivileges(java.lang.String resourceId) Returns the privileges the session has for the resource denoted by resourceId, which must exist.
byte[]	getSchemaDefinition(java.lang.String schemaLocation) Retrieves the XSD schema for the specified schema location from the Document Repository serialized into a byte[].
RepositoryMigrationReport	migrateRepository(int batchSize, boolean evaluateTotalCount) Migrates resources in the repository.
Document	moveDocument(java.lang.String documentId, java.lang.String targetPath) Moves the document to the target path.
void	removeDocument(java.lang.String documentId) Removes document.
void	removeDocumentVersion(java.lang.String documentId, java.lang.String documentRevisionId) Removes a version of a document.
void	removeFolder(java.lang.String folderId, boolean recursive) Removes folder.
java.lang.String	requestDocumentContentDownload(java.lang.String documentId) Initiates document content download via DmsContentServlet.
java.lang.String	requestDocumentContentUpload(java.lang.String documentId) Initiates document content upload via DmsContentServlet.
byte[]	retrieveDocumentContent(java.lang.String documentId) Retrieves the content of the document identified by documentId.
void	setPolicy(java.lang.String resourceId, org.eclipse.stardust.engine.api.runtime.AccessControlPolicy policy) Binds the policy to the resource denoted by resourceId (overwrites the old version of the policy) If the policy does not contain any IAccessControlEntry then this policy is removed from the resource.
Document	updateDocument(Document document, boolean createNewRevision, java.lang.String versionLabel, boolean keepLocked) Deprecated. since 7.0 use updateDocument(Document, boolean, String, String, boolean)
Document	updateDocument(Document document, boolean createNewRevision, java.lang.String versionComment, java.lang.String versionLabel, boolean keepLocked) Updates document (except document content).
Document	updateDocument(Document document, byte[] content, java.lang.String encoding, boolean createNewRevision, java.lang.String versionLabel, boolean keepLocked) Deprecated. since 7.0 use updateDocument(Document, byte[], String, boolean, String, String, boolean)
Document	updateDocument(Document document, byte[] content, java.lang.String encoding, boolean createNewRevision, java.lang.String versionComment, java.lang.String versionLabel, boolean keepLocked) Updates document.
Folder	updateFolder(Folder folder) Updates folder.
Document	versionDocument(java.lang.String documentId, java.lang.String versionLabel) Deprecated. since 7.0 use versionDocument(String, String, String)
Document	versionDocument(java.lang.String documentId, java.lang.String versionComment, java.lang.String versionLabel) Creates a new version of the document.

Method Detail

getDocument

Document getDocument(java.lang.String documentId)
                     throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Gets the document by ID or path.

Parameters:

documentId - the ID or path of the document.

Returns:

the document or null if no document with such ID (or path) exists.

Throws:

DocumentManagementServiceException - on DMS specific errors

getDocumentVersions

java.util.List getDocumentVersions(java.lang.String documentId)
                                   throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Gets all versions of the document by document ID (of any of its version).

Parameters:

documentId - the ID (any version) or path of the document.

Returns:

list of document versions found.

Throws:

DocumentManagementServiceException - on DMS specific errors

getDocuments

java.util.List getDocuments(java.util.List documentIds)
                            throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Gets multiple documents by ID or path.

Parameters:

documentIds - list of document IDs or paths.

Returns:

list of documents found.

Throws:

DocumentManagementServiceException - on DMS specific errors

findDocumentsByName

java.util.List findDocumentsByName(java.lang.String namePattern)
                                   throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Gets documents based on the name pattern search.

Parameters:

namePattern - the name pattern to search for.

Returns:

list of documents found.

Throws:

DocumentManagementServiceException - on DMS specific errors

findDocuments

java.util.List findDocuments(java.lang.String xpathQuery)
                             throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Gets documents based on the XPath query.

Parameters:

xpathQuery - the XPath query.

Returns:

list of documents found.

Throws:

DocumentManagementServiceException - on DMS specific errors

retrieveDocumentContent

byte[] retrieveDocumentContent(java.lang.String documentId)
                               throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Retrieves the content of the document identified by documentId.

Warning: 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 DmsContentServlet for memory efficient content access.

Parameters:

documentId - The ID or path of the document content should be retrieved for.

Returns:

A byte array containing the document content. This byte array will be encoded according to the document's Document.getEncoding() attribute.

Throws:

DocumentManagementServiceException - on DMS specific errors

See Also:

requestDocumentContentDownload(String)

requestDocumentContentDownload

java.lang.String requestDocumentContentDownload(java.lang.String documentId)
                                                throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Initiates document content download via DmsContentServlet. The returned token should be used as relative URI for the content Servlet and will be valid as long as the session associated with this service is alive.

Parameters:

documentId - The ID or path of the document content should be retrieved for.

Returns:

A download token valid for the lifetime of this service's session.

Throws:

DocumentManagementServiceException - on DMS specific errors

getFolder

Folder getFolder(java.lang.String folderId)
                 throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Retrieves a folder and lists its members.

Parameters:

folderId - The ID or path expression identifying the folder to be retrieved.

Returns:

The resolved folder.

Throws:

DocumentManagementServiceException - on DMS specific errors

See Also:

Folder.LOD_LIST_MEMBERS

getFolder

Folder getFolder(java.lang.String folderId,
                 int levelOfDetail)
                 throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Retrieves a folder. Level of detail of information returned is controlled by levelOfDetail.

Parameters:

folderId - ID or path of the folder.

levelOfDetail - one of Folder.LOD_NO_MEMBERS, Folder.LOD_LIST_MEMBERS or Folder.LOD_LIST_MEMBERS_OF_MEMBERS.

Returns:

the folder or null if no folder with such ID (or path) exists.

Throws:

DocumentManagementServiceException - on DMS specific errors

See Also:

Folder.LOD_LIST_MEMBERS

getFolders

java.util.List getFolders(java.util.List folderIds,
                          int levelOfDetail)
                          throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Gets multiple folders by ID or path.

Parameters:

folderIds - list of IDs or paths.

levelOfDetail - one of Folder.LOD_NO_MEMBERS, Folder.LOD_LIST_MEMBERS or Folder.LOD_LIST_MEMBERS_OF_MEMBERS.

Returns:

list of folders found.

Throws:

DocumentManagementServiceException - on DMS specific errors

findFoldersByName

java.util.List findFoldersByName(java.lang.String namePattern,
                                 int levelOfDetail)
                                 throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Gets folders based on the name pattern search.

Parameters:

namePattern - the name pattern to search for.

levelOfDetail - one of Folder.LOD_NO_MEMBERS, Folder.LOD_LIST_MEMBERS or Folder.LOD_LIST_MEMBERS_OF_MEMBERS.

Returns:

list of folders found.

Throws:

DocumentManagementServiceException - on DMS specific errors

findFolders

java.util.List findFolders(java.lang.String xpathQuery,
                           int levelOfDetail)
                           throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Gets folders based on the name XPath query.

Parameters:

xpathQuery - the XPath query.

levelOfDetail - one of Folder.LOD_NO_MEMBERS, Folder.LOD_LIST_MEMBERS or Folder.LOD_LIST_MEMBERS_OF_MEMBERS.

Returns:

list of folders found.

Throws:

DocumentManagementServiceException - on DMS specific errors

createDocument

Document createDocument(java.lang.String folderId,
                        DocumentInfo document)
                        throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Creates document in a folder described by the document info. The new document will have no content.

Parameters:

folderId - ID or path of the folder to create the document in. Value "/" designates the top-level folder.

document - an instance of DocumentInfo that describs the document.

Returns:

the new document.

Throws:

DocumentManagementServiceException - on DMS specific errors

createDocument

Document createDocument(java.lang.String folderId,
                        DocumentInfo document,
                        byte[] content,
                        java.lang.String encoding)
                        throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Creates document in a folder described by the document info.

For the content an encoding can be specified e.g. (UTF-8, UTF-16). The encoding can take any value and can be used to decode the content byte[] after retrieving it via retrieveDocumentContent(String).

Warning: 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 DmsContentServlet for memory efficient content access.

Parameters:

folderId - ID or path of the folder to create the document in. Value "/" designates the top-level folder

document - an instance of DocumentInfo that describes the document.

content - the content of the new document.

encoding - encoding of the new document content.

Returns:

the new document.

Throws:

DocumentManagementServiceException - on DMS specific errors

See Also:

requestDocumentContentUpload(String)

versionDocument

@Deprecated
Document versionDocument(java.lang.String documentId,
                                    java.lang.String versionLabel)
                         throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Deprecated. since 7.0 use versionDocument(String, String, String)

Creates a new version of the document.

Parameters:

documentId - ID or path of the document to be versioned

versionLabel - label for the new revision. The label must be unique per document.

Returns:

document describing the new document version

Throws:

DocumentManagementServiceException - on DMS specific errors

versionDocument

Document versionDocument(java.lang.String documentId,
                         java.lang.String versionComment,
                         java.lang.String versionLabel)
                         throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Creates a new version of the document.

Parameters:

documentId - ID or path of the document to be versioned

versionComment - comment for the new revision

versionLabel - label for the new revision. The label must be unique per document.

Returns:

document describing the new document version

Throws:

DocumentManagementServiceException - on DMS specific errors

removeDocumentVersion

void removeDocumentVersion(java.lang.String documentId,
                           java.lang.String documentRevisionId)
                           throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Removes a version of a document. At least one version has to remain.
A call to remove the last remaining version leads to a DocumentManagementServiceException.
If the document exists but the documentRevisionId cannot be resolved to a version of the document a DocumentManagementServiceException will be thrown.
An invalid documentId will lead to a DocumentManagementServiceException.

Parameters:

documentId - ID or path of the document.

documentRevisionId - The revisionId of the document version to be removed.

Throws:

DocumentManagementServiceException - on DMS specific errors

moveDocument

Document moveDocument(java.lang.String documentId,
                      java.lang.String targetPath)
                      throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Moves the document to the target path.

Parameters:

documentId - The document to be moved.

targetPath - The path to move the document to.

Returns:

The moved Document.

Throws:

DocumentManagementServiceException - on DMS specific errors

updateDocument

@Deprecated
Document updateDocument(Document document,
                                   boolean createNewRevision,
                                   java.lang.String versionLabel,
                                   boolean keepLocked)
                        throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Deprecated. since 7.0 use updateDocument(Document, boolean, String, String, boolean)

Updates document (except document content).

Parameters:

document - document to update.

createNewRevision - if true, new revision of the document will be created

versionLabel - if createNewRevision is true, the new revision will be labeled with this label. The label must be unique per document.

keepLocked - if true, the document will be kept locked after update.

Returns:

the updated document

Throws:

DocumentManagementServiceException - on DMS specific errors

updateDocument

Document updateDocument(Document document,
                        boolean createNewRevision,
                        java.lang.String versionComment,
                        java.lang.String versionLabel,
                        boolean keepLocked)
                        throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Updates document (except document content).

Parameters:

document - document to update.

createNewRevision - if true, new revision of the document will be created

versionComment - can be specified to comment the version operation.

versionLabel - if createNewRevision is true, the new revision will be labeled with this label. The label must be unique per document.

keepLocked - if true, the document will be kept locked after update.

Returns:

the updated document

Throws:

DocumentManagementServiceException - on DMS specific errors

updateDocument

@Deprecated
Document updateDocument(Document document,
                                   byte[] content,
                                   java.lang.String encoding,
                                   boolean createNewRevision,
                                   java.lang.String versionLabel,
                                   boolean keepLocked)
                        throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Deprecated. since 7.0 use updateDocument(Document, byte[], String, boolean, String, String, boolean)

Updates document.

Warning: 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 DmsContentServlet for memory efficient content access.

Parameters:

document - document to update.

content - new document content.

encoding - encoding of the new document content.

createNewRevision - if true, new revision of the document will be created

versionLabel - if createNewRevision is true, the new revision will be labeled with this label. The label must be unique per document.

keepLocked - if true, the document will be kept locked after update.

Returns:

the updated document

Throws:

DocumentManagementServiceException - on DMS specific errors

See Also:

requestDocumentContentUpload(String)

updateDocument

Document updateDocument(Document document,
                        byte[] content,
                        java.lang.String encoding,
                        boolean createNewRevision,
                        java.lang.String versionComment,
                        java.lang.String versionLabel,
                        boolean keepLocked)
                        throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Updates document.

Warning: 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 DmsContentServlet for memory efficient content access.

Parameters:

document - document to update.

content - new document content.

encoding - encoding of the new document content.

createNewRevision - if true, new revision of the document will be created

versionComment - can be specified to comment the version operation.

versionLabel - if createNewRevision is true, the new revision will be labeled with this label. The label must be unique per document.

keepLocked - if true, the document will be kept locked after update.

Returns:

the updated document

Throws:

DocumentManagementServiceException - on DMS specific errors

See Also:

requestDocumentContentUpload(String)

requestDocumentContentUpload

java.lang.String requestDocumentContentUpload(java.lang.String documentId)
                                              throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Initiates document content upload via DmsContentServlet. The returned token should be used as relative URI for the content Servlet and will be valid as long as the session associated with this service is alive.

Parameters:

documentId - The ID/path of the document content should be retrieved for.

Returns:

An upload token valid for the lifetime of this service's session.

Throws:

DocumentManagementServiceException - on DMS specific errors

removeDocument

void removeDocument(java.lang.String documentId)
                    throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Removes document.

Parameters:

documentId - ID or path of the document to remove.

Throws:

DocumentManagementServiceException - on DMS specific errors

createFolder

Folder createFolder(java.lang.String parentFolderId,
                    FolderInfo folder)
                    throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Creates document in a folder described by the document info. The new document will have no content.

Parameters:

parentFolderId - ID or path of the folder to create the folder in. Value "/" designates the top-level folder.

folder - an instance of FolderInfo that describs the folder.

Returns:

the new folder.

Throws:

DocumentManagementServiceException - on DMS specific errors

updateFolder

Folder updateFolder(Folder folder)
                    throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Updates folder.

Parameters:

folder - folder to be updated.

Returns:

the updated folder.

Throws:

DocumentManagementServiceException - on DMS specific errors

removeFolder

void removeFolder(java.lang.String folderId,
                  boolean recursive)
                  throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Removes folder.

Parameters:

folderId - ID or path of the folder to remove.

recursive - if true, documents and subfolders will be removed also (applies to all the children). If false, only the folder itself will be removed.

Throws:

DocumentManagementServiceException - on DMS specific errors

getPrivileges

java.util.Set<org.eclipse.stardust.engine.api.runtime.Privilege> getPrivileges(java.lang.String resourceId)

Returns the privileges the session has for the resource denoted by resourceId, which must exist.

Parameters:

resourceId - absolute path or ID of a file or folder

Returns:

getEffectivePolicies

java.util.Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy> getEffectivePolicies(java.lang.String resourceId)

Returns the IAccessControlPolicy objects that currently are in effect on the resource denoted by resourceId (cumulated). Returned objects can not be modified, they represent a read-only view of effective policies.

Parameters:

resourceId - absolute path or ID of a file or folder

Returns:

getPolicies

java.util.Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy> getPolicies(java.lang.String resourceId)

Returns the IAccessControlPolicy objects that are currently set for the resource denoted by resourceId. Returned objects can be changed, changes take effect after calling setPolicy()

Parameters:

resourceId - absolute path or ID of a file or folder

Returns:

getApplicablePolicies

java.util.Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy> getApplicablePolicies(java.lang.String resourceId)

Returns the IAccessControlPolicy objects that can be set for the resource denoted by resourceId. Returned objects can be changed, and used as arguments to setPolicy() in order to add a new policy.

Parameters:

resourceId - absolute path or ID of a file or folder

Returns:

setPolicy

void setPolicy(java.lang.String resourceId,
               org.eclipse.stardust.engine.api.runtime.AccessControlPolicy policy)

Binds the policy to the resource denoted by resourceId (overwrites the old version of the policy) If the policy does not contain any IAccessControlEntry then this policy is removed from the resource. If the policy was obtained using getApplicablePolicies(), the policy will be added, if it was obtained using getPolicies(), the policy will replace its old version.

Parameters:

resourceId - absolute path or ID of a file or folder

policy -

migrateRepository

RepositoryMigrationReport migrateRepository(int batchSize,
                                            boolean evaluateTotalCount)
                                            throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException

Migrates resources in the repository. This migration process works sequential from the current version to the next higher version. The count of resources migrated in one execution is limited by the parameter batchSize.
Subsequent calls will migrate further resources if there are resources for migration available. After all resources for the migration from one version to the next are processed subsequent calls will start the migration to the next higher repository structure version.
The migration is complete when the two current version (vfs internal and engine structure) reach the respective target version.

Important Note Please ensure there is no other write access on the repository to avoid race conditions! Since there is no locking mechanism this should be run in read-only maintenance window!

The MigrationReport returned by each call contains information about: Total resources that need migration to the next version, resources already migrated, current version, next version and target version of the repository structure.

There are two different versions, internal versions are migrated first.
The vfs internal version called repositoryVersion. RepositoryMigrationReport.getTargetRepositoryVersion()
The engine's structure version called repositoryStructureVersion. RepositoryMigrationReport.getTargetRepositoryStructureVersion()

Parameters:

batchSize - count of resources to be migrated in this call. A value of 0 will return a MigrationReport without migrating.

evaluateTotalCount - if set to true the total count of resources that need processing in this migration step is evaluated. Setting this parameter to false saves performance.

Returns:

a report containing information about the migration batch execution.

Throws:

DocumentManagementServiceException - if there are problems in repository access or the user is not an administrator.

getSchemaDefinition

byte[] getSchemaDefinition(java.lang.String schemaLocation)
                           throws org.eclipse.stardust.common.error.ObjectNotFoundException

Retrieves the XSD schema for the specified schema location from the Document Repository serialized into a byte[].

Parameters:

schemaLocation - the document type's schema location

Returns:

XSD schema of this document type

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if the specified schema location cannot be found