com.sap.ecm.api

Class EcmFactory

java.lang.Object

com.sap.ecm.api.EcmFactory

public class EcmFactory
extends Object

This class is a utility class to simplify connecting to the SAP Cloud Platform document service. The Apache Chemistry OpenCMIS library is the client API to the document service. This class adds methods for creating or connecting to a repository. It provides additional parameters and predefined constants that are specific to SAP Cloud Platform.

Connecting to a repository:

uniqueName, key are parameters to be used to access a key secured repository. Repositories can be secured using a name and a secret key. The key provided on creation of the repository must be provided later to connect to the repository. See the SAP Cloud Platform document service Concepts documentation for more details about securing repositories.

destination is a parameter describing the name of a deployed destination in the target system. The destination contains the URL to the document service instance to connect to. See the documentation of the SAP Cloud Platform connectivity service for more details on how destinations can be configured. If no destination is provided a default destination with the correct URL to the Document Service will be used.

user is a parameter that denotes the user id to be forwarded to the document service as originator of the call. If no user is provided the current user is used.

Creating a repository:

options is a parameter that must be provided when a repository is created. Various settings can be set that influence the behavior of the repository including visibility and security. See the RepositoryOptions class for more details.

Constructor Summary

Constructors

Constructor and Description
EcmFactory()

Method Summary

Methods

Modifier and Type	Method and Description
static Session	connect(String uniqueName, String key) Connects to a key-secured repository specified by uniqueName.
static Session	connect(String uniqueName, String key, String destination) Connects to a key-secured repository specified by uniqueName.
static Session	connect(String uniqueName, String key, String destination, Map<String,String> openCmisProperties) Connects to a key-secured repository specified by uniqueName.
static Session	connect(String uniqueName, String key, String destination, Map<String,String> openCmisProperties, List<String> additionalPrincipals) Connects to a key-secured repository specified by uniqueName.
static Session	connectForTenant(String uniqueName, String key, String tenantId, String user) Connects to a key-secured repository specified by uniqueName for the specified tenant and user.
static Session	connectForTenant(String uniqueName, String key, String tenantId, String user, Map<String,String> openCmisProperties) Connects to a key-secured repository specified by uniqueName for the specified tenant and user.
static Session	connectForTenant(String uniqueName, String key, String tenantId, String user, Map<String,String> openCmisProperties, List<String> additionalPrincipals) Connects to a key-secured repository specified by uniqueName for the specified tenant and user.
static Session	connectForUser(String uniqueName, String key, String user) Connects to a key-secured repository specified by uniqueName for the specified user.
static Session	connectForUser(String uniqueName, String key, String destination, String user) Connects to a key-secured repository specified by uniqueName for the specified user.
static Session	connectForUser(String uniqueName, String key, String destination, String user, Map<String,String> openCmisProperties) Connects to a key-secured repository specified by uniqueName for the specified user.
static Session	connectForUser(String uniqueName, String key, String destination, String user, Map<String,String> openCmisProperties, List<String> additionalPrincipals) Connects to a key-secured repository specified by uniqueName for the specified user.
static String	createRepository(RepositoryOptions options) Creates a new repository in the Document Service with the given options.
static String	createRepository(RepositoryOptions options, String destination) Creates a new repository in the Document Service with the given options.
static void	deleteRepository(String uniqueName, String repositoryKey) Deletes a repository for the current consuming account.
static void	deleteRepository(String uniqueName, String repositoryKey, String destination) Deletes a repository for the current consuming account.
static void	forceDeleteRepository(String uniqueName, String repositoryKey) Deletes the tenant repository of the current tenant (consuming account) including all data contained within.
static void	forceDeleteRepositoryForAllTenants(String uniqueName, String repositoryKey) Deletes a repository and all contained tenant repositories including all data inside.
static void	forceDeleteRepositoryForTenant(String uniqueName, String repositoryKey, String tenantId) Deletes the tenant repository of the given tenant ID including all data contained within.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EcmFactory

