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. Logging Using classic method invocation, >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. Note: See 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
https://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 Note: If the host is a UNIX machine, you must also ensure that the java.ini file has been property configured and installed before using the method server.

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 Note: It may be necessary to modify the classpath entry in the registry if the Business Object Framework is utilized from the method implementations. Due to the ordering of classloaders BOF implementation classes need to be loaded by the custom classloader defined in DFC. The web application classloader defined by Tomcat interferes with the loading of BOF classes if the BOF classes are loaded into the method server web application.

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.