fbpx

The Documentum Java Method Server

Introduction

Methods

Documentum methods enable custom code to run on behalf of the Content Server.
Methods may execute any program launchable on the operating system of the Content
Server but they are typically implemented in docbasic or Java. There are four
main reasons to be interested in methods:

  1. Methods execute on the server and are therefore client independant. This
    is useful if there is behavior that is shared across multiple client platforms
  2. Methods may execute with super-user privileges which makes them appropriate
    for system-level tasks that a regular user may need to invoke but would not
    have normally have permission to perform.
  3. There are sometimes operations that are not appropriate to execute on the client.
    Methods may be configured to run asynchronously and are an excellent choice for
    long-running, background processing.
  4. There is some Documentum functionality (such as custom workflow activities) that must
    be implemented as methods.

For more information on methods, read Michael Trafton’s article on methods.

The problem with methods

Prior to the introduction of the Java method server as part of the Documentum 5 platform,
Java-based methods were expensive to execute. As each method launched a separate
process, every method invocation was burdened with the overhead of creating and
destroying a process.

For native applications, this overhead is relatively minor but
for Java applications, each method invocation involved the loading of a Java virtual machine,
loading the classes necessary to execute the method, and then unloading the Java virtual
machine. On most platforms, the overhead could result in method calls that took
seconds to execute rather than milliseconds. When this occurs for every automatic
task in a workflow that is being used by hundreds of users, there is suddenly a significant
performance and scalability problem.

Introducing the Java method server

The Documentum 5 platform introduced the Java method server as a means of improving
the performance and scalability of the Documentum method architecture. In the
past couple of years, Documentum has focused on Java as a cornerstone for its
technology. Documentum clients are being written in Java
more and more frequently. The core Documentum libraries are implemented in Java.
Running Java-based methods, however, has been the most painful of experiences.
The Java method server aims to fix this.

The method server runs as a process distinct from the Content Server and is responsible
for the invocation of the individual methods. Each method invocation results in
a call to the method server which manages the actual execution of the Java-based method
implementation. As the method server is a continuously running process, there is no overhead
involved in loading and tearing-down a Java virtual machine with each invocation.
This yields an enormous benefit in overhead.

As methods are typically executed over
and over again, the classes involved in the implementation of the method only need
be loaded once. Other overhead, such as the creation of docbase sessions may also
be reduced as the method server may reuse sessions with connection pooling. The
result is methods that execute in milliseconds instead of seconds and which use
significantly fewer system resources.

How does the method server work

It’s a web application

The method server itself is a Java-based web application. It communicates with
the Content Server via HTTP calls. Each time a method is invoked, the Content
Server makes an HTTP request passing the name of the Java class which implements
the method along with any specified arguments to a servlet which knows how to
execute the specified method.

Methods in documentum are defined via >dm_method objects. To indicate
that a Java method should execute via the Java method server, set the
>dm_method.method_type attribute to >java, the
>dm_method.use_method_server attribute to >1, and the
>dm_method.method_verb attribute to the classname of the method implemenation.
When the Content Server sees a method matching this pattern, it opens a HTTP
request to the Java method server requesting executing of the method with the
specified class.

This simple architecture solves the overhead problem and also introduces a
convenient mechanism for dramatically improving the scalability of the Content
Server. Although it is not configured out-of-the-box to support this, Method
servers may be executed on a machine physically separate from the Content Server.
It is even possible to run the method server on a platform different from the
Content Server (ie. running the Content Server on Solaris and the method server
on Windows). This offloads work from the Content Server which might enable
the Content Server to handle more users.

If the methods are expensive to execute, it is also possible to load-balance
method servers using industry standard HTTP load balancers. There is nothing
special or complicated about the method server. It simply requires a J2EE-compatible
servlet container

Note:

The method server is supported on Tomcat. It is very likely that it will
operate correctly on any J2EE servlet container such as BEA Weblogic, Jetty,
Websphere, etc. but the author has not tried any alternate servlet-container configurations.
Documentum doesn’t currently support these configurations (as of August 2004)
but plans to in future releases.

Implementing method server aware methods

The IDmMethod interface

The >IDmMethod interface is the interface that a method must implement to be
invoked via the method server. This interface is located in the method
server JAR file (mthdservlet.jar) which is found on the Content Server.
package com.documentum.mthdservlet;
import java.io.OutputStream;
import java.util.Map;

/**
* Interface for Java Methods that are invoked by the
* Documentum Content Server.
*/
public interface IDmMethod
{
/**
* Serves as the entry point to a Java method (installed in Tomcat) executed by
* the Content Server DO_METHOD apply method.
*
* @param parameters A Map containing parameter names as keys and parameter values
* as map values.The keys in the parameter are of type String.
* The values in the parameter map are of type String array.
* (This map corresponds to the string ARGUMENTS passed by the
* DO_METHOD apply call.)
*
* @param output OutputStream to be sent back as the HTTP response content,
* to be saved in the docbase if SAVE_RESULTS was set to TRUE
* in the DO_METHOD apply call.
* NOTE: This output stream is NULL if the DO_METHOD was
* launched asynchronously. Always check for a null
* before writing to the OutputStream.
*/
public void execute(Map parameters, OutputStream output) throws Exception;
}

The >IDmMethod interface has a single method >execute
which operates very similarly to the >main method in traditional
Java-based method implementations. The >parameters argument
is a
Map
containing the method parameters
(Strings)
keyed by their names
(Strings).