public EcmFactory()

Method Detail

connect

public static Session connect(String uniqueName,
              String key)
                       throws ServiceException,
                              CmisObjectNotFoundException

Connects to a key-secured repository specified by uniqueName. The key will be used to verify access to this repository. The currently logged in user of your application will be read and forwarded to the document service for use in e.g. createdBy and modifiedBy properties and ACLs.

Parameters:

uniqueName - The unique name of the repository as specified upon creation (see createRepository(RepositoryOptions)).

key - The key that was used to secure the repository as specified upon creation (see createRepository(RepositoryOptions)).

Returns:

An authenticated OpenCMIS session connected to the repository uniqueName in the SAP Cloud Platform document service.

Throws:

CmisObjectNotFoundException - If the requested repository does not exist or the given key does not match

ServiceException - Generic exception that encapsulates root causes

connectForUser

public static Session connectForUser(String uniqueName,
                     String key,
                     String user)
                              throws ServiceException,
                                     CmisObjectNotFoundException

Connects to a key-secured repository specified by uniqueName for the specified user. The key will be used to verify access to this repository.

Parameters:

uniqueName - The unique name of the repository as specified upon creation (see createRepository(RepositoryOptions)).

key - The key that was used to secure the repository as specified upon creation (see createRepository(RepositoryOptions)).

user - User for whom the session should be created. This user will be used for e.g. createdBy and modifiedBy properties and ACLs.

Returns:

An authenticated OpenCMIS session connected to the repository uniqueName in the SAP Cloud Platform document service.

Throws:

CmisObjectNotFoundException - If the requested repository does not exist or the given key does not match

ServiceException - Generic exception that encapsulates root causes

connect

public static Session connect(String uniqueName,
              String key,
              String destination)
                       throws ServiceException,
                              CmisObjectNotFoundException

Connects to a key-secured repository specified by uniqueName. The key will be used to verify access to this repository. The currently logged in user of your application will be read and forwarded to the document service for use in e.g. createdBy and modifiedBy properties and ACLs.

Parameters:

uniqueName - The unique name of the repository as specified upon creation (see createRepository(RepositoryOptions)).

key - The key that was used to secure the repository as specified upon creation (see createRepository(RepositoryOptions)).

destination - Name of the destination to the Document Service server (useful if you want to overwrite the destination to use e.g. a service-user one). Can be null.

Returns:

An authenticated OpenCMIS session connected to the repository uniqueName in the SAP Cloud Platform document service.

Throws:

CmisObjectNotFoundException - If the requested repository does not exist or the given key does not match

ServiceException - Generic exception that encapsulates root causes

connect

public static Session connect(String uniqueName,
              String key,
              String destination,
              Map<String,String> openCmisProperties)
                       throws ServiceException,
                              CmisObjectNotFoundException

Connects to a key-secured repository specified by uniqueName. The key will be used to verify access to this repository. The currently logged in user of your application will be read and forwarded to the document service for use in e.g. createdBy and modifiedBy properties and ACLs. Optionally you can specify properties openCmisProperties that should be passed to the OpenCMIS library. By default, the method internally retries to connect 2 times in case of a connection exception with a sleep of one second between two trials. You could change the number of retries by adding an entry with key "maxRetries" and a value representing a positive integer defining the number of retries to openCmisProperties. To change the sleep duration between two retries add an entry with key "sleepDuration" and a value representing a positive long number defining the sleep duration in milliseconds to openCmisProperties.

Parameters:

uniqueName - The unique name of the repository as specified upon creation (see createRepository(RepositoryOptions)).

key - The key that was used to secure the repository as specified upon creation (see createRepository(RepositoryOptions)).

destination - Name of the destination to the Document Service server (useful if you want to overwrite the destination to use e.g. a service-user one). Can be null.

