Configuring the Java Runtime Environment (JRE)

Process Java API classes enable Process applications to access Process Engine workflow services. Before you can develop Process applications, you must first install and configure the appropriate Java Development Kit(s) (JDK) to provide the JRE. The Process Java runtime APIs are provided in the pw.jar file (for Process Services for FileNet Workplace, Process and Content Java APIs are provided in the pw.jar, eProcess.jar, and wcm.jar files). However, there are known issues associated with adding these JAR files to your system CLASSPATH.

Note In addition to adding JAR files to your CLASSPATH, if you intend to use the JMS Service Adapter of the Component Integrator with FileNet Workplace using either Tomcat or WebSphere, the Process Task Manager on the Application Engine must be configured to use the JVM of the application server (see below).

Subtopics include:

Note The Process Engine requires that the Remote Method Invocation (RMI) mechanism be built-in to the JRE. If you develop with Microsoft Visual J++™, install the Microsoft RMI patch before compiling your application code.

Which JRE / JDK (for Development) To Use

Which JRE / JDK (for development) to use may vary according to your runtime platform and which FileNet web application (FileNet Workplace, FileNet Web Services, or FileNet Open Client) you are using, as shown in the table below. For Stand-alone PJAC (not shown in the table), the PJAC installer searches for an existing JRE 1.3.1 or greater. If not found, the PJAC installer installs JRE 1.3.1.

Important Note Versions shown in this table may be changed. For the latest information on which versions of software (including JREs) are supported for Process Services, see the Process Compatibility/Dependency/Server Matrix document, located at the http://www.css.filenet.com web site (Clink on the link, or go to Product Tech Info > FileNet P8 Image Manager Services > Products - Compatibility & Dependency > Process Compatibility/Dependency/Hardware Matrix. A FileNet CSS password is required.).

Client/Server FileNet Workplace FileNet Web Services FileNet Open Client
Web Client Sun Microsystems JRE 1.4.2 Sun Microsystems JRE 1.4.2 Sun Microsystems JRE 1.4.2
Web Server Use the appropriate Sun Microsystems JRE for the web server and its OS. The PJAC installer searches for an existing specific JRE 1.3.1 version. If not found, the installer installs JRE 1.3.1. The PJAC installer searches for an existing specific JRE 1.3.1 version. If not found, the installer installs JRE 1.3.1.
Process Engine server - Windows 2000 platform Sun Microsystems JRE 1.4.2 (installed by the Process Engine installer) Sun Microsystems JRE 1.4.2 (installed by the Process Engine installer) Sun Microsystems JRE 1.4.2 (installed by the Process Engine installer)
Process Engine server - Solaris platform Sun Microsystems JRE 1.4.2 Sun Microsystems JRE 1.4.2 Sun Microsystems JRE 1.4.2
Process Engine server - HP-UX platform --- HP JRE 1.4.1 HP JRE 1.4.1
Process Engine server - AIX platform IBM AIX JRE 1.4.1 for AIX 5.1 ML3 and AIX 5.2 ML2. IBM AIX JRE 1.4.1 for AIX 4.3 and higher. IBM AIX JRE 1.4.1 for AIX 4.3 and higher.

Java SDK Configuration Procedure

