EMC White Paper

Method Server essentials

Soumya Mitra

Abstract: This document highlights the technically obscure areas of Content Server to facilitate Developer Support assignments.

Date 3/15/2007

Copyright 2007 EMC Corporation. All rights reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. EMC2, EMC, and EMC Documentum product names are trademarks of EMC Corporation. All other trademarks used herein are the property of their respective owners. All other brand names are trademarks or registered trademarks of their respective owners.

Method Server essentials

Introduction to Method Servers

Content server provides very powerful server side scripting features through its method server architecture. It is somewhat analogous to Common Gateway Interface or CGI feature of a Webserver. Likewise in Content Server, methods are run as executable scripts or programs in separate external processes. The figure below illustrates how different components interact in a Content Server environment.

The Content Server process orchestrates the entire function of repository. When a client invokes a method server call, it delegates the call (based on the method) to appropriate execution agents. The Content Server version 5.2.5 and 5.3 has three execution agents:1) Content Server 2) Docbasic method server 3) Java method server The methods can be a Docbasic script, Java class or a self executable program written in another programming language such as C++. For every method, we have to create a method object of type dm_method. The attributes of that method object will define arguments and the execution parameters. Methods are executed by issuing a DO_METHOD administration method or using a job. Using a DO_METHOD allows you to execute the method on demand. Using a job allows you to schedule the method for regular, automatic execution.

Method Server essentials

Content Server & Docbasic Method Server

There are only two Documentum supported languages used for cross-platform development of dm_method content. These languages are GAWK and Docbasic. Since these languages are interpreted and limited in some ways, it might be desirable to forgo the cross platform advantage and use a compiled language. On the NT platform, a customer might want to develop an executable in Visual Basic 5, and use it as dm_method content. The figure below shows how a DmBasic method needs to be setup in the method object.

Not just any Visual Basic application can run as method. The rules are the same for development in Visual Basic as well as Docbasic or GAWK. You can NOT have any graphical user interface in a method. The process runs on the server host and there is no way to interact with it from the client. Also, you must make the program a command line executable that accepts the necessary parameters at the start of execution.

Skeleton of a DmBasic Method

'#################################################################### ' ' A skeleton of a DmBasic Method ' '#################################################################### ' ' Entry_Point is the entry point for this script. It retrieves '

Method Server essentials

Sub Entry_Point _ (objId As String, _ docBase As String, _ userName As String, _ ticket As String) ' Connect with Docbase

buff = "connect," & docBase & "," & UserName & "," & ticket sess_id = dmAPIGet(buff) ' If any error occues then: Call Connect_Handler() End Sub ' ' Handle and report any errors ' Sub Error_Handler (sess As String) buff$ = "getmessage," & sess mesg$ = dmAPIGet(buff$) print "Message: ";mesg$ Stop End Sub ' ' Retrieve any connection related information ' Sub Connect_Handler () buff$ = "getmessage,a" mesg$ = dmAPIGet(buff$) print "Message: ";mesg$ Stop End Sub

Java Method Server

Documentum provides a customized version of Apache Tomcat to execute Documentum Server Java methods. It gets installed along with the Content Sever in the same box. In addition to Tomcat, Documentum provides a servlet called DO_METHOD to execute Documentum Server methods. The compiled servlet code is found in mthdservlet.jar located on the same host as Content Server. This jar file contains the IDmMethod class.

Method Server essentials

Technically all Documentum Java Sever methods are simple java classes, which implements IDmMethod interface. When a DO_METHOD method directed to the Java method server is issued (with the Java method class name and parameters), it generates an internal HTTP_POST request. The Java method server invokes the do_method servlet to service the request.

Why Java method server?

Content Server execution agent can launch any executable program, including a JVM running a Java application. So one can raise the question if CS can lunch a Java program, then why Documentum provides a separate Java method server? There are number of good reasons for this design:The java methods are executed as Servlets under Tomcat Application Server. So we can invoke many instances of the method without spawing multiple instances of JVM process, each of which running an instance of the method. This will save lot of memory and processing resources and provide performance benefits. The benefits are same like running a Servlet instead of running a CGI application. Java method server runs as an independent process. It can be stopped or started without recycling the content server. In Windows platform, method server can be run as a Windows service or as a process. CLASSPATH must include $DOCUMENTUM_SHARED/dctm.jar, $DM_HOME/dctm_server.jar, $DOCUMENTUM_SHARED/tcf/config, and $DOCUMENTUM_SHARED/tcf/lib/tcf-engine.jar