openCmisProperties - A map that will be passed to the OpenCMIS library. See SessionFactory.createSession(Map) and SessionParameter. Note however that overwriting authentication or connection parameters (like URL, binding, auth provider) will most likely break the connection between your application and the document service.

Returns:

An authenticated OpenCMIS session connected to the repository uniqueName in the SAP Cloud Platform document service.

Throws:

CmisObjectNotFoundException - If the requested repository does not exist or the given key does not match

ServiceException - Generic exception that encapsulates root causes

connect

public static Session connect(String uniqueName,
              String key,
              String destination,
              Map<String,String> openCmisProperties,
              List<String> additionalPrincipals)
                       throws ServiceException,
                              CmisObjectNotFoundException

Connects to a key-secured repository specified by uniqueName. The key will be used to verify access to this repository. The currently logged in user of your application will be read and forwarded to the document service for use in e.g. createdBy and modifiedBy properties and ACLs. Optionally you can specify properties openCmisProperties that should be passed to the OpenCMIS library. You could also provide a list of additional principals additionalPrincipals. The access rights to files and folders with respect to ACLs of these principals are added to the current user rights. By default, the method internally retries to connect 2 times in case of a connection exception with a sleep of one second between two trials. You could change the number of retries by adding an entry with key "maxRetries" and a value representing a positive integer defining the number of retries to openCmisProperties. To change the sleep duration between two retries add an entry with key "sleepDuration" and a value representing a positive long number defining the sleep duration in milliseconds to openCmisProperties.

Parameters:

uniqueName - The unique name of the repository as specified upon creation (see createRepository(RepositoryOptions)).

key - The key that was used to secure the repository as specified upon creation (see createRepository(RepositoryOptions)).

destination - Name of the destination to the Document Service server (useful if you want to overwrite the destination to use e.g. a service-user one). Can be null.

openCmisProperties - A map that will be passed to the OpenCMIS library. See SessionFactory.createSession(Map) and SessionParameter. Note however that overwriting authentication or connection parameters (like URL, binding, auth provider) will most likely break the connection between your application and the document service.

additionalPrincipals - A list of additional principals. The access rights with respect to ACLs to files and folders of these principals are added to the current user rights.

Returns:

An authenticated OpenCMIS session connected to the repository uniqueName in the SAP Cloud Platform document service.

Throws:

CmisObjectNotFoundException - If the requested repository does not exist or the given key does not match

ServiceException - Generic exception that encapsulates root causes

connectForUser

public static Session connectForUser(String uniqueName,
                     String key,
                     String destination,
                     String user)
                              throws ServiceException,
                                     CmisObjectNotFoundException

Connects to a key-secured repository specified by uniqueName for the specified user. The key will be used to verify access to this repository.

Parameters:

uniqueName - The unique name of the repository as specified upon creation (see createRepository(RepositoryOptions)).

key - The key that was used to secure the repository as specified upon creation (see createRepository(RepositoryOptions)).

destination - Name of the destination to the Document Service server (useful if you want to overwrite the destination to use e.g. a service-user one). Can be null.

user - User for whom the session should be created. This user will be used for e.g. createdBy and modifiedBy properties and ACLs.

Returns:

An authenticated OpenCMIS session connected to the repository uniqueName in the SAP Cloud Platform document service.

Throws:

CmisObjectNotFoundException - If the requested repository does not exist or the given key does not match

ServiceException - Generic exception that encapsulates root causes

connectForUser

public static Session connectForUser(String uniqueName,
                     String key,
                     String destination,
                     String user,
                     Map<String,String> openCmisProperties)
                              throws ServiceException,
                                     CmisObjectNotFoundException

Connects to a key-secured repository specified by uniqueName for the specified user. The key will be used to verify access to this repository. By default, the method internally retries to connect 2 times in case of a connection exception with a sleep of one second between two trials. You could change the number of retries by adding an entry with key "maxRetries" and a value representing a positive integer defining the number of retries to openCmisProperties. To change the sleep duration between two retries add an entry with key "sleepDuration" and a value representing a positive long number defining the sleep duration in milliseconds to openCmisProperties.

