Understanding the Java Method Server in Documentum

Introduction to Documentum Methods

Documentum methods are a powerful feature within the Content Server environment, enabling the execution of custom code directly on the server. These methods, typically written in Docbasic or Java, offer a way to extend Documentum’s functionality beyond its out-of-the-box capabilities. There are several key advantages to utilizing methods in Documentum:

• Server-Side Execution: Methods operate on the server, ensuring client independence. This is invaluable for consistent behavior across diverse client platforms.
• Elevated Privileges: Methods can run with super-user permissions, making them ideal for system-level tasks that require elevated access beyond standard user permissions.
• Background Processing: Methods can be configured for asynchronous execution, making them perfect for long-running, background tasks without impacting client responsiveness.
• Essential for Custom Functionality: Certain Documentum features, like custom workflow activities, rely on methods for their implementation.

To delve deeper into Documentum methods, Michael Trafton’s insightful article on methods provides a comprehensive overview.

The Performance Challenge with Traditional Java Methods

Before the introduction of the Java Method Server in Documentum 5, executing Java-based methods presented a significant performance bottleneck. Each method invocation triggered the launch of a separate operating system process. This meant that every time a Java method was called, the system incurred the overhead of process creation and destruction.

While this overhead is usually minimal for native applications, it became substantial for Java methods. Each invocation necessitated starting a Java Virtual Machine (JVM), loading the necessary classes for the method execution, and then shutting down the JVM. On many systems, this process could add seconds to the execution time of each method, rather than milliseconds. When workflows incorporating numerous Java methods were used by hundreds of users, this overhead quickly translated into serious performance and scalability issues for Documentum environments.

Introducing the Java Method Server: A Solution for Scalability

Documentum 5 addressed this performance challenge by introducing the Java method server. This innovation dramatically improved the performance and scalability of Documentum’s method architecture, particularly for Java-based methods. Documentum has increasingly embraced Java as a core technology, with clients and core libraries being developed in Java. However, the performance of Java methods had been a persistent pain point, which the Java method server was designed to resolve.

The Java method server operates as a separate process from the Content Server and is specifically responsible for executing methods. When a method is invoked, the Content Server communicates with the method server, which then manages the execution of the Java method implementation. Because the method server is a continuously running process, the overhead of starting and stopping a JVM for each method call is eliminated. This persistent JVM environment provides substantial performance gains.

Furthermore, as methods are often executed repeatedly, the classes required for their implementation only need to be loaded once by the method server. Other overheads, such as establishing docbase sessions, can also be reduced through connection pooling within the method server. The result is a significant improvement in method execution speed, reducing execution times from seconds to milliseconds and minimizing system resource consumption.

Diagram illustrating the architecture of the Java Method Server, showing its separation from the Content Server and its role in handling Java method executions.

How the Java Method Server Works: A Web Application Approach

The Java method server itself is a Java-based web application. It communicates with the Documentum Content Server using HTTP requests. When a method is triggered, the Content Server sends an HTTP request to the method server. This request includes the name of the Java class that implements the method and any necessary arguments. A servlet within the method server then processes this request and executes the specified method.

In Documentum, methods are defined using dm_method objects. To designate a Java method for execution via the Java method server, you need to configure the dm_method object attributes as follows:

• Set dm_method.method_type to java.
• Set dm_method.use_method_server to 1.
• Set dm_method.method_verb to the fully qualified class name of the method implementation.

When the Content Server encounters a method configured in this way, it sends an HTTP request to the Java method server to execute the specified class.

This straightforward architecture not only resolves the performance overhead issue but also provides a convenient way to significantly improve the scalability of the Content Server. Although not configured by default, method servers can be deployed on separate physical machines from the Content Server. It’s even possible to run the method server on a different operating system platform than the Content Server (e.g., Content Server on Solaris and method server on Windows). This distribution of workload offloads processing from the Content Server, potentially enabling it to handle a larger number of users.

For methods that are particularly resource-intensive, load balancing can be implemented using standard HTTP load balancers to distribute requests across multiple method server instances. The Java method server is designed to be uncomplicated and relies on a standard J2EE-compatible servlet container.

Note: While the method server is officially supported on Tomcat, it is highly likely to function correctly with any J2EE servlet container, such as BEA Weblogic, Jetty, or Websphere. However, official support for these alternative containers may vary depending on the Documentum version and support policy.

Implementing Methods for the Java Method Server: The IDmMethod Interface

To be executed by the method server, Java methods must implement the IDmMethod interface. This interface is defined in the mthdservlet.jar file, which is located on the Content Server.

package com.documentum.mthdservlet;
import java.io.OutputStream;
import java.util.Map;

/**
 * Interface for Java Methods invoked by the Documentum Content Server.
 */
public interface IDmMethod {
    /**
     * Entry point for Java methods executed by the Content Server's DO_METHOD apply method.
     * @param parameters Map of parameter names (String) to parameter values (String array).
     *                   Corresponds to the ARGUMENTS string passed by DO_METHOD apply.
     * @param output     OutputStream for HTTP response content, saved in docbase if SAVE_RESULTS is TRUE.
     *                   NULL if DO_METHOD launched asynchronously.
     * @throws Exception
     */
    public void execute(Map<String, String[]> parameters, OutputStream output) throws Exception;
}

