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:

  • Field Details

  • 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