Parameters:

uniqueName - The unique name of the repository as specified upon creation (see createRepository(RepositoryOptions)).

key - The key that was used to secure the repository as specified upon creation (see createRepository(RepositoryOptions)).

destination - Name of the destination to the Document Service server (useful if you want to overwrite the destination to use e.g. a service-user one). Can be null.

user - User for whom the session should be created. This user will be used for e.g. createdBy and modifiedBy properties and ACLs.

openCmisProperties - A map that will be passed to the OpenCMIS library. See SessionFactory.createSession(Map) and SessionParameter. Note however that overwriting authentication or connection parameters (like URL, binding, auth provider) will most likely break the connection between your application and the document service.

Returns:

An authenticated OpenCMIS session connected to the repository uniqueName in the SAP Cloud Platform document service.

Throws:

CmisObjectNotFoundException - If the requested repository does not exist or the given key does not match

ServiceException - Generic exception that encapsulates root causes

connectForUser

public static Session connectForUser(String uniqueName,
                     String key,
                     String destination,
                     String user,
                     Map<String,String> openCmisProperties,
                     List<String> additionalPrincipals)
                              throws ServiceException,
                                     CmisObjectNotFoundException

Connects to a key-secured repository specified by uniqueName for the specified user. The key will be used to verify access to this repository. Optionally you can specify properties openCmisProperties that should be passed to the OpenCMIS library. You could also provide a list of additional principals additionalPrincipals. The access rights to files and folders with respect to ACLs of these principals are added to the current user rights. By default, the method internally retries to connect 2 times in case of a connection exception with a sleep of one second between two trials. You could change the number of retries by adding an entry with key "maxRetries" and a value representing a positive integer defining the number of retries to openCmisProperties. To change the sleep duration between two retries add an entry with key "sleepDuration" and a value representing a positive long number defining the sleep duration in milliseconds to openCmisProperties.

Parameters:

uniqueName - The unique name of the repository as specified upon creation (see createRepository(RepositoryOptions)).

key - The key that was used to secure the repository as specified upon creation (see createRepository(RepositoryOptions)).

destination - Name of the destination to the Document Service server (useful if you want to overwrite the destination to use e.g. a service-user one). Can be null.

user - User for whom the session should be created. This user will be used for e.g. createdBy and modifiedBy properties and ACLs.

openCmisProperties - A map that will be passed to the OpenCMIS library. See SessionFactory.createSession(Map) and SessionParameter. Note however that overwriting authentication or connection parameters (like URL, binding, auth provider) will most likely break the connection between your application and the document service.

additionalPrincipals - A list of additional principals. The access rights with respect to ACLs to files and folders of these principals are added to the current user rights.

Returns:

An authenticated OpenCMIS session connected to the repository uniqueName in the SAP Cloud Platform document service.

Throws:

CmisObjectNotFoundException - If the requested repository does not exist or the given key does not match

ServiceException - Generic exception that encapsulates root causes

connectForTenant

public static Session connectForTenant(String uniqueName,
                       String key,
                       String tenantId,
                       String user)
                                throws ServiceException,
                                       CmisObjectNotFoundException

Connects to a key-secured repository specified by uniqueName for the specified tenant and user. The key will be used to verify access to this repository. The currently logged in user of your application will be read and forwarded to the document service for use in e.g. createdBy and modifiedBy properties and ACLs.

Parameters:

uniqueName - The unique name of the repository as specified upon creation (see createRepository(RepositoryOptions)).

key - The key that was used to secure the repository as specified upon creation (see createRepository(RepositoryOptions)).

tenantId - The id of the tenant.

user - User for whom the session should be created.

Returns:

An authenticated OpenCMIS session connected to the repository uniqueName in the SAP Cloud Platform document service.

Throws:

CmisObjectNotFoundException - If the requested repository does not exist or the given key does not match