The IDmMethod interface contains a single method, execute, which serves as the entry point for method execution, analogous to the main method in traditional Java applications. The parameters argument is a Map containing method parameters as key-value pairs, where both keys (parameter names) and values are strings.

For example, workflow methods typically receive five standard parameters:

1. "user": The username under which the method should be executed.
2. "docbase_name": The name of the docbase to operate against.
3. "packageId": The workitem ID (referred to as packageId).
4. "ticket": A security ticket for docbase authentication.
5. "mode": Generally ignored and not used.

In traditional method implementations, these parameters were passed as an array of strings (args) to the main method. The IDmMethod interface provides a more structured and accessible way to handle these parameters.

Note: Due to the similarities between classic method implementations and method server implementations, it’s possible to create an abstract base method class that allows a single workflow method implementation to function with both execution mechanisms. This approach can be very beneficial for code reusability and maintainability.

The output parameter is used to return data if SAVE_RESPONSE is set to true for the method invocation. For asynchronous methods, this output stream will always be null. The specific use cases for this output stream are beyond the scope of this article.

Regarding logging, traditional methods wrote to the Content Server log via stdout. With the method server, logs are written to a method-server-specific location. Invocation logging is still captured in the Content Server log when dm_method.trace_launch is set to true, but System.out output is directed to the servlet container’s log location. For a default method server installation on the Content Server, this location is typically %DM_HOME%tomcatlogsstdout.log.

Leveraging log4j for Enhanced Logging

DFC logging and tracing are configured through the log4j.properties file, located at %DOCUMENTUM%configlog4j.properties on the Content Server. Detailed configuration of log4j is outside the scope of this article, but comprehensive documentation is available on the log4j home page. Properly configuring log4j within the method server environment is crucial for effective debugging and monitoring of method executions.

Deploying Method Implementations to the Method Server

Deploying method implementations to the Java method server is a straightforward process. Simply copy the compiled class files or JAR files containing your method implementations to the %DOCUMENTUM%dbajava_methods directory on the Content Server. The method server automatically includes this directory in its classpath.

Whenever new classes are deployed or existing ones are updated, the method server needs to be restarted to recognize the changes. It’s also essential to ensure that all dependent classes and JAR files required by your method implementations are also deployed to the method server’s classpath.

Note: Refer to the “Method server registry keys” section below for advanced classpath considerations, especially when using Business Object Framework (BOF).

When properly configured, the method server logs its classpath during startup, including JAR files deployed in the java_methods directory. This log information, typically found in the method server logs, can be helpful for verifying correct deployment and classpath configuration.

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 Documentum repository stores configuration settings, including the URI used to invoke the method server. This URI is managed through the app_server_name[] and app_server_uri[] attributes, which are correlated. The method server URI is associated with the app_server_name value do_method. By default, the app_server_uri is typically set to https://localhost:9080/DmMethods/servlet/DoMethod.

For development environments, it can be highly beneficial to modify this URI to point to a method server running on a developer’s local machine for debugging purposes. While setting up a local method server requires some initial effort, the improved debugging capabilities often quickly justify the investment, especially when working with complex method code.

Disabling the Method Server

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

Note: On UNIX-based Content Server hosts, ensure that the java.ini file is correctly configured before using the method server.

Method Server Registry Keys (Windows)

On Windows platforms, the Java method server is installed as a Windows service. Although it’s based on Tomcat, it’s not launched using the standard catalina.bat script. Instead, tomcat.exe, located in C:Program FilesDocumentumtomcat4.0.6bbintomcat.exe, is executed. Its startup parameters are read from the Windows Registry, specifically from: HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesDmJavaMethodServerParameters.

Note: Modifying the classpath entry in the registry may be necessary when using the Business Object Framework (BOF) in method implementations. Due to classloader ordering issues, BOF implementation classes need to be loaded by the custom classloader defined in DFC. The web application classloader used by Tomcat can interfere with BOF class loading if BOF classes are loaded into the method server’s web application classpath.

Common Problems and Troubleshooting

Most issues encountered with the method server are related to classpath problems. These typically manifest as NoClassDefFoundError exceptions in the method server logs, indicating that a required class is missing from the method server’s classpath.

Note: Be cautious when diagnosing NoClassDefFoundError exceptions, especially when dealing with static class references or static initializers. The class reported in the error message might not be the actual missing class. It could be a class that the reported class attempts to initialize statically.

Classpath problems related to custom BOF classloaders can be particularly challenging to resolve. BOF is not ideally suited for servlet container environments with multiple classloaders. BOF classes are best loaded by the same classloader as DFC, which is usually the root classloader in standard Documentum installations.

Note: A recommended approach for deploying BOF functionality in method server environments is to package BOF classes into a separate JAR file. This JAR file, along with any other dependent JARs, should then be placed in the servlet container’s root classpath (where DFC JARs are located). For default Windows installations, this root classpath is configured through the registry key mentioned earlier.

Conclusion: Embracing the Java Method Server for Efficient Documentum Operations

The Java method server is a critical component for achieving optimal performance and scalability when utilizing Java-based methods within Documentum. By understanding its architecture, implementation, and configuration, Documentum administrators and developers can effectively leverage this powerful feature to build robust and efficient content management solutions. The method server eliminates the performance bottlenecks associated with traditional Java methods, enabling faster execution, reduced resource consumption, and improved overall system responsiveness. By properly deploying and configuring Java methods for the method server, organizations can unlock the full potential of custom server-side logic within their Documentum environments.