Java class path configuration

ILOG® JRules Connector runs on the IBM® InfoSphere® Information Server engine tier host. ILOG JRules connector is a Java™ based connector and it requires access to various ILOG JRules resources such as ILOG JRules JAR files, Java Execution Object Model (XOM) classes, and the configuration files to function properly.

You must specify the resources required by the connector in the Java class path for the connector. You can specify the required resources in the Classpath property on the ILOG JRules connector stage page.

You can define a InfoSphere DataStage® project environment variable to list all the necessary resources, and then add it to the job as job parameter specified as the Classpath property value. When the resources are specified in the Classpath property, they are made available to the connector during the job execution as well as during the configuration wizard session.

The use of the system Java class path to list the necessary resources is not recommended. If specified in the system class path, the resources might interfere with other Java processes that are running on the same machine. It is also not convenient to add resources to the system class path incrementally because it requires restarting the IBM InfoSphere DataStage engine in order to recognize the new entries added to the system class path. If the engine is a Windows system, then it requires a reboot. An example where the system class path needs to be updated periodically is to add new Java XOM JAR files for the connector to use to invoke new rulesets.

If it is not convenient to add the necessary resources in the Classpath property of each ILOG JRules stage, then you can do one of the following instead of setting the system class path value:
  • For the runtime execution of the job, define the CLASSPATH environment variable at the IBM InfoSphere DataStage project level, and list the necessary resources in the default value for this environment variable. The specified CLASSPATH value is then picked up by every job in that IBM InfoSphere DataStage project. To override the default value specified at the project level, the jobs can import this environment variable as a job parameter and set its value to be used by the connector class path value for that particular job.
  • For the configuration wizard, copy the necessary resources to IS_HOME/ASBNode/lib/java, where IS_HOME represents the home directory of the IBM InfoSphere Information Server installation on the IBM InfoSphere Information Server engine tier host.
    Note: You cannot add resources to the system class path for the configuration wizard sessions because these sessions run under the control of ASB Agent service. ASB Agent service is initialized with the internal custom classpath which does not include the resources specified in the system class path value.

Depending on the engine mode selected, you must have the specified JRules JAR files in the class path during the job execution as well as for the configuration wizard use.

The configuration wizard is running under ASB Agent service process on the IBM InfoSphere Information Server engine host. When the wizard loads Java XOM classes from the Java XOM JAR file specified in the Classpath property, that JAR file becomes locked during the wizard session. The wizard loads the XOM classes in each session independently, so if necessary it is generally possible to overwrite the XOM JAR between the wizard sessions, for example to put a newer version of the JAR in place of the old one. However, on some platforms the JAR file may remain locked even after the wizard session completes, because the ASB Agent process under which the classes were loaded is still running. In those cases, even if it is not possible to delete the locked JAR or move another JAR to replace of the locked JAR, it might still be possible to copy another JAR over the locked JAR. If that still does not work, another option is to place the new JAR to a new location and specify that location in place of the old one in the Classpath property. As the last option, the ASB Agent process can be restarted.

Core engine mode

Depending on the type of rules that you used, you must have the following JRules JAR files in the class path during the job execution:
  • Classic rules:
    JRULES_HOME/executionserver/lib/jrules-engine.jar
  • Decision Engine rules:
    JRULES_HOME/executionserver/lib/jrules-engine.jar
JRULES_HOME/executionserver/lib/dom4j-VERSION.jar
JRULES_HOME/executionserver/lib/openxml4j-VERSION.jar
JRULES_HOME/executionserver/lib/poi-VERSION.jar
JRULES_HOME/executionserver/lib/poi-ooxml-VERSION.jar
where JRULES_HOME represents the ILOG JRules product home directory on the IBM InfoSphere Information Server engine host, and VERSION represents the version of the library available in the ILOG JRules product version that you use, for example dom4j-1.6.1.jar.

These JAR files are not required for the configuration wizard sessions.

When the ruleset for which the connector is configured is based on Java XOM, then the XOM classes of the ruleset parameters also need to be included in the class path. This applies to the job runtime as well as the configuration wizard sessions.

When the connector is configured for core engine mode, it does not require access to any configuration files.

J2SE RES XU mode

The following JRules JAR files need to be present in the class path during the job execution as well as for the configuration wizard use:

  • JRULES_HOME/executionserver/lib/jrules-engine.jar
  • JRULES_HOME/executionserver/lib/jrules-res-session-java.jar
  • JRULES_HOME/executionserver/lib/jrules-res-execution.jar
  • JRULES_HOME/executionserver/lib/sam.jar
  • JRULES_HOME/executionserver/lib/log4j-1.2.8.jar
  • JRULES_HOME/executionserver/lib/j2ee_connector-1_5-fr.jar

Where, JRULES_HOME represents the ILOG JRules product home directory on the IBM InfoSphere Information Server engine host.

When the ruleset for which the connector is configured is based on Java XOM, then the XOM classes of the ruleset parameters also need to be included in the class path. This applies to the job runtime as well as the configuration wizard sessions.

When the ruleset repository is JDBC-based, the JDBC driver implementation necessary for JRules engine to access the repository needs to be present in the class path. For example, if the ruleset repository is implemented as a Db2® database, the db2jcc4.jar JDBC driver available with the Db2 product installation might be selected to access the repository.

The type of the ruleset repository and the connect information for the repository is stored in the ra.xml JRules configuration file. The directory with this file needs to be listed in the class path for the connector. The JRules installation comes with the example ra.xml file in the JRULES_HOME/executionserver/bin directory, which can be customized for access to a particular ruleset repository. For more information about the ra.xml configuration file, refer to the ILOG JRules product documentation.