ServiceException - Generic exception that encapsulates root causes

connectForTenant

public static Session connectForTenant(String uniqueName,
                       String key,
                       String tenantId,
                       String user,
                       Map<String,String> openCmisProperties)
                                throws ServiceException,
                                       CmisObjectNotFoundException

Connects to a key-secured repository specified by uniqueName for the specified tenant and user. The key will be used to verify access to this repository. The currently logged in user of your application will be read and forwarded to the document service for use in e.g. createdBy and modifiedBy properties and ACLs. By default, the method internally retries to connect 2 times in case of a connection exception with a sleep of one second between two trials. You could change the number of retries by adding an entry with key "maxRetries" and a value representing a positive integer defining the number of retries to openCmisProperties. To change the sleep duration between two retries add an entry with key "sleepDuration" and a value representing a positive long number defining the sleep duration in milliseconds to openCmisProperties.

Parameters:

uniqueName - The unique name of the repository as specified upon creation (see createRepository(RepositoryOptions)).

key - The key that was used to secure the repository as specified upon creation (see createRepository(RepositoryOptions)).

tenantId - The id of the tenant.

user - User for whom the session should be created.

openCmisProperties - A map that will be passed to the OpenCMIS library. See SessionFactory.createSession(Map) and SessionParameter. Note however that overwriting authentication or connection parameters (like URL, binding, auth provider) will most likely break the connection between your application and the document service.

Returns:

An authenticated OpenCMIS session connected to the repository uniqueName in the SAP Cloud Platform document service.

Throws:

CmisObjectNotFoundException - If the requested repository does not exist or the given key does not match

ServiceException - Generic exception that encapsulates root causes

connectForTenant

public static Session connectForTenant(String uniqueName,
                       String key,
                       String tenantId,
                       String user,
                       Map<String,String> openCmisProperties,
                       List<String> additionalPrincipals)
                                throws ServiceException,
                                       CmisObjectNotFoundException

Connects to a key-secured repository specified by uniqueName for the specified tenant and user. The key will be used to verify access to this repository. The currently logged in user of your application will be read and forwarded to the document service for use in e.g. createdBy and modifiedBy properties and ACLs. Optionally you can specify properties openCmisProperties that should be passed to the OpenCMIS library. You could also provide a list of additional principals additionalPrincipals. The access rights to files and folders with respect to ACLs of these principals are added to the current user rights. By default, the method internally retries to connect 2 times in case of a connection exception with a sleep of one second between two trials. You could change the number of retries by adding an entry with key "maxRetries" and a value representing a positive integer defining the number of retries to openCmisProperties. To change the sleep duration between two retries add an entry with key "sleepDuration" and a value representing a positive long number defining the sleep duration in milliseconds to openCmisProperties.

Parameters:

uniqueName - The unique name of the repository as specified upon creation (see createRepository(RepositoryOptions)).

key - The key that was used to secure the repository as specified upon creation (see createRepository(RepositoryOptions)).

tenantId - The id of the tenant.

user - User for whom the session should be created.

openCmisProperties - A map that will be passed to the OpenCMIS library. See SessionFactory.createSession(Map) and SessionParameter. Note however that overwriting authentication or connection parameters (like URL, binding, auth provider) will most likely break the connection between your application and the document service.

additionalPrincipals - A list of additional principals. The access rights with respect to ACLs to files and folders of these principals are added to the current user rights.

Returns:

An authenticated OpenCMIS session connected to the repository uniqueName in the SAP Cloud Platform document service.

Throws:

CmisObjectNotFoundException - If the requested repository does not exist or the given key does not match

ServiceException - Generic exception that encapsulates root causes

createRepository

public static String createRepository(RepositoryOptions options)
                               throws ServiceException,
                                      RepositoryAlreadyExistsException

Creates a new repository in the Document Service with the given options.

Parameters:

options - Options specifying what kind of repository to create

Returns:

The repository Id of the newly created repository

