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 HANA Cloud 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 HANA Cloud.

  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 HANA Cloud 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 HANA Cloud 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.

    - ### 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.
      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 HANA Cloud 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.
      Returns:
        An authenticated OpenCMIS session connected to the repository `uniqueName` in the SAP HANA Cloud 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.
      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 HANA Cloud 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. Optionally you can specify properties `openCmisProperties` that should be passed to the OpenCMIS library.
      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 HANA Cloud 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. 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.
      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 HANA Cloud 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.
      Returns:
        An authenticated OpenCMIS session connected to the repository `uniqueName` in the SAP HANA Cloud 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.
      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.
        `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 HANA Cloud 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.
      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.
        `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 HANA Cloud 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.
      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 HANA Cloud 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.
      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 HANA Cloud 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. 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.
      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 HANA Cloud 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

Copyright © 2016 SAP. All Rights Reserved.