A common mistake
The Tomcat provided with Content Server to run Java method is not a full blown Tomcat. It has been customized by eliminating many features, so it is not suitable to work as a generic Servlet container. Often, a customer may deploy a WDK application on this Tomcat and run into issues. Such deployment will not work and unsupported by Documentum.

Anatomy of a Java Server method

It is same as any Java class with some specific guidelines:1. Always implement the IDmMethod interface in your class, 2. Implement the method execute(), 3. Obtain a Docbase session using newSessionManager() 4. Throw an exception instead of using 'exit', 5. Release your session after use. A typical skeleton of a Java Server Method will look like this
import import import import import java.util.*; java.io.OutputStream; com.documentum.mthdservlet.IDmMethod; com.documentum.fc.client.*; com.documentum.fc.common.*;

public class MyServerMethod implements IDmMethod { public void execute(Map params, OutputStream ostream) throws Exception // Log on the to docbase and get a session manager like this // IDfSessionManager sessionMgr = dfClient.newSessionManager(); // and get a session from the session manager {

Method Server essentials

// Add your business logic here ... } catch (DfException e) { ostream.write("A DfException occurred".getBytes()); ostream.write(e.getMessage().getBytes()); e.printStackTrace(); // spit out to stderr as well throw e; } finally { // If session is not null release the session to the // session manager here. } }

How to deploy a Java server method?

The following instructions provide the main steps to deploy a Java server method 1) Compile the Java method. Note that if you make changes to the workflow method, you must recompile the method and restart the Java Method Server for the changes to take effect. 2) Stop Tomcat, if its already running. 3) Start Windows Explorer and change to the following directory: %DOCUMENTUM%\dba\java_methods. This directory represents the location for all java methods that you develop, and which are executed by a Documentum supplied servlet called DO_METHOD on the application server. 4) Copy the java method class to deploy into this folder. 5) Restart the Tomcat application server. 6) Connect to your Docbase using Documentum Administrator. 7) Click Administration > Job Management > Methods in the left pane. 8) Click File > New > Method from the drop-down menu to create a new method. 9) In the Name field, enter your custom method name Do not use the format dm_methodname to name the method. This naming convention is reserved for default Documentum objects. 10) In the Verb field, enter DmSampleMethod. Note: The method_verb attribute must correspond to the same Java class used in Tomcat. For other type of methods, the method verb is the command-line name of the procedure or the name of the interpretive language that will execute the program file. It is a good practice to specify the fully-qualified class name of the Java class as the command verb. If your class is contained with a jar file then you must specify the fully-qualified class name. For example; com.documentum.bpm.bpsintegration.bps.DmBPSHTTPIntegration 11) Select java as the Method Type. 12) Check Run As Server. If checked, it indicates that you want the method to run as the installation owner account, with the installation owners privileges. Otherwise, the method runs as the user creating the method, with that users privileges. The default is unchecked. Run as Server must be checked to execute a method on the method server or application server. 13) UnCheck Launch Direct. This controls whether the program is executed by the operating systems system or exec API call. If checked, the server uses the exec call to execute the

Method Server essentials

procedure. In such cases, the method_verb must be a fully qualified path name. If unchecked, the server uses the system call to execute the procedure. 14) Check Use Method Server. 15) When done, click the Finish button to return back to the Methods page. The figure below shows a typical entry in method object for a Java method

How to trace method servers

To trace method execution in the method server or Content Server, set the trace_method_server server flag. You can set this flag using the SET_OPTIONS administration method or on the server startup command line: -otrace_method_server Tracing information generated by Content Server is stored in the server log file. Tracing information generated by the method server is stored in the method server log file. The log file is stored in
%DOCUMENTUM%\dba\log\<repository_id>\MethodServer\MethodServer\server_config_name.log