On your development system(s), perform the following steps to configure the JRE:

  1. Install the appropriate JDK on your development system (see table above).
  2. For Workplace on Windows, the default installation directory is <drive>...\j2dk1.4.2; on Solaris, etc. <drive>:/j2sdk1.4.2 (for JDK 1.4.2), etc. (The remainder of this procedure assumes a Windows platform.) If you run the PJAC installer for FileNet Web Services and/or Open Client or for Stand-alone PJAC, PJAC installs the Sun JDK 1.3.1 to the default directory. As a reminder, remember to add the JDK to your PATH variable.

    Caution When installing the JDK, be sure to use the default settings. If you change default settings and you are using JRE 1.3.1, the security settings will not be correctly installed by the JDK installer (this is not a problem with JRE 1.4.x). To correct for JRE 1.3.1, make sure that both the <JRE>\bin and the <JRE>\bin\hotspot directories have both Read and Execute privileges assigned for the Users group and that these directories are in your CLASSPATH.

    Important Note If you are planning to develop Process Java applications for FileNet Open Client with the JiGlue COM Bridge, you must install the JDK in the default directory.

  3. Create a local directory (in any location) called \pe. You will use this directory to hold the Process Development Environment files, including the pw.jar file (for Java development with FileNet Workplace, the pw.jar, eProcess.jar, and wcm.jar files).
  4. Copy the ...\Developer Files directory (includes the pw.jar file; for FileNet Workplace includes the pw.jar, eProcess.jar, and wcm.jar files) from the PJAC and Toolkit Installation CD (for Workplace, from the P8 Platform CD) to the new \pe directory.
  5. For information on locating the ...\Developer Files directory on the CD (as well as additional information on the Process Development Environment's contents), see (according to your FileNet web application):

  6. Use one of the three methods indicated in the subsection, Adding JAR Files to CLASSPATH Issues, which follows this step, to avoid conflict issues that can arise when adding these JAR files to your CLASSPATH.

Adding JAR Files to CLASSPATH Issues

A known issue associated with adding the pw.jar file (for Process Services for FileNet Workplace, the pw.jar, eProcess.jar, and wcm.jar files) to the system CLASSPATH is that this can cause security conflicts when attempting to run the out-of-the-box Java client applications on your development system. The conflict is caused when, for example, the Process Engine server sends the correct pw.jar, but the CLASSPATH statement forces the client application to use the pw.jar file from the specified location.

If you run the Java Plug-in console on a system attempting to run the out-of-the-box Java client application with the pw.jar file (for Process Services for FileNet Workplace, the pw.jar, eProcess.jar, and wcm.jar files) specified in the CLASSPATH, you will receive messages similar to the following:

    java.security.AccessControlException: access denied (java.lang.RuntimePermission modifyThreadGroup)
    at java.security.AccessControlContext.checkPermission(Unknown Source)
    at java.security.AccessController.checkPermission(Unknown Source)
    at java.lang.SecurityManager.checkPermission(Unknown Source)
    . . .

There are three ways, any one of which will work to get around this behavior. Perform one of the following three workarounds, as is appropriate for your requirements (modify for the appropriate JDK):

Note The only portion of the CLASSPATH statement specific to Process application development are the locations of the eProcess.jar, pw.jar, and wcm.jar files. If any of these assumptions are not correct for your development environment, refer to the Sun Microsystems Java Development Kit documentation (http://java.sun.com/) for additional information on setting up the CLASSPATH variable.

Note If you are using an IDE, and you wish to use the Java Step Processor UI Toolkit Swing-based Java beans and interfaces to create user controls similar to the FileNet sample controls, add vwpanel to your project (the vwpanel.jar file is included with the Process Java Step Processor UI Toolkit). For information on the Process Java Step Processor UI Toolkit, see the Java Step Processor UI Toolkit Overview topic.

Configuring the Process Task Manager to Use the Application Server's JVM

If you are developing for the FileNet P8 Baseline platform using FileNet Workplace and you plan to use the JMS Service Adapter of the Component Integrator on either a Tomcat (the JMS service provider is Sun Microsystems J2EE Reference Implementation) or a WebSphere application server, the Process Task Manager on the Application Engine must be configured to use the JVM of the application server.

To do this, perform the following file modifications (depending upon whether you are on a Windows or a Solaris platform):

Note The example edits shown below for both Windows and Solaris platforms assume that your system has the Environment variable JAVA_HOME set to the JVM of the Tomcat or WebSphere application server. If not, you will need to specify the path of the application server's JVM in place of the JAVA_HOME variable.

Windows Platform

Edit the winroutercmd.bat file to point to the application server's JVM by commenting out the existing XERCES_HOME and JVM locations, and by changing the directory to %JAVA_HOME%\bin. The default location for winroutercmd.bat is <application engine installation directory>\FileNet\Router\winroutercmd.bat.

For example:

 rem cd %XERCES_HOME%
 rem cd ..\..\_jvm\bin
 cd %JAVA_HOME%\bin

Solaris Platform

Edit the sunroutercmd.sh shell file to point to the application server's JVM by commenting out the xerces_home location, and by changing the directory to $JAVA_HOME/bin. The default location for sunroutercmd.sh is <application engine installation directory>/FileNet/Router/sunroutercmd.sh.

For example:

 # cd "${xerces_home}"
 cd ${JAVA_HOME}/bin