Package com.documentum.fc.client

Interface IDfClient

All Known Subinterfaces:
IDfAdminClient
All Known Implementing Classes:
DfClient
public interface IDfClient
This interface provides functionality to establish and manage sessions with a Documentum server, and provides information about the server before a session is established.

The IDfClient interface provides methods for:

  • Constructing session managers.
  • Setting Principal Support mode, when "single login" is required.
  • Querying the connection broker
  • Obtaining a DBOR management object

  • Method Details

    • newSession

      IDfSession newSession(String docbaseName, IDfLoginInfo loginInfo) throws DfException
      Factory method that always constructs a new IDfSession object and establishes a new session with the specified Documentum server.

      Since DFC 5.1, it is recommended that you use IDfSessionManager.newSession(java.lang.String) method instead of this one.

      Note that a DFC session created with this method is not shared. Use getSharedSession(java.lang.String, com.documentum.fc.common.IDfLoginInfo, java.lang.String) to establish a shared session with a server.

      The following code example demonstrates how to obtain an IDfSession interface to a new DFC session:

      Java:
       IDfClient client = DfClient.getLocalClient();
 IDfLoginInfo login = new IDfLoginInfo();
 login.setUser( "username" );
 login.setPassword( "password" );
 login.setDomain( null );
 IDfSession session = client.newSession(docbaseName, login);
      Parameters:
      docbaseName - identifies the repository with which you want to establish a session. Specify the name of the repository in one of the following formats:
      • repository
      • repository.documentum_server_name
      • repository@host_name
      • repository.documentum_server_name@host_name
      where
      • repository is the name or ID of the repository
      • documentum_server_name is the name of the server that you want to use
      • host_name is the name of the machine on which the repository resides

      loginInfo - An IDfLoginInfo object that contains the required user validation information. You can pass in null to use the Windows NT Unified Login.
      Returns:
      an IDfSession interface to the new DFC session.
      Throws:
      DfException - if a server error occurs.
      See Also:

    • getSharedSession

      IDfSession getSharedSession(String docbaseName, IDfLoginInfo loginInfo, String key) throws DfException
      Deprecated.
      use IDfSessionManager instead for session sharing
      This method retrieves an existing shared session if the shared session is created with the same key and the same repository name and login information. If no existing shared session matches the parameters, a new shared session will be created and returned.

      The following code example demonstrates how to obtain an interface to a non-shared session, then obtain an interface to the shared session: 

       IDfClient client = DfClient.getLocalClient();
 IDfLoginInfo li = new IDfLoginInfo();
 li.setUser("tuser");
 li.setPassword("somePass");
 // Here's a brand new session.
 IDfSession sess1 = client.getSharedSession("docbaseName", li, "uniqueKey");
 // Here's a second session shared with sess1.
 IDfSession sess2 = client.getSharedSession("docbaseName", li, "uniqueKey");
      Parameters:
      docbaseName - the repository with which you want to establish a DFC session: Specify the name of the repository in one of the following formats:
      • repository
      • repository.documentum_server_name
      • repository@host_name
      • repository.documentum_server_name@host_name
      where
      • repository is the name or ID of the repository
      • documentum_server_name is the name of the server that you want to use
      • host_name is the name of the machine on which the repository resides
      loginInfo - an IDfLoginInfo interface containing the required user validation information. You may leave this parameter empty if you want to use a unified login. Unified logins are specific to Windows NT.
      key - an application-defined string. Note that for security purposes, there is no DFC method that returns this key. You must remember it if you wish to locate and use the shared session created or returned by this method.
      Returns:
      an IDfSession interface to the new shared DFC session.
      Throws:
      DfException - if a server error occurs.
      See Also:

    • adoptDMCLSession

      IDfSession adoptDMCLSession(String dmclSessionId) throws DfException
      Deprecated.
      session adoption is no longer useful without a separate DMCL
      Returns a DFC session that uses an existing DMCL session ID.

      A DMCL session is a session that is established by a direct call to the DMCL's connect server API, or is obtained from an existing DFC IDfSession object via the method IDfSession.getDMCLSessionId(). The purpose of this function is to allow an application that already has a DMCL session to use DFC. In some cases, application developers may decide to call the DMCL directly when migrating pre-DFC customizations. When possible, however, developers are encouraged to establish sessions through the DFC.

      The following code example demonstrates how to obtain an IDfSession interface by adopting a DMCL session obtained from another DFC session interface: 

       IDfClient client = DfClient.getLocalClient();
 IDfSession sess2 = client.adoptDMCLSession(sess1.getDMCLSessionId());
      Parameters:
      dmclSessionId - the DMCL session ID.
      Returns:
      an IDfSession interface to the DMCL session. Note that you cannot call the IDfSession.disconnect() method on the returned IDfSession interface. Use the disconnect DMCL server API instead.
      Throws:
      DfException - if a server error occurs.
      See Also:

    • unadoptDMCLSession

      void unadoptDMCLSession(String dmclSessionId) throws DfException
      Deprecated.
      session adoption is no longer useful without a separate DMCL
      Releases the DFC session created with the adoptDMCLSession(java.lang.String) method.

      A DMCL session is a session that is established by a direct call to the DMCL's connect server API, rather than through the DFC. Note that this method does not disconnect a DMCL session. Sessions established through the DMCL must also be disconnected through the DMCL with a call to the disconnect server API.

      The following code example demonstrates how to adopt a DMCL session then release the session by unadopting the DMCL session: 

       IDfClient client = DfClient.getLocalClient();
 IDfSession sess2 = client.adoptDMCLSession(sess1.getDMCLSessionId());
 client.unadoptDMCLSession(sess2.getDMCLSessionId());
 if (!sess2.isConnected())
 {
 // This is what we expect...
 }
      Parameters:
      dmclSessionId - the DMCL session ID
      Throws:
      DfException - if a server error occurs
      See Also:

    • enumSharedSessions

      Enumeration enumSharedSessions(String key) throws DfException
      Deprecated.
      use IDfSessionManager instead for session sharing
      Returns an enumeration of all the shared sessions created with a user-specified key.
      Parameters:
      key - an application-defined string that identifies the shared session. Note that there is no DFC method that returns this key. This is the same string you passed to getSharedSession(java.lang.String, com.documentum.fc.common.IDfLoginInfo, java.lang.String).
      Returns:
      an Enumeration object containing all the shared sessions corresponding to the key. Will return an empty enumeration if no session is shared using the key passed.
      Throws:
      DfException - if a server error occurs.
      See Also:

    • findSession

      IDfSession findSession(String sessionId) throws DfException
      Returns an existing DFC session using a DFC session ID. The purpose of this method is in cases where it may be desirable to obtain a second IDfSession instance where both instances share the same underlying session id.

      The following code example demonstrates how to obtain a second IDfSession interface from another IDfSession interface: 

       IDfSession sess2 = client.findSession(sess1.getSessionId());
      Parameters:
      sessionId - the DFC session ID obtained by calling IDfSession.getSessionId()
      Returns:
      an IDfSession interface to the DFC session.
      Throws:
      DfException - if a server error occurs.
      See Also:

    • getClientConfig

      IDfTypedObject getClientConfig() throws DfException
      Returns information about DFC.

      Client configuration information is stored in a client Config object and is intended for use by system administrators. Refer to the EMC Documentum Object Reference Manual for more information on what properties are available through the client object. It is STRONGLY recommended that applications only read the data returned in the typed object, because writes will affect all other Documentum sessions in the process space. If applications do write to the returned object, they are responsible handling all concurrency issues associated with those writes.

      Returns:
      an IDfTypedObject interface to the client configuration information
      Throws:
      DfException - if a server error occurs

    • getDocbaseMap

      IDfDocbaseMap getDocbaseMap() throws DfException
      Returns information about the repositories that are known to a connection broker.

      This method returns an object that contains the repository IDs, repository names, and verbose repository descriptions.

      Throws:
      DfException - if a server error occurs
      See Also:

    • getDocbaseMapEx

      IDfDocbaseMap getDocbaseMapEx(String protocol, String hostName, String portNumber) throws DfException
      Returns information about the repositories that are known to a connection broker. Use this function to specify extended information such as protocol, host name, and port number.

      This method returns repository IDs, repository names, and verbose repository descriptions. The parameters uniquely identify the connection broker that responds to this method. If you do not pass any parameters, the primary connection broker defined in the dmcl.ini file responds. If the primary connection broker is not available, the request is sent to each backup connection broker in turn, until one responds. You will receive error messages for any connection brokers that do not respond. A docbaselocator object contains three attributes that identify which connection broker responded.

      Refer to the EMC Documentum Object Reference Manual for more information about docbase locator objects and list of protocols to communicate with a connection broker. Note that the protocol parameter is null in most cases.

      Parameters:
      protocol - the protocol used to talk to the connection broker (not used in most cases)
      hostName - the host machine on which the connection broker resides
      portNumber - the port number which the connection broker is using for communications
      Returns:
      an IDfDocbaseMap interface to the extended information about the repositories that are known to a connection broker
      Throws:
      DfException - if a server error occurs
      See Also:

    • getDocbrokerMap

      IDfTypedObject getDocbrokerMap() throws DfException
      Returns information about the connection brokers known to the DFC.
      Returns:
      information about the connection brokers known by the DFC
      Throws:
      DfException - if a server error occurs
      See Also:

    • getServerMap

      IDfTypedObject getServerMap(String docbaseName) throws DfException
      Returns information about the servers that are known to a connection broker.
      Parameters:
      docbaseName - the name of the repository associated with the servers for which you are requesting information
      Throws:
      DfException - if a server error occurs
      See Also:

    • getServerMapEx

      IDfTypedObject getServerMapEx(String docbaseName, String protocol, String hostName, String portNumber) throws DfException
      Returns information about the servers known to a connection broker. Use this method to specify extended information such as protocol, host name, and port number.

      The parameters uniquely identify the responding connection broker. If you do not pass any parameters, the primary connection broker defined in the dmcl.ini file responds. If the primary connection broker is not available, the request is sent to each backup connection broker, in turn, until a connection broker responds. You will receive error messages for any connection brokers that do not respond.

      A docbaselocator object contains three attributes that identify which connection broker responded. Refer to the EMC Documentum Object Reference Manual for more information about docbase locator objects.

      Parameters:
      docbaseName - the name of the repository
      protocol - the protocol used to talk to the connection broker
      hostName - the host machine on which the connection broker resides
      portNumber - the port number which the connection broker is using for communications
      Returns:
      an IDfDocbaseMap interface to the extended information about the servers that are known to a connection broker
      Throws:
      DfException - if a server error occurs
      See Also:

    • getDocbaseNameFromId

      String getDocbaseNameFromId(IDfId objectId) throws DfException
      Returns the name of the repository from where the object and its IDfId originated.
      Parameters:
      objectId - an IDfId interface containing an object ID
      Returns:
      a string containing the name of the repository from which the object ID originates
      Throws:
      DfException - if a server error occurs

    • getDocbaseNameFromDocbaseId

      String getDocbaseNameFromDocbaseId(long docbaseId) throws DfException
      Returns the name of the repository with the specified numeric docbase id.
      Parameters:
      docbaseId - the numeric docbase id.
      Returns:
      a string containing the name for the requested id.
      Throws:
      DfException - if a server error occurs or if the docbase name is unknown.

    • getContext

      IDfProperties getContext(String contextId) throws DfException
      Returns the IDfProperties object associated with a particular client.

      IDfProperties objects are non-persistent objects used to store arbitrary information about a client.

      Parameters:
      contextId - an application-defined key to the Properties object; Note that for security purposes, there is no DFC method that returns this key.
      Returns:
      an IDfProperties interface to the client object
      Throws:
      DfException - if the specified IDfProperties object doesn't exist and an attempt to create it fails
      See Also:

    • removeContext

      boolean removeContext(String contextId) throws DfException
      Deletes a IDfProperties object containing client information.

      Property objects are non-persistent objects that store arbitrary information about a client used at runtime.

      Parameters:
      contextId - an application-defined key to the Properties object; Note that for security purposes, there is no DFC method that returns this key.
      Returns:
      TRUE if the Properties object is deleted; FALSE if not.
      Throws:
      DfException - if the method fails
      See Also:

    • newService

      IDfService newService(String name, IDfSessionManager sessionMgr) throws DfServiceException
      Factory method that constructs and instantiates the specified business object service. It returns a new instance of the requested service.

      A service implementation should save this reference so the service can later use its methods to retrieve a concrete DFC session handle.

      The factory method returns a service interface that can then be downcasted to the specific service interface.

      Java:
       IDfClient client = DfClient.getLocalClient();
 IDfSessionManager sMgr = client.newSessionManager();
 String strService = IAutoNumber.class.getName();
 IAutoNumber autonumber = (IAutoNumber)client.newService( strService, sMgr );
 int iNextNumber = autonumber.getUniqueNumber();
      Parameters:
      name - the logical service name. The business objects framework recommends use of the fully qualified interface name of the service interface as a logical service name. This prevents naming conflicts. Example: IAutoNumber.class.getName() might return "com.accelera.autonumber.IAutoNumber" as the fully qualified name.
      sessionMgr - the session handle of type IDfSessionManager.
      Returns:
      a generalized IDfService interface that can be downcasted to the specific service interface.
      Throws:
      DfServiceInstantiationException - Cannot create service due to class loading issues.
      DfServiceException - Cannot create service
      DfDborNotFoundException - Cannot find DBO Registry
      DfServiceNotFoundException - Cannot find service in DBOR
      Since:
      5.1
      See Also:

    • newModule

      IDfModule newModule(String hostingDocbase, String moduleName, IDfSessionManager sessionMgr) throws DfServiceException
      Factory method that constructs and instantiates the specified Module. It returns a new instance of the requested module.
      Parameters:
      hostingDocbase - the repository from
      moduleName - the logical module name. IDfSessionManager.
      sessionMgr - the session handle of type
      Returns:
      a generalized IDfModule interface
      Throws:
      DfServiceException - Cannot create module
      Since:
      5.3

    • newSessionManager

      IDfSessionManager newSessionManager()
      Factory method that constructs a new IDfSessionManager object for managing sessions and transactions with one or more repositories. Since DFC 5.1, using this method instead of newSession is recommended.

      The IDfSessionManager object encapsulates one or more "managed" DFC session objects and dynamically manages the session pool.

      Java:
       IDfClient client = DfClient.getLocalClient();
 IDfSessionManager sMgr = client.newSessionManager();

 IDfLoginInfo login = new DfLoginInfo();
 login.setUser( strUserName );
 login.setPassword( strPassword );
 login.setDomain( null );

 sMgr.setIdentity( strDocbase1, login );
 sMgr.setIdentity( strDocbase2, login );
      Returns:
      a new IDfSessionManager object.
      Since:
      5.1

    • setPrincipalSupport

      void setPrincipalSupport(IDfPrincipalSupport support)
      Changes the session manager mode from "identity" mode to "Principal Support" mode in order to support single sign in. This method allows a client to define a handler that creates sessions on behalf of principal users.

      In order to use principal support, the IDfPrincipalSupport object must be a custom class that implements IDfPrincipalSupport and overrides its IDfPrincipalSupport.getSession(java.lang.String, java.lang.String) method.

      Parameters:
      support - IDfPrincipalSupport
      Since:
      5.1

    • getDbor

      IDfDbor getDbor()
      Deprecated.
      Please use getModuleRegistry() instead
      Factory method that instantiates an IDfDbor business objects registry management object.

      Java:
       IDfDbor dbor = m_client.getDbor();

 IDfDborEntry entry = new DfDborEntry();
 entry.setName( strDocbaseTypeName );
 entry.setServiceBased( bDborService );
 entry.setJavaClass( strJavaClass );// AutoNumberType.class.getName() );
 entry.setVersion( "1.0" );

 dbor.register( entry );
      Returns:
      an instance of an IDfDbor management object.
      Since:
      5.1
      See Also:

    • encryptPassword

      String encryptPassword(String password) throws DfException
      Encrypts a password.
      Parameters:
      password - unencrypted password
      Returns:
      encrypted password
      Throws:
      DfException
      Since:
      5.2

    • getApplicationTokenDiagnostics

      String getApplicationTokenDiagnostics(String applicationToken) throws DfException
      Return details extracted from an applicationToken.
      Parameters:
      applicationToken -
      Throws:
      DfException
      Since:
      6.0

    • getLoginTicketDiagnostics

      String getLoginTicketDiagnostics(String loginTicket) throws DfException
      Return details extracted from a login ticket.
      Parameters:
      loginTicket -
      Throws:
      DfException
      Since:
      6.0
      See Also:

    • initCrypto

      void initCrypto(String keyFile) throws DfException
      Initializes the key store for password encryption.
      Parameters:
      keyFile -
      Throws:
      DfException
      Since:
      5.2

    • initCryptoEx

      void initCryptoEx(String keyFile, String passphrase) throws DfException
      Initializes the key store for password encryption.
      Parameters:
      keyFile -
      passphrase - The passphrase used to encrypt the AEK file.
      Throws:
      DfException
      Since:
      6.0

    • encryptText

      String encryptText(String s1, String s2) throws DfException
      Deprecated.
      This method is not supported.
      Throws:
      DfException

    • decryptText

      String decryptText(String s1, String s2) throws DfException
      Deprecated.
      This method is not supported.
      Throws:
      DfException

    • authenticate

      void authenticate(String docbaseName, IDfLoginInfo loginInfo) throws DfException
      Validates a username/password combination without returning a new session.
      Parameters:
      docbaseName - identifies the repository with which you want to authenticate. Specify the name of the repository in one of the following formats:
      • repository
      • repository.documentum_server_name
      • repository@host_name
      • repository.documentum_server_name@host_name
      where
      • repository is the name or ID of the repository
      • documentum_server_name is the name of the server that you want to use
      • host_name is the name of the machine on which the repository resides

      loginInfo - An IDfLoginInfo object that contains the required user validation information.
      Throws:
      DfException - if a server error occurs.
      Since:
      5.2

    • getModuleRegistry

      IDfGlobalModuleRegistry getModuleRegistry() throws DfException
      Factory method that instantiates an IDfGlobalModuleRegistry global module registry object.
      Throws:
      DfException
      Since:
      5.3

    • newSearchService

      IDfSearchService newSearchService(IDfSessionManager sessionManager)
      Deprecated.
      Replaced by newSearchService(IDfSessionManager, String)
      Factory method to create a new instance of the search service. This instance is itself a factory that can be used to create the different search objects.
      Parameters:
      sessionManager - A session manager to be used for authentication against search sources
      Since:
      5.3

    • newSearchService

      IDfSearchService newSearchService(IDfSessionManager sessionManager, String defaultMetadataDocbase)
      Factory method to create a new instance of the search service.

      This instance is itself a factory that can be used to create the different search objects.

      Parameters:
      sessionManager - A session manager to be used for authentication against search sources
      defaultMetadataDocbase - The default repository to pick the metadata information from (e.g. information on types). This parameter can be safely set to null if the search service is configured to search only on repositories and not on any external source. This parameter must not be null if external sources are selected through the search service. This repository must have a corresponding login information in the session manager.
      Since:
      5.3

    • newRetentionService

      IDfRetentionService newRetentionService()
      Factory method to create a new instance of the retention service.

      This instance can be used to create new retainer objects.

      Since:
      5.3

    • getNetworkLocation

      IDfNetworkLocationEntry getNetworkLocation(String locationId, String locale) throws DfException
      Deprecated.
      use IDfAcsClient.getNetworkLocation()
      Returns an IDfNetworkLocationEntry object by location identifier.
      Parameters:
      locationId - network location identifier
      locale - identifies the locale (currently not supported)
      Returns:
      IDfNetworkLocationEntry client network location object, or null if the location is not found.
      Throws:
      DfException

    • getClientNetworkLocations

      IDfEnumeration getClientNetworkLocations(String clientIPAddress, String locale) throws DfException
      Deprecated.
      use IDfAcsClient.getClientNetworkLocations()
      Returns an IDfEnumeration object that lists all IDfNetworkLocationEntry objects.
      Parameters:
      clientIPAddress - client IP address If this argument is null, all IDfNetworkLocationEntry objects that can be used as a client network location for a given locale are returned.
      locale - identifies the locale (currently not supported)
      Returns:
      IDfEnumeration of IDfNetworkLocationEntry objects
      Throws:
      DfException

    • getAllNetworkLocations

      IDfEnumeration getAllNetworkLocations(String locale) throws DfException
      Deprecated.
      use IDfAcsClient.getAllNetworkLocations()
      Returns an IDfEnumeration object that lists all IDfNetworkLocationEntry objects.
      Parameters:
      locale - identifies the locale (currently not supported)
      Returns:
      IDfEnumeration of IDfNetworkLocationEntry objects
      Throws:
      DfException

    • addUnavailableAcsServer

      void addUnavailableAcsServer(String urlString) throws DfException
      Deprecated.
      use IDfAcsClient.addUnavailableAcsServer()
      Add the specified accelerated content store (ACS) server to the list of unavailable ACS servers.
      Parameters:
      urlString - URL for the unavailable ACS server, expressed as a String
      Throws:
      DfException

    • getTransactionManager

      com.documentum.fc.client.transaction.IDfTransactionManager getTransactionManager()
      Returns the transaction manager.
      Since:
      5.4

    • newOperationManager

      com.documentum.operations.IDfOperationManager newOperationManager() throws DfException
      Returns operation manager.
      Throws:
      DfException

    • getLicenseManager

      com.documentum.fc.client.license.ILicenseManager getLicenseManager() throws DfException
      Throws:
      DfException