org.eclipse.stardust.engine.core.spi.dms
Interface IRepositoryService


public interface IRepositoryService

The IRepositoryService provides all functionality for document management operations.

This includes:

Depending on the IRepositoryCapabilities the IRepositoryProvider provides only a subset has to be implemented.
If a method is not implemented an UnsupportedOperationException must be thrown.

Version:
$Revision: 56243 $
Author:
rsauer, roland.stamm

Method Summary
 Document createDocument(String folderId, DocumentInfo document)
          Creates document in a folder described by the document info.
 Document createDocument(String folderId, DocumentInfo document, byte[] content, String encoding)
          Creates document in a folder described by the document info.
 Folder createFolder(String parentFolderId, FolderInfo folder)
          Creates document in a folder described by the document info.
 Documents findDocuments(DocumentQuery query)
          Retrieves all documents satisfying the criteria specified in the provided query.
 Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy> getApplicablePolicies(String resourceId)
          Returns the IAccessControlPolicy objects that can be set for the resource denoted by resourceId.
 Document getDocument(String documentId)
          Gets the document by ID or path.
 List<? extends Document> getDocuments(List<String> documentIds)
          Gets multiple documents by ID or path.
 List<? extends Document> getDocumentVersions(String documentId)
          Gets all versions of the document by document ID (of any of its version).
 Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy> getEffectivePolicies(String resourceId)
          Returns the IAccessControlPolicy objects that currently are in effect on the resource denoted by resourceId (cumulated).
 Folder getFolder(String folderId)
          Retrieves a folder and lists its members.
 Folder getFolder(String folderId, int levelOfDetail)
          Retrieves a folder.
 List<? extends Folder> getFolders(List<String> folderIds, int levelOfDetail)
          Gets multiple folders by ID or path.
 Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy> getPolicies(String resourceId)
          Returns the IAccessControlPolicy objects that are currently set for the resource denoted by resourceId.
 Set<org.eclipse.stardust.engine.api.runtime.Privilege> getPrivileges(String resourceId)
          Returns the privileges the session has for the resource denoted by resourceId, which must exist.
 byte[] getSchemaDefinition(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(String documentId, String targetPath)
          Moves the document to the target path.
 void removeDocument(String documentId)
          Removes document.
 void removeDocumentVersion(String documentId, String documentRevisionId)
          Removes a version of a document.
 void removeFolder(String folderId, boolean recursive)
          Removes folder.
 byte[] retrieveDocumentContent(String documentId)
          Retrieves the content of the document identified by documentId.
 void retrieveDocumentContentStream(String documentId, OutputStream target)
          Retrieves an OutputStream for the document.
 void setPolicy(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)
 Document updateDocument(Document document, boolean createNewRevision, String versionComment, String versionLabel, boolean keepLocked)
          Updates document (except document content).
 Document updateDocument(Document document, byte[] content, String encoding, boolean createNewRevision, String versionComment, String versionLabel, boolean keepLocked)
          Updates document.
 Folder updateFolder(Folder folder)
          Updates folder.
 void uploadDocumentContentStream(String documentId, InputStream source, String contentType, String contentEncoding)
          Allows to set a InputStream for content upload.
 Document versionDocument(String documentId, String versionComment, String versionLabel)
          Creates a new version of the document.
 

Method Detail

getDocument

Document getDocument(String documentId)
                     throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException
Gets the document by ID or path.

Implementation is mandatory.

Parameters:
documentId - the ID or path of the document.
Returns:
the document or null if no document with such ID (or path) exists.
Throws:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

getDocumentVersions

List<? extends Document> getDocumentVersions(String documentId)
                                             throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException
Gets all versions of the document by document ID (of any of its version).

Implementation is needed if IRepositoryCapabilities.isVersioningSupported() is true.

Parameters:
documentId - the ID (any version) or path of the document.
Returns:
list of document versions found.
Throws:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

getDocuments

List<? extends Document> getDocuments(List<String> documentIds)
                                      throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException
Gets multiple documents by ID or path.

Implementation is mandatory.

Parameters:
documentIds - list of document IDs or paths.
Returns:
list of documents found.
Throws:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

retrieveDocumentContent

byte[] retrieveDocumentContent(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. The DmsContentServlet will use retrieveDocumentContentStream(String, OutputStream).

Implementation is mandatory.

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:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors
See Also:
retrieveDocumentContentStream(String, OutputStream)

retrieveDocumentContentStream

void retrieveDocumentContentStream(String documentId,
                                   OutputStream target)
                                   throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException
Retrieves an OutputStream for the document.

Implementation is mandatory.

Parameters:
documentId - The ID or path of the document stream should be retrieved for.
target - The target OutputStream
Throws:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

getFolder

Folder getFolder(String folderId)
                 throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException
Retrieves a folder and lists its members.

Implementation is mandatory.

Parameters:
folderId - The ID or path expression identifying the folder to be retrieved.
Returns:
The resolved folder.
Throws:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors
See Also:
Folder.LOD_LIST_MEMBERS

getFolder

Folder getFolder(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.

Implementation is mandatory.

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:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors
See Also:
Folder.LOD_LIST_MEMBERS

getFolders

List<? extends Folder> getFolders(List<String> folderIds,
                                  int levelOfDetail)
                                  throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException
Gets multiple folders by ID or path.

Implementation is mandatory.

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:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

createDocument

Document createDocument(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.

Implementation is needed if IRepositoryCapabilities.isWriteSupported() is true.

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:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

createDocument

Document createDocument(String folderId,
                        DocumentInfo document,
                        byte[] content,
                        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 retrieveDocumentContentStream(String, OutputStream).

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.

Implementation is needed if IRepositoryCapabilities.isWriteSupported() is true.

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:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

versionDocument

Document versionDocument(String documentId,
                         String versionComment,
                         String versionLabel)
                         throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException
Creates a new version of the document.

Implementation is needed if IRepositoryCapabilities.isWriteSupported() and IRepositoryCapabilities.isVersioningSupported() is true.

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:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

removeDocumentVersion

void removeDocumentVersion(String documentId,
                           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.

Implementation is optional if IRepositoryCapabilities.isWriteSupported() and IRepositoryCapabilities.isVersioningSupported() is true.

Parameters:
documentId - ID or path of the document.
documentRevisionId - The revisionId of the document version to be removed.
Throws:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

moveDocument

Document moveDocument(String documentId,
                      String targetPath)
                      throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException
Moves the document to the target path.

Implementation is needed if IRepositoryCapabilities.isWriteSupported() is true.

Parameters:
documentId - The document to be moved.
targetPath - The path to move the document to.
Returns:
The moved Document.
Throws:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

updateDocument

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

Implementation is needed if IRepositoryCapabilities.isWriteSupported() and IRepositoryCapabilities.isVersioningSupported() is true.

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:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

updateDocument

Document updateDocument(Document document,
                        byte[] content,
                        String encoding,
                        boolean createNewRevision,
                        String versionComment,
                        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. The DmsContentServlet will use uploadDocumentContentStream(String, InputStream, String, String).

Implementation is needed if IRepositoryCapabilities.isWriteSupported() and IRepositoryCapabilities.isVersioningSupported() is true.

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:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors
See Also:
uploadDocumentContentStream(String, InputStream, String, String)

uploadDocumentContentStream

void uploadDocumentContentStream(String documentId,
                                 InputStream source,
                                 String contentType,
                                 String contentEncoding)
                                 throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException
Allows to set a InputStream for content upload.

Implementation is mandatory.

Parameters:
documentId - The ID or path of the document stream should be uploaded for.
source - The source InputStream.
Throws:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

removeDocument

void removeDocument(String documentId)
                    throws org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException
Removes document.

Implementation is needed if IRepositoryCapabilities.isWriteSupported() is true.

Parameters:
documentId - ID or path of the document to remove.
Throws:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

createFolder

Folder createFolder(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.

Implementation is needed if IRepositoryCapabilities.isWriteSupported() is true.

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:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

updateFolder

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

Implementation is needed if IRepositoryCapabilities.isWriteSupported() is true.

Parameters:
folder - folder to be updated.
Returns:
the updated folder.
Throws:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

removeFolder

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

Implementation is needed if IRepositoryCapabilities.isWriteSupported() is true.

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:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - on DMS specific errors

getPrivileges

Set<org.eclipse.stardust.engine.api.runtime.Privilege> getPrivileges(String resourceId)
Returns the privileges the session has for the resource denoted by resourceId, which must exist.

Implementation is needed if IRepositoryCapabilities.isAccessControlPolicySupported() is true.

Parameters:
resourceId - absolute path or ID of a file or folder
Returns:
the privileges of the given resource

getEffectivePolicies

Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy> getEffectivePolicies(String resourceId)
Returns the IAccessControlPolicy objects that currently are in effect on the resource denoted by resourceId (cumulated).

Implementation is needed if IRepositoryCapabilities.isAccessControlPolicySupported() is true. 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:
the effective access control policies of the given resource

getPolicies

Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy> getPolicies(String resourceId)
Returns the IAccessControlPolicy objects that are currently set for the resource denoted by resourceId.

Implementation is needed if IRepositoryCapabilities.isAccessControlPolicySupported() is true. Returned objects can be changed, changes take effect after calling setPolicy()

Parameters:
resourceId - absolute path or ID of a file or folder
Returns:
the access control policies of the given resource

getApplicablePolicies

Set<org.eclipse.stardust.engine.api.runtime.AccessControlPolicy> getApplicablePolicies(String resourceId)
Returns the IAccessControlPolicy objects that can be set for the resource denoted by resourceId.

Implementation is needed if IRepositoryCapabilities.isAccessControlPolicySupported() is true. 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:
the access control policies that are applicable for the given resource

setPolicy

void setPolicy(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)

Implementation is needed if IRepositoryCapabilities.isAccessControlPolicySupported() is true. 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()

Implementation is optional.

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:
org.eclipse.stardust.engine.api.runtime.DocumentManagementServiceException - if there are problems in repository access or the user is not an administrator.

getSchemaDefinition

byte[] getSchemaDefinition(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[].

Implementation is optional.

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

findDocuments

Documents findDocuments(DocumentQuery query)
Retrieves all documents satisfying the criteria specified in the provided query.

Implementation of DocumentQuery.META_DATA is needed if IRepositoryCapabilities.isMetaDataSearchSupported() is true.
Implementation of DocumentQuery.DOC_CONTENT is needed if IRepositoryCapabilities.isFullTextSearchSupported() is true.
Implementation of all other options is optional.

Parameters:
query - the document query.
Returns:
a List of Document objects.


Copyright © 2017 Eclipse Stardust. All Rights Reserved.