dm_notes: Documentum Notes

September 5, 2008

UCF Demistified : Client Config : Part 1

Filed under: documentum, ucf — Tags: , , — Raj V @ 9:19 pm

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.

June 26, 2008

Role of UCF in Documentum Clients

Filed under: dfc, notes, ucf, wdk, webtop — Tags: — Raj V @ 10:32 pm

In early days, all Documentum clients were thick clients (either DFC based or DMCL based). This  means it was on a 2-tier architecture. You either need to have a DFC or a DFC based client installed on every client that accesses the Documentum Repository or alternatively use the legacy DMCL library based (IAPI, IDQL) to access the repository .

With the advent of WDK (a web based repository access manager), the thick client is no longer required on the individual clients. This was made possible by moving the Documentum Repository client layer (DFC) to the middle tier ( a 3-tier based architecture) from the traditional Client/Server based 2-tier architecture).

Moving DFC to the middle tier will enable the Application server to access the Repository. But how can the end client access the content in the Repository locally, where there is no footprint of Documentum?

When you perform content management operations, the content is retrieved by DFC on behalf of WDK from the content server and is transferred to the Application server where DFC resides. But how do we transport the content from the App Server to the end client.

To answer this, Documentum has come up with a HTTP based content transfer program that runs with in the context of the Client browser.
This program is a Java based Applet that transfers the content from the App Server to the client (Outbound operations ) and vice-versa (In-bound operations).
But due to the applets limitations to process complex document structures like XML Links/OLE Links etc. this transport mechanism was limited to basic content management functionality.

These limitations have put forward a new robust and extensible transport mechanism called UCF (Unified Client Facilities).

We can enable UCF in WDK based applications( 5.3 or later) through the configuration parameter.

How can you identify which transport facility (http or ucf) is used in your WDK based application?

It is defined in your app.xml file of your application (default entry : wdk\app.xml).
The below config element defines the mode

<contentxfer>
<default-mechanism>ucf</default-mechanism>

</contentxfer>

What is UCF?

UCF is composed of two components (at a very high level). UCF Server and UCF Client.

UCF Server plays two different roles. It presents itself as a end client to the DFC layer that communicates with the Repository and it presents itself as a server to the UCF Client (end client).

The broader communication channel is as below:

Content Server <—> DFC <– –> WDK/UCF Server<—> UCF Client.

What are the benifits of UCF over HTTP transfer mode and why is it being made the de-facto standard in  Documentum based applications (from D6)?

  • Performance and Throughput
    • There is a disbelief that the earlier HTTP based transport is faster than UCF transport. In general any standard http based uploads are better than http based downloads. Not sure why? May be the Server’s is responding more to the clients as most of the users are accessing the application and there are only few users that are trying to write back to the server (upload). (Just a thought)
    • I do agree there have been few performance issues and there have been lot of improvements over the time. It has improved a lot lately.
    • UCF provides client information to the server as and when required, accesses the registry, optimizes the content transfer, etc.. There is a delay involved in launching the UCF client and initializing it compared to the applet based transport. This delay is due to the JVM startup(launch), UCF client making the initial connection to the App Server and protocol negotiation with the server.
  • Extensibility
    • UCF is extensible. You can add your own Requests (Server)/handlers (Client) and plug-in to the UCF Infrastructure and enable it to perform your custom tasks.
  • Recovery
    • UCF has the support for recovery. Say when you are Exporting/Viewing a content file and the socket connection was broken during the transfer, UCF tries to re-try the operation from where it has left and attempts to complete the operation.
  • DFC based analysis for the client
    • As UCF has a small footprint on the client it sends the content file to the server. Then the server analyzes the content and initiates a 2-way communication channel with the client. This communication channel enables the server and client together to perform the Content Analysis.
  • Client information available on the server (for DFC and WDK components)
    • UCF client makes available all the required client information at the Server giving the impression of a client.

None of the above benefits were available with the http based transport implementation or were available with limited support.

Create a free website or blog at WordPress.com.