Package com.documentum.fc.client

# Interface IDfSessionManager

public interface IDfSessionManager
Manages identities, pooled sessions and transactions.

Interface for all sessions used by Documentum Business Object services. Typically used with `IDfSession`.

Since:
  5.1
See Also:
  - `IDfSession`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ALL_DOCBASES`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `abortTransaction()`
  Rolls back any repository activities on the repository since the transaction was started.
  `void`
  `authenticate(String docbase)`
  Takes the repository name as an argument and throws an exception on bad user credentials.
  `void`
  `beginClientControl()`
  Deprecated.
  No longer needed
  `void`
  `beginTransaction()`
  Starts a new "managed" transaction (repository transaction).
  `void`
  `clearIdentities()`
  Removes all provided identities for all repositories.
  `void`
  `clearIdentity(String docbase)`
  Removes one single identity.
  `void`
  `commitTransaction()`
  Commits all changes to the repositories currently accessed.
  `void`
  `endClientControl()`
  Deprecated.
  No longer needed
  `void`
  `flushSessions()`
  Flushes unused sessions from the session manager's pool.
  `IDfSessionManagerConfig`
  `getConfig()`
  Retrieves a IDfSessionManagerConfig object that contains configuration information pertaining to all sessions managed by this session manager.
  `IDfLoginInfo`
  `getIdentity(String docbase)`
  Retrieves a previously set identity for a given repository.
  `String`
  `getLocale()`
  Returns the locale.
  `String`
  `getPrincipalName()`
  Returns the principal name currently held in this session manager instance.
  `IDfScopeManager`
  `getScopeManager()`
  Returns an IDfScopeManager instance.
  `IDfSession`
  `getSession(String docbase)`
  To get the session handle a service implementation should call the `getSession` method.
  `IDfSessionManagerStatistics`
  `getStatistics()`
  Retrieves a IDfSessionManagerStatistics object that contains diagnostics data.
  `boolean`
  `getTransactionRollbackOnly()`
  Method getTransactionRollbackOnly retrieves the rollback only flag.
  `boolean`
  `hasIdentity(String docbase)`
  Checks whether an identity has been provided previously for a given repository.
  `boolean`
  `isTransactionActive()`
  Checks if a `beginTransaction` has been started.
  `IDfSession`
  `newSession(String docbase)`
  To get a new instance of a DFC session, `newSession` retrieves a new session for the given repository.
  `void`
  `release(IDfSession session)`
  Puts the DFC session object back into the session pool.
  `void`
  `setIdentity(String docbase, IDfLoginInfo identity)`
  Sets the identity for "manual" user authentication.
  `IDfSessionManagerEventListener`
  `setListener(IDfSessionManagerEventListener listener)`
  Sets the event listener.
  `void`
  `setLocale(String locale)`
  Method setLocale sets locale information that will be used for all sessions.
  `void`
  `setPrincipalName(String name)`
  Sets the principal Name.
  `void`
  `setTransactionRollbackOnly()`
  Makes sure the managed transaction will be aborted in any case even if `commitTransaction` method is called outside of the service implementation.

- ## Field Details

  - ### ALL_DOCBASES

    static final String ALL_DOCBASES
    See Also:
      - Constant Field Values

- ## Method Details

  - ### setPrincipalName

    void setPrincipalName(String name)
    Sets the principal Name. For ease of use the principal name is passed and not the principal object itself. This makes it easier to use from other environments such as COM. A principal cannot be defined for a specific repository. Once defined it is valid for all repositories that have principal support enabled. If an identity is defined for a repository, this identity is used instead. Principal support is only used when no manual identity is available.
    Parameters:
      `name` - principal name

  - ### getPrincipalName

    String getPrincipalName()
    Returns the principal name currently held in this session manager instance.
    Returns:
      principal name

  - ### setLocale

    void setLocale(String locale)
    Method setLocale sets locale information that will be used for all sessions.
    Parameters:
      `locale` -

  - ### getLocale

    String getLocale()
    Returns the locale. If client did not set locale before this method returns null.
    Returns:
      locale

  - ### setIdentity

    void setIdentity(String docbase, IDfLoginInfo identity) throws DfServiceException
    Sets the identity for "manual" user authentication. The identity must not already exist in the session manager's idenity list, otherwise an exception is thrown. Use "clearIdentity" first if you want to overwrite in any case.
    Parameters:
      `docbase` - repository name
      `identity` - IDfLoginInfo object set to the user credentials for that repository, like user name and password.
    Throws:
      `DfServiceException` - Identity for this repository is already set.

  - ### getIdentity

    IDfLoginInfo getIdentity(String docbase)
    Retrieves a previously set identity for a given repository.
    Parameters:
      `docbase` - repository name

  - ### hasIdentity

    boolean hasIdentity(String docbase)
    Checks whether an identity has been provided previously for a given repository.
    Parameters:
      `docbase` - repository name

  - ### clearIdentity

    void clearIdentity(String docbase)
    Removes one single identity. This method has no effect if the requested identity is not defined.
    Parameters:
      `docbase` - repository name for identity to be removed

  - ### clearIdentities

    void clearIdentities()
    Removes all provided identities for all repositories.(removes password from memory)

  - ### flushSessions

    void flushSessions()
    Flushes unused sessions from the session manager's pool.

  - ### authenticate

    void authenticate(String docbase) throws DfIdentityException, DfAuthenticationException, DfPrincipalException, DfServiceException
    Takes the repository name as an argument and throws an exception on bad user credentials. No session handle is returned. (The DFC session object is cached)
    Parameters:
      `docbase` - repository name
    Throws:
      `DfIdentityException` - Identity not properly defined
      `DfAuthenticationException` - Bad user credentials
      `DfPrincipalException` - Principal session problem
      `DfServiceException` - Cannot release session

  - ### getSession

    IDfSession getSession(String docbase) throws DfIdentityException, DfAuthenticationException, DfPrincipalException, DfServiceException
    To get the session handle a service implementation should call the `getSession` method. The session can be retrieved as many times as required. When the client is done the session must be released using the `release` method. If an `IDfSession` has not been established for the the specified repository, a new session is automatically created.
    Parameters:
      `docbase` - repository name
    Throws:
      `DfIdentityException` - Identity not properly defined (principal or identity for given repository). getMessage() returns repository name.
      `DfAuthenticationException` - Bad user credentials
      `DfPrincipalException` - Principal session problem
      `DfServiceException` - Cannot release session

  - ### newSession

    IDfSession newSession(String docbase) throws DfIdentityException, DfAuthenticationException, DfPrincipalException, DfServiceException
    To get a new instance of a DFC session, `newSession` retrieves a new session for the given repository. Again, a client is responsible for releasing this session after its use.
    Parameters:
      `docbase` - repository name
    Throws:
      `DfIdentityException` - Identity not properly defined (principal or identity for given repository). getMessage() returns repository name.
      `DfAuthenticationException` - Bad user credentials
      `DfPrincipalException` - Principal session problem
      `DfServiceException` - Cannot release session

  - ### release

    void release(IDfSession session)
    Puts the DFC session object back into the session pool. You should call this method as soon as you are finished with objects in that session.
    Parameters:
      `session` - DFC session object

  - ### beginTransaction

    void beginTransaction() throws DfServiceException
    Starts a new "managed" transaction (repository transaction). There are three scenarios:
    - `beginTransaction` is called but there is no repository session yet. In this case a flag is set and when the first session is retrieved (using `getSession`) the transaction is started.

    - In case of multiple threads, transaction handling operates on the current thread. This means the session manager will manage transactions for each thread separately. For example if there is an existing DFC session for one thread, a new session is created for the second thread automatically.

    - Another special case to be handled is where a first thread gets a session. Then a second thread also gets a session and starts a transaction. In this case it is not possible to start a transaction for the first thread since in may be in the middle of doing something that does not require a transaction.

    Remember, that repository transactions depend on the underlying RDBMS transactions.

    Only sessions obtain after the call to `beginTransaction` method will be able to participate in the transaction. Session objects obtain before `beginTransaction` will not be able to participate in the transaction.

    Nested transactions are not supported. You cannot begin a new transaction using either the `beginTransaction` or `IDfSession.beginTrans` methods once either type of transaction is already started.

    Throws:
      `DfServiceException` - Internal problems

  - ### commitTransaction

    void commitTransaction() throws DfServiceException
    Commits all changes to the repositories currently accessed.

    This commit is ignored (and changed to an `abortTransaction`) if the `setTransactionRollbackOnly` method has been called.

    Throws:
      `DfServiceException` - Internal problems

  - ### abortTransaction

    void abortTransaction() throws DfServiceException
    Rolls back any repository activities on the repository since the transaction was started. Use this method when an unresolvable problem with any activity that would normally require the activities to execute as an atomic operation.
    Throws:
      `DfServiceException` - Internal problems

  - ### isTransactionActive

    boolean isTransactionActive()
    Checks if a `beginTransaction` has been started. This method does not consider DFC unmanaged transactions (`beginTrans`) when determining if a transaction is active. It only applies to managed transactions.
    Returns:
      true if the transaction is still active (false otherwise)

  - ### setTransactionRollbackOnly

    void setTransactionRollbackOnly()
    Makes sure the managed transaction will be aborted in any case even if `commitTransaction` method is called outside of the service implementation. A special case is also when a service implementation decides to abort the transaction but does not want to disturb the flow of the program. Basically this means to abort without throwing an exception.

  - ### getTransactionRollbackOnly

    boolean getTransactionRollbackOnly()
    Method getTransactionRollbackOnly retrieves the rollback only flag.
    Returns:
      true if flag is active (false otherwise)

  - ### beginClientControl

    void beginClientControl()
    Deprecated.
    No longer needed
    Locks the session pool so that the sessions will not revert back to the session pool until the `endClientControl` method is called.

    Session pool locking is required for a scenario where a service returns a number of type based DFC object such as IDfPersistentObject.

    After the processing returns, the client must call the `endClientControl` method to make sure the session pool is working again.

  - ### endClientControl

    void endClientControl() throws DfServiceException
    Deprecated.
    No longer needed
    Unlocks sessions currently locked (`beginClientControl`); must be called in order to allow the session manager to be able to pool the sessions again.
    Throws:
      `DfServiceException` - Internal problems

  - ### getStatistics

    IDfSessionManagerStatistics getStatistics()
    Retrieves a IDfSessionManagerStatistics object that contains diagnostics data. (reference counters, number of session, repositories currently connected)

  - ### getConfig

    IDfSessionManagerConfig getConfig()
    Retrieves a IDfSessionManagerConfig object that contains configuration information pertaining to all sessions managed by this session manager.
    Since:
      6.0

  - ### setListener

    IDfSessionManagerEventListener setListener(IDfSessionManagerEventListener listener)
    Sets the event listener. It allows a client to react to major events in the session manager, like session creation, destroying sessions.
    Parameters:
      `listener` - the new listener
    Returns:
      returns existing listener, null if the listener was not set
    Since:
      5.2

  - ### getScopeManager

    IDfScopeManager getScopeManager()
    Returns an IDfScopeManager instance.
    Since:
      6.5