J2EE RES XU mode

The connection to the ruleset repository is configured when the Rule Execution Server is deployed to the Java Platform, Enterprise Edition server.

During the job execution, the connector acts as remote EJB3 client and establishes connection to the EJB3 session component that must be deployed to the Java Platform, Enterprise Edition server on which the Rule Execution Server is deployed. This engine mode requires that the ILOG JRules Java EE add-ons are installed and configured correctly in the JRules environment. The following JRules JAR files must be present in the class path for the job execution, where JRULES_HOME represents the ILOG JRules product home directory on the IBM InfoSphere Information Server engine host.

  • JRULES_HOME/executionserver/lib/jrules-engine.jar
  • JRULES_HOME/executionserver/lib/jrules-res-session-java.jar
  • JRULES_HOME/executionserver/lib/jrules-res-execution.jar
  • JRULES_HOME/executionserver/lib/sam.jar
  • JRULES_HOME/executionserver/lib/log4j-1.2.8.jar
  • JRULES_HOME/executionserver/lib/j2ee_connector-1_5-fr.jar

In addition to the JRules JAR files, you must have the Java Platform, Enterprise Edition client JAR files necessary to establish connection to the EJB3 component on the Java Platform, Enterprise Edition server.

When the JRules engine is running on WebSphere® Application Server v7 and the connector connects to it through the WebSphere Application Client v7 installed on the engine tier machine, you must add the following JAR files to the class path:
  • WAS_HOME/runtimes/com.ibm.ws.ejb.thinclient_7.0.0.jar
  • WAS_HOME/runtimes/com.ibm.ws.webservices.thinclient_7.0.0.jar
Where WAS_HOME is the WebSphere Application Client 7 home directory on the IBM InfoSphere Information Server engine tier machine.
Note: You must select the Stand-alone Thin Clients and Resource Adapters option during the WebSphere Application Client installation in order for these two JAR files to be included in the installation.

The EJB3 stub JAR files must be created and listed in the class path. This stub JAR file is generated by running the createEJBStubs script located in the WAS_HOME/bin directory, where WAS_HOME is the home directory of the WebSphere Application Server v7 installation on which the Rule Execution Server is deployed. The file extension for this script differs between operating systems. For example, on Windows, it is .bat and on Linux it is .sh. The script must be executed once against the jrules-res-session-ejb3-WAS7.jar file located under JRULES_HOME/executionserver/applicationservers/WebSphere7 directory. The option -newfile is to specify the location of the generated stub file. For example:

WAS_HOME/bin/createEJBStubs.sh JRULES_HOME/executionserver/applicationservers/WebSphere7/jrules-res-session-ejb3-WAS7.jar -newfile JRULES_HOME/executionserver/lib/jrules-res-session-ejb3-WAS7_stub.jar

The generated EJB3 stub file must be copied to the IBM InfoSphere Information Server engine host and included in the class path for the job execution.

When the ruleset for which the connector is configured is based on Java XOM, then the XOM classes of the ruleset parameters must also be included in the class path. This applies to the job runtime as well as the configuration wizard sessions. In this engine mode, the Java XOM classes must implement the java.io.Serializable interface. Otherwise, the jobs fail with CORBA marshalling exceptions as the ruleset parameter values are not transported properly over the EJB connection.

The connector also requires access to the jndi.properties configuration file. This file contains the properties needed to create the initial context (java.naming.InitialContext object) to establish connection to the EJB3 rule session component on the Java Platform, Enterprise Edition server. An example jndi.properties file is provided with JRules installation under the JRULES_HOME/executionserver/samples/j2eerulesession/websphere7 directory. You can customize it and add its containing directory to the class path for the connector.

You must also point the connector to sas.client.props, ssl.client.props, and soap.client.props files which contain additional information for establishing connection to the WebSphere Application Server from the WebSphere Application Client installation used by the connector. The WebSphere Application Client installation has sample files that can be customized and configured to connect to a particular WebSphere Application Server instance. These sample files are stored in the WAS_HOME/properties directory.

Specify the following options in the Java VM settings property under the Java properties section in the Stage properties:
  • -Dcom.ibm.CORBA.ConfigURL=file:WAS_HOME/properties/sas.client.props
  • -Dcom.ibm.SSL.ConfigURL=file:WAS_HOME/properties/ssl.client.props
  • -Dcom.ibm.SOAP.ConfigURL=file:WAS_HOME/properties/soap.client.props
  • -Djava.util.logging.manager=com.ibm.ws.bootstrap.WsLogManager
  • -Djava.util.logging.configureByServer=true
Where, WAS_HOME is the WebSphere Application Client 7 home directory on the IBM InfoSphere Information Server engine tier machine.
Note: The configuration wizard never accesses the JRules Rule Execution Server deployed to WebSphere Application Server. If the J2EE RES XU engine mode is selected when the configuration wizard is launched, or if this engine mode is selected in the configuration wizard session, the wizard accesses the JRules engine as the locally managed JRules Rule Execution Server. The requirements in this case are therefore the same as for J2SE RES XU engine mode.

Generating Java code through the configuration wizard

When the configuration wizard is used to generate Java code based on the columns defined on the stage links, the connector does not require access to any resources other than what is automatically provided by IBM InfoSphere Information Server and the Java Runtime Environment (JRE) in which the connector runs.