UCF Demistified : Client Config : Part 1

UCF is the de facto standard for Transferring the Content from Documentum repository to the end client across its application clients (applications that doesn’t have any DFC footprint on the client).
UCF is composed of 2 parts: a Client and a Server.  UCF extensively uses configuration files for various aspects.

UCF configuration files exist at two layers. One on the server – App Server (ucf.server.config.xml file) and the other on the Client (ucf.client.config.xml file).

The rest of the article looks at the configuration files applicable to the client layer.

A configuration file defines how UCF is launched on the client.
On the client, UCF has few configuration files that defines how it is launched.

Each of the below configuration file is used for a definite purpose. The purpose of each file is detailed below:

• ucf.launcher.config.xml: This is the file that specifies where UCF should look for files (like libraries, configuration files etc.). This file has the configuration parameter that specifies the UCF home directory (“installs.home”). This directory is used by the UCF launcher to look for the files it requires for launching the UCF client process. During UCF installation this is the first files that gets created.

• ucf.installs.config.xml:
  This is the main configuration file that the UCF launcher uses to launch the UCF Java process (on the client). This file defines the UCF Runtime environment on the client.
  • <ucfInstall> element followed by its attributes define where the UCF libraries can be found and how to use it.
    • appId: defaulted to ‘shared’. This specifies that the UCF application libraries are shared across multiple applications (all UCF based consumers) for the same version of UCF client.
    • version: This defines which version of UCF client library should be used for launching the UCF client process. This is the UCF’s version number your application is bundled with. If you have multiple versions of UCF on you client machine, the version specified here used for launching UCF.
      This version follows a standard as other Documentum applications do :
      Format <major>.<minor>.<maintenance  no>.<build no.> ex.: 5.3.0.417 ==> 5.3 SP4 build.
    • host: The host for which these UCF libraries were installed. If your %USERPROFILE% directory is the same from any host in your corporate network, each host from which you access UCF will have a separate UCF libraries directory. Your host UCF client process would pick up the UCF libraries only from the directory that match with the current host.
    • home: UCF home directory, this is the directory where all the UCF related libraries and configuration files are found. This attribute value is the same as defined in the ucf.launcher.config.xml file.

    This ucfInstall element defines the location of the UCF library files, configuration files and the intermediate temp directory.

  • <java> element (under ucfInstall element) and its enclosed elements define the runtime environment the UCF client process uses. The attributes of this element are detailed below:
    • version: The version of JRE being used by the UCF client. This is the version that is found by UCF installer on your host machine found to be suitable for launching the UCF process.
    • minVersion: The minimum Java version the current UCF build requires to launch the client successfully. If this minimum java version is not met, UCF downloads its private JRE and uses it. if your version is higher than the minVersion, no private JRE is downloaded.
    • exePath: The path to the javaw executable that is used for launching the UCF process.
      Hack: If I want to force the UCF to be launched by a different version of java (like JDK 1.6.0 instead of JDK 1.4.2), I can modify this path to point to my JRE. Beware that EMC doesn’t support these hacks and versions it doesn’t support.
    • classpath: This is the classpath used by the UCF client to launch the UCF process. The only additional libraries available to UCF during the launch are only the bootstrap jars of the JRE.
      If you take close look at this classpath entry, it followes a pre-defined format:
      • <installs.home>/<host>/<appId>/<bin>/<version>/*.jar
        (Pre 5.3 SP3 UCF versions doesn’t have the version directory)
        This is for this reason the ucfInstall element has defined these attributes.
  • <option> elements. These are the VM arguments that are passed to UCF process during the launch time.
    • The default options the installer specifies are:
      • java.library.path : This is the directory where the UCFWin32JNI.dll is found (on Windows). This dll file provides the support to access Windows Registry for tracking the User operations on the client (Checked out documents, Viewed documents, Linked documents also called “InlinedDocuments”, Housekeeping parameters etc. When ever a document is transferred to the client (accessed using UCF), its tracked in the registry.
      • java.util.logging.config.class: This is the standard Java.util.logging parameter (defined by JDK) that defines the Logger class to be used for logging UCF calls. You can plug-in your own logger instead of the default Logger, in case you have additional requirements for logging.
        Note: One pitfall I see in using java.util.logging.Logger is it doesn’t record the granularity of timing at milliseconds unlike Log4J (Bug# 6285131).
        Custom loggers however are not supported by EMC.  (Only for detailing purpose they are hinted here)
      • user.home: The Java’s user.home system variable. This would be the default directory where your documents would be checked out, Viewed or Exported to. The documents location can however be defaulted to a different location by specifying them in the “ucf.client.config.xml” file (more on this later).
      • Any additional VM arguments that needs to be passed can be added to this file here.
        Like minimum/maximum Heap memory; Debugging parameters or JMX listeners etc.

UCF Launcher : UCF Launcher used by WDK applications launch the UCF process in a shared mode. This means the launched UCF client process can be shared across multiple content transfer invocations. Having it shared means the UCF client process lingers around for some period  after the current operation (this is configurable again; details to follow later) waiting for further requests from UCF server.

Note: The above statements detailed in this article are neither supported nor suggested by EMC. Its purely my own understanding of the UCF component. Please use this information at your own discretion.
Neither me nor EMC would provide the support/take the responsibility, if the default installation is altered.