or
$DOCUMENTUM/dba/log/<repository_id>/MethodServer/MethodServer/server_config_name.log

Method Server essentials

The log file is created when the method server is started. If a method server log file currently exists, it is saved with a time stamp and a new log file is started. To trace method execution on the Java method server, set the trace parameter in the web.xml file to true. For example:
<init-param> <param-name>trace</param-name> <param-value>t</param-value> </init-param>

The web.xml file is found in %DM_HOME%\tomcat\webapps\DmMethods\WEBINF\web.xml ($DM_HOME/tomcat/webapps/DmMethods/WEBINF/web.xml). The log files generated by the Java method server are stored in %DM_HOME%\tomcat\logs ($DM_HOME/tomcat/logs).

Manually starting the method server

For Windows: Click Start-->Programs-->Administrative Tools-->Services.and run start.bat For Unix: Navigate to the $DM_HOME/tomcat/bin/ directory and run startup.sh java method server

Server and Method Server startup order

1) Docbroker - Independent of any other application 2) Repository - Dependent on Docbroker 3) Java Method Server - Dependent on Docbroker and Repository 4) Index server - Independent of any other application 5) Index agent - Dependent on Index server

Order of starting index sever and java method server do not matter. For shutdown, follow the reverse order.

How to check if method server is running?

Check if your java method server is up and running. Try accessing the following url http://<hostname>:9080/DmMethods/servlet/DoMethod It should show "Documentum Java Method Server". If not restart it. Navigate to the $DM_HOME/tomcat/bin/ directory and run startup.sh script for UNIX. For windows Click Start-->Programs-->Administrative Tools-->Services.and start java method server

Method Server essentials

Known issues with Java method server

Some time some custom application can cause Method Server to put heavy load on the content server. On further investigation we have found that if the application uses asynchronous server method invocations, then execution agent can potentially launch hundred or more external method processes. This causes a very high load on the content server and Oracle. The Tomcat server used for the method server can be configured to reduce the number of simultaneous threads active. This could theoretically provide some flow control by limiting the number of methods that can simultaneously be executed. Unfortunately it appears error handling in the Content Server for asynchronous methods is rather weak. If the Java Method Server is already processing all the simultaneous methods that it is capable of, all new requests get discarded. The application never knows that its method requests were discarded. Please note asynchronous method execution can overload the server and may cause substantial delay in execution of the method. When switching to synchronous method execution there are still problems. Under heavy load the "DO_METHOD" calls will fail with a rather vague error message. It is up to the application to decide that the server is under heavy load and therefore should just keep retrying the method submission until the server has bandwidth to service it. As it stands now the user requests simply fail when the server gets busy.

Challenge Questions
1) 2) 3) 4) 5) What is a Documentum Server Methods? How many types of Server Methods are supported? Who executes the Server Method? What interface does a Java Server Method need to implement? How to check if a method server is running?

Method Server essentials

10

About EMC EMC Corporation (NYSE: EMC) is the world leader in information storage systems, software, networks, and services, providing automated networked storage solutions to help organizations get the maximum value from their information, at the lowest total cost, across every point in the information lifecycle. Information about EMCs products and services can be found at www.EMC.com About Documentum Software from EMC EMC Documentum software includes enterprise content management solutions that enable organizations to unite teams, content, and associated business processes. With a single platform, EMC Documentum software enables people to collaboratively create, manage, deliver, and archive the content that drives business operations, from documents and discussions to e-mail, Web pages, records, and rich media. The Documentum enterprise content management platform makes it possible for companies to distribute all of this content in multiple languages, across internal and external systems, applications, and user communities. As a result of deploying Documentum, thousands of the worlds most successful organizations are harnessing corporate knowledge, accelerating time to market, increasing customer satisfaction, enhancing supply chain efficiencies, reducing operating costs, and improving their overall competitive advantage. For more information about Documentum enterprise content management, visit www.emc.com/documentum or call 800.607.9546 (outside the U.S.: +1.925.600.5802).

Method Server essentials

11