Package 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 Details

    • EcmFactory

      public EcmFactory()

  • Method Details

    • 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