Throws:

ServiceException - Generic exception that encapsulates root causes

RepositoryAlreadyExistsException - Thrown if the specified repository already exists (e.g. if the given uniqueName is already in use)

createRepository

public static String createRepository(RepositoryOptions options,
                      String destination)
                               throws ServiceException,
                                      RepositoryAlreadyExistsException

Creates a new repository in the Document Service with the given options.

Parameters:

options - Options specifying what kind of repository to create

destination - Name of the destination to the Document Service server (useful if you want to overwrite the destination to use e.g. a service-user one). Can be null.

Returns:

The repository Id of the newly created repository

Throws:

ServiceException - Generic exception that encapsulates root causes

RepositoryAlreadyExistsException - Thrown if the specified repository already exists (e.g. if the given uniqueName is already in use)

deleteRepository

public static void deleteRepository(String uniqueName,
                    String repositoryKey)
                             throws ServiceException,
                                    CmisObjectNotFoundException,
                                    RepositoryNotEmptyException

Deletes a repository for the current consuming account. It can only be deleted if it does not contain any data.

Parameters:

uniqueName - The unique name of the repository

repositoryKey - Authentication key for the repository

Throws:

ServiceException - Generic exception that encapsulates root causes

CmisObjectNotFoundException - Thrown if the specified repository does not exist

RepositoryNotEmptyException - Thrown if the specified repository is not empty

deleteRepository

public static void deleteRepository(String uniqueName,
                    String repositoryKey,
                    String destination)
                             throws ServiceException,
                                    CmisObjectNotFoundException,
                                    RepositoryNotEmptyException

Deletes a repository for the current consuming account. It can only be deleted if it does not contain any data.

Parameters:

uniqueName - The unique name of the repository

repositoryKey - Authentication key for the repository

destination - Name of the destination to the Document Service server (useful if you want to overwrite the destination to use e.g. a service-user one). Can be null.

Throws:

ServiceException - Generic exception that encapsulates root causes

CmisObjectNotFoundException - Thrown if the specified repository does not exist

RepositoryNotEmptyException - Thrown if the specified repository is not empty

forceDeleteRepository

public static void forceDeleteRepository(String uniqueName,
                         String repositoryKey)
                                  throws ServiceException,
                                         CmisObjectNotFoundException

Deletes the tenant repository of the current tenant (consuming account) including all data contained within. This happens even if the repository is not empty and can lead to data loss.

Parameters:

uniqueName - The unique name of the repository to delete the current tenant from

repositoryKey - Authentication key for the repository

Throws:

ServiceException - Generic exception that encapsulates root causes

CmisObjectNotFoundException - Thrown if the specified repository does not exist

forceDeleteRepositoryForTenant

public static void forceDeleteRepositoryForTenant(String uniqueName,
                                  String repositoryKey,
                                  String tenantId)
                                           throws ServiceException,
                                                  CmisObjectNotFoundException

Deletes the tenant repository of the given tenant ID including all data contained within. This happens even if the repository is not empty and can lead to data loss.

Parameters:

uniqueName - The unique name of the repository to delete the specified tenant from

repositoryKey - Authentication key for the repository

tenantId - tenant id of the tenant that is to be deleted from the specified repository

Throws:

ServiceException - Generic exception that encapsulates root causes

CmisObjectNotFoundException - Thrown if the specified repository does not exist

forceDeleteRepositoryForAllTenants

public static void forceDeleteRepositoryForAllTenants(String uniqueName,
                                      String repositoryKey)
                                               throws ServiceException,
                                                      CmisObjectNotFoundException

Deletes a repository and all contained tenant repositories including all data inside. This happens even if the repository is not empty and can lead to data loss.

Parameters:

uniqueName - The unique name of the repository to delete all tenants from

repositoryKey - Authentication key for the repository

Throws:

ServiceException - Generic exception that encapsulates root causes

CmisObjectNotFoundException - Thrown if the specified repository does not exist