For example, workflow methods take five method parameters:

  1. "user" --> The username to run the method as
  2. "docbase_name" --> The name of the docbase to run the method against
  3. "packageId" --> The workitemId (yes, it is called packageId even though it is for
    a workitemId)
  4. "ticket" --> The ticket to use to log onto the docbase
  5. “mode” –> Just ignore this

For a classic workflow method implementation, these would have been passed
in ten arguments to >main.

  • args[0] = “user”
  • args[1] = “the_user_name”
  • args[2] = “docbase_name”
  • args[3] = “the_docbase_name”
  • args[4] = “packageId”
  • args[5] = “the_workitemId”
  • args[6] = “ticket”
  • args[7] = “the_ticket”
  • args[8] = “mode”
  • args[9] = “the_mode”
  • Note:

    The classic method implementation and the one for the method server are similar
    enough that its a relatively trivial task to write an abstract base method
    implementation that enables a workflow implementation to work with both
    the classic mechanism as well as the method server. The author has found this
    useful.

    The >output parameter is used for returning information if
    >SAVE_RESPONSE is set to >true for the method invocation.
    For asynchronous methods, this output stream will always be null. The usage of
    this feature is outside the scope of this article. stdout was written into the server
    log. With the method server, logs are written to a method-server specific location.
    Logging the invocation will still be captured in the server log when the
    dm_method.trace_launch attribute is set to >true
    but >System.out is logged to the location specified by the servlet container.

    For the default installation of the method server on the Content Server, this
    location is >%DM_HOME%tomcatlogsstdout.log

    log4j

    DFC logging and tracing is controlled via the >log4j.properties
    file located in %DOCUMENTUM%configlog4j.properties on the
    Content Server. Configuring this file is out of the scope of this article
    but documentation is available from the log4j home page

    Deploying method implementations to the method server

    To deploy methods to the method server, simply copy the class files or JAR
    files to the >%DOCUMENTUM%dbajava_methods directory on the Content Server.
    The method server will include them in its classpath. Whenever classes are deployed to the
    method server, the method server will need to be restarted. All classes on which
    the method implementations depend must also be deployed to the method server.Method server registry keys below.

    If the log4j.properties are configured appropriately, the method server will log
    the classpath it is using (including jar files deployed as described above)
    20:01:11,967 INFO [main] com.documentum.mthdservlet.MethodConfig -
    Docbase Names = my_docbase
    20:01:11,967 INFO [main] com.documentum.mthdservlet.MethodConfig -
    Host Names = my_host
    20:01:11,967 INFO [main] com.documentum.mthdservlet.MethodConfig -
    IP Addresses = 192.168.64.139, 127.0.0.1
    20:01:11,967 INFO [main] com.documentum.mthdservlet.MethodConfig
    - Java Method Dir = D:Documentumdbajava_methods
    20:01:11,967 INFO [main] com.documentum.mthdservlet
    .MethodConfig - DoMethod CLASSPATH=%CLASSPATH%;
    D:Documentumdbajava_methods

    Configuring the Method Server

    Updating dm_server_config for debugging

    The >dm_server_config object in the repository defines which URI is requested
    to invoke the method server. This URI is managed via the >app_server_name[]
    attribute and the >app_server_uri[] attribute. The two attributes are
    correlated. The method server URI is the entry whose >app_server_name is
    do_method. By default, theapp_server_uri is
    http://localhost:9080/DmMethods/servlet/DoMethod.

    For development docbases, updating the URI to reference a web application running
    on the developer’s machine is often useful for debugging. Some energy is required
    to set up a method server on the developer’s machine but that effort usually pays
    off quickly when debugging complex method code.

    Disabling the Method Server

    The method server is installed and enabled automatically when you install Content
    Server. To disable the method server, set >method_server_enabled = F
    in the server.ini file. To re-enable the method server, set the value to >T Method server registry keys

    On the Windows platform, the Java method server is installed as a service.
    Although it is an instance of Tomcat, the server isn’t launched via the
    familiar >catalina.bat file. Rather, the >tomcat.exe
    located in >C:Program FilesDocumentumtomcat4.0.6bintomcat.exe

    is executed. It loads its arguments from the registry in parameters specified
    in the following location in the registry:
    HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesDmJavaMethodServerParameters Problems

    Most problems related to the method server are the result of classpath problems.
    Typically, this is the result of failing to include a dependant class on the
    method server’s classpath. >NoClassDefFound errors are typically displayed
    in the method server log.

    Note:

    Beware classes referenced statically (often in static initializers) as the class
    referenced in the >NoClassDefFound may not actually be the
    class that isn’t found. It may, instead, be a class that the logged class initializes
    statically.

    Classpath problems which are a result of the custom BOF classloader are a bear
    to work around. BOF doesn’t work ideally in an servlet container where there are
    multiple classloaders. BOF classes need to be loaded by the same class loader as
    DFC which is usually the root classloader in standard Documentum installations.

    Note:

    The author has found that the best way to deploy BOF functionality is to build
    a JAR file of just the BOF classes and to reference that JAR file (and any dependant
    JAR files) in the servlet container’s root classpath (where DFC is referenced).
    For the default installation of the method server on Windows, this is specified in the
    registry key described above.

    Like this article?

    Share on facebook
    Share on Facebook
    Share on twitter
    Share on Twitter
    Share on linkedin
    Share on Linkdin
    Share on pinterest
    Share on Pinterest

    Leave a comment

    © 2019 Blue Fish, All Rights Reserved.

    Powered by Groundwork.