The Documentum Java Method Server
The Documentum Java Method Server
The Documentum Java Method Server enables efficient invocation of Documentum methods implemented in Java. This article explores the features of the method server, how to configure it, and where to look when you run into trouble.
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:
- Methods execute on the server and are therefore client independant. This is useful if there is behavior that is shared across multiple client platforms
- 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.
- 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.
- 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:
- “user” –> The username to run the method as
- “docbase_name” –> The name of the docbase to run the method against
- “packageId” –> The workitemId (yes, it is called packageId even though it is for a workitemId)
- “ticket” –> The ticket to use to log onto the docbase
- “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%\tomcat\logs\stdout.log
log4j
DFC logging and tracing is controlled via the log4j.properties file located in %DOCUMENTUM%\config\log4j.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%\dba\java_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:\Documentum\dba\java_methods
20:01:11,967 INFO [main] com.documentum.mthdservlet.MethodConfig - DoMethod CLASSPATH=%CLASSPATH%;D:\Documentum\dba\java_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, the app_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
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 Files\Documentum\tomcat\4.0.6\bin\tomcat.exe is executed. It loads its arguments from the registry in parameters specified in the following location in the registry:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\DmJavaMethodServer\Parameters
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.
(1 votes, average: 5 out of 5)
Loading ...One Comment
please give the full subject on java documentum. i am a basic level student. i am unable to understand this. why we are using this one . plz help me inthis. it is urgent to me
in our comapny we are using this one.