EAI Java Business Service

This chapter discusses the EAI Java Business Service. It includes the following topics:

About the EAI Java Business Service

The EAI Java Business Service (JBS) is a service framework that allows custom business services to be implemented in Java and run from a Siebel application. The framework consists of the following:

A template business service, EAI Java Business Service, which is defined in the repository.
An abstract Java class, com.siebel.eai.SiebelBusinessService, that defines the interface of the Java class that implements the business service.

The EAI Java Business Service works in two different ways:

32-bit JVM. The EAI Java Business Service works by creating a 32-bit Java Virtual Machine (JVM) in-process with the Siebel application and invoking Java implementations using Java Native Interface (JNI). Each Siebel process (component) has at most one JVM. JVMs are not shared across components.
64-bit JVM. The EAI Java Business Service works by creating a 64-bit Java Virtual Machine (JVM) that runs in a separate process from Siebel application and invokes Java implementations using HTTP.

Requirements for Implementing a Java Business Service

To implement a Java business service, the following software must be installed and properly configured on each Siebel Server or Siebel Mobile and Developer Web Clients:

A Java Runtime Environment (JRE)
All necessary Java code
A configured named subsystem of type:
- JVMSubSys for a 32-bit JRE or
- JavaContainerSubSys for a 64-bit JRE

The named 32-bit subsystem supplies the following parameters to the JBS: DLL, CLASSPATH, and VMOPTIONS. These parameters are described as follows.

DLL. The complete path of the JRE library, as shown in the following table.
CLASSPATH. The classpath used by the JVM.
The classpath must include the following Siebel JAR files as well as all Java code implementing the desired business service.
The required Siebel JAR files are:
- Siebel.jar
- SiebelJI_lang.jar (lang corresponds to the default language for your installation).
VMOPTIONS. Java Virtual Machine options. On all platforms, except AIX, it is recommended that the option -Xusealtsigs be used to make sure that the signal handlers used by the Siebel Server do not conflict with those of the JVM.

Note: The -Xusealtsigs option is mandatory for use on the Oracle Solaris platform. The JVM options do not load successfully into the Application Object Manager without this option.

Operating System	JRE Library	Typical Location on Server and Environment Variable Setting
AIX	libjvm.so	`/usr/java/jre/lib/ppc/j9vm` You must include both `/usr/java/jre/lib/ppc/` and `/usr/java/jre/lib/ppc/j9vm` in the LIBPATH variable. For example: siebenv.csh setenv LIBPATH=/siebel/siebsrvr/lib:/siebel/siebsrvr/ mw/lib:/siebel/siebsrvr/SYBSsa90/lib:/usr/lib:/siebel/ siebsrvr/lib:/oracle_client/app/oracle/OraHome_1/ lib32:/oracle_client/app/oracle/OraHome_1/lib:/usr/ java/jre/lib/ppc/:/usr/java/jre/lib/ppc/j9vm For example: siebenv.sh LIBPATH=/siebel/siebsrvr/lib:/siebel/siebsrvr/mw/lib:/ siebel/siebsrvr/SYBSsa90/lib:/usr/lib:/siebel/siebsrvr/ lib:/oracle_client/app/oracle/OraHome_1/lib32:/ oracle_client/app/oracle/OraHome_1/lib:/usr/java/jre/ lib/ppc/:/usr/java/jre/lib/ppc/j9vm
HP-UX	libjvm.sl	/opt/java/jre/lib/PA_RISC2.0/server Set the environment variable SHLIB_PATH to include the JVM’s `jre` and `server` directories. Set LD_PRELOAD in the siebmtshw file located in `/siebsrvr/bin`. For example: setenv SHLIB_PATH=${SHLIB_PATH}:/opt/java/jre/lib/ PA_RISC2.0; export SHLIB_PATH In siebmtshw: LD_PRELOAD=/opt/java/jre/lib/PA_RISC2.0/server/libjvm.sl export LD_PRELOAD
Linux	libjvm.so	/usr/java/jdk/jre/lib/i386/server Set the environment variable LD_LIBRARY_PATH to include the JVM’s `server` directory. For example: setenv LD_LIBRARY_PATH=/usr/java/jdk/jre/lib/i386/server: /usr/java/jdk/jre/lib/i386
Windows	jvm.dll	JDK installation directory. If using Java 7, then set the environment variable Path to include the JRE library. This is not necessary for Java 5 or 6. For example: <JRE_HOME>\jre7\bin\client\jvm.dll
Oracle Solaris	libjvm.so	/usr/jdk/instances/jdk/jre/lib/sparc/server Set the environment variable LD_LIBRARY_PATH to include the JVM’s `server` directory. Add `/platform/SUNW,Sun-Fire-V440/lib` to LD_LIBRARY_PATH. For example: siebenv.csh: setenv LD_LIBRARY_PATH=/usr/jdk/instances/jdk/jre/lib/ sparc/server:/platform/SUNW,Sun-Fire-V440/ lib:{LD_LIBRARY_PATH} For example: siebenv.sh LD_LIBRARY_PATH=/usr/jdk/instances/jdk/jre/lib/sparc/ server:/platform/SUNW,Sun-Fire-V440/ lib:{LD_LIBRARY_PATH};export LD_LIBRARY_PATH

The named 64-bit subsystem supplies the following parameters to the JBS: CONTAINERURL, CLASSPATH, and OPTIONS. These parameters are described as follows.

CONTAINERURL: The URL to the Java Web Container server for all the JBS requests.
CLASSPATH: The classpath used by the JVM.
The classpath must include the location of the jndi.properties file.
Ensure that the file contains the file name of the jndi.properties file.
With Java 8, the required JAR files for the execution of JMS must reside on the Java Web Container server. The Siebel.jar and SiebelJI_enu,jar are packaged within the war file. All other JMS Provider Jars depending on the usage of customer must be placed in the lib directory of the Apache Tomcat server.
OPTIONS: In the Java 64-bit subsystem, OPTIONS is not used. Therefore, OPTIONS must be set using the CATALINA_OPTS option in the setenv.bat or setenv.sh file of the javacontainer based on the operating system. An example is as follows:
Windows
```
javacontainerX\bin\setenv.bat
set CATALINA_OPTS=-Djava.compiler=NONE
```
non-Windows
```
File: javacontainerX/bin/setenv.sh
CATALINA_OPTS="-Djava.compiler=NONE"
```

The following topics are also discussed here:

Creating a 32-bit Java Subsystem by Using the Siebel Server Manager

The following example shows how to create a named 32-bit Java subsystem using the Siebel Server Manager:

create named subsystem JAVA for subsystem JVMSubSys with
DLL="D:\jdk\jre\bin\server\jvm.dll",
CLASSPATH="c:\cp\Siebel.jar;c:\cp\SiebelJI_enu.jar;c:\cp\myJARs.jar;.",
VMOPTIONS="-Xrs -Djava.compiler=NONE"

Note: On Oracle Solaris, the create statement might be truncated. To avoid this, you can set CLASSPATH in the create statement and DLL and VMOPTIONS in the Siebel application.

Alternatively, the parameters to the Java Business Service can be specified in the application configuration (CFG) file instead of a named subsystem. This applies only to the Siebel Mobile and Developer Web Clients, and not the Siebel Server.

[JAVA]
DLL = D:\jdk\jre\bin\server\jvm.dll
CLASSPATH = c:\cp\Siebel.jar;c:\cp\SiebelJI_enu.jar;c:\cp\myJARs.jar;.
VMOPTIONS = -Xrs -Djava.compiler=NONE

Creating a 64-bit Java Subsystem by Using the Siebel Server Manager

The following example shows how to create a named 64-bit Java subsystem using the Siebel Server Manager:

create named subsystem JAVA64 for subsystem JavaContainerSubSys
change param CONTAINERURL=http://localhost:<Config Agent HTTP Port>/siebel/jbs for 
named subsystem JAVA64
change param CLASSPATH=<JNDI file path> for named subsystem JAVA64
change param JVMSubsys= JAVA64 for comp sccobjmgr_enu

Based on your usage, place all other JMS Provider jars in the lib directory of the Apache Tomcat server.

Note: In Innovation Pack 2017 Siebel Server, the JAVA64 subsystem is preconfigured with the required CONTAINERURL, which eliminates the need for you to create the JAVA64 subsystem manually. However, you can modify parameters such as CLASSPATH-based JNDI file path.

Creating a 32-bit Java Subsystem by Using the Siebel Web Client

The following is an alternative procedure for creating a Java subsystem by using the Siebel Web Client.

To create a Java subsystem by using the Siebel Web Client

In the Siebel client, navigate to the Administration - Server Configuration screen, Enterprises view.
In the first list applet, select the Enterprise Server that you want to configure.
In the middle applet, click the Profile Configuration tab.

Click New to create a new component profile and set the following parameters:

Name	Value
Profile	JAVA
Alias	JAVA
Subsystem Type	JVMSubsys

In the Profile Parameters list applet (the last applet), set the following values:
1. Set the Value of the JVM Classpath parameter to one of the following:
  - The location of the jndi.properties file (if using the JMS Transport).
  - The JMS provider JAR files (if using the JMS Transport).
  - The Siebel.jar and SiebelJI_enu.jar files. These files can be installed by using either Siebel Tools or the Siebel Server. An example of these files for Microsoft Windows follows:
```
c:\Oracle\Middleware\wlserver_10.3\server\lib\weblogic.jar;c:\siebel\jndi;
c:\siebel\siebsrvr\CLASSES\Siebel.jar; 
c:\siebel\siebsrvr\classes\SiebelJI_enu.jar
```
2. Set the Value of the JVM DLL Name parameter to the path where you have the jvm.dll file installed. For example:
```
D:\jdk\jre\bin\server\jvm.dll
```
3. Set the Value of the JVM Options record to any JVM-specific options that you would like to enable, for example:
```
-Djava.compiler=NONE
```

Creating a 64-bit Java Subsystem by Using the Siebel Web Client

The following is an alternative procedure for creating a 64-bit Java subsystem by using the Siebel Web Client.

To create a 64-bit Java subsystem by using the Siebel Web Client

In the Siebel client, navigate to the Administration - Server Configuration screen, Enterprises view.
In the first list applet, select the Enterprise Server that you want to configure.
In the middle applet, click the Profile Configuration tab.

Click New to create a new component profile and set the following parameters:

Name	Value
Profile	JAVA64
Alias	JAVA64
Subsystem Type	JavaContainerSubSys

In the Profile Parameters list applet (the last applet), set the following values:
1. Set the Value of the JVM Classpath parameter to the following:
  The location of the jndi.properties file (if using the JMS Transport).
2. Set CONTAINERURL to point to the java container. For example:
```
CONTAINERURL=http://localhost:<Config Agent HTTP Port>/siebel/jbs for named 
subsystem JAVA64
```
3. Based on your usage, place all other JMS Provider jars in the lib directory of the Apache Tomcat server.

Note: In Innovation Pack 2017 Siebel Server, the JAVA64 subsystem is preconfigured with the required CONTAINERURL, which eliminates the need for you to create the JAVA64 subsystem manually. However, you can modify parameters such as CLASSPATH-based JNDI file path.

Creating a 32-bit Java Subsystem by Using the Siebel Dedicated Client

For dedicated client, define subsystem in the .cfg file with name JAVA.

Define the 32-bit subsystem as follows:

[JAVA]

DLL = “<jre Install Dir>\bin\server\jvm.dll�?

CLASSPATH = “c:\cp\Siebel.jar;c:\cp\SiebelJI_enu.jar;c:\cp\myJARs.jar�?;

VMOPTIONS = “-Xrs -Djava.compiler=NONE�?

About Platform-Specific Configurations for the JVM

Depending on the platform, it is necessary to set certain environment variables to load the JVM properly:

AIX. Make sure that you have the environment variable LIBPATH set to include the JVM's shared libraries, /usr/java/jre/lib/ppc/ and /usr/java/jre/lib/ppc/j9vm. For example:
```
setenv LIBPATH=/siebel/siebsrvr/lib:/siebel/siebsrvr/mw/lib:/siebel/siebsrvr/
SYBSsa90/lib:/usr/lib:/siebel/siebsrvr/lib:/oracle_client/app/oracle/OraHome_1/
lib32:/oracle_client/app/oracle/OraHome_1/lib:/usr/java/jre/lib/ppc/:/usr/java/
jre/lib/ppc/j9vm
```
For more information about setting the LIBPATH environment variable, see the documentation for IBM SDK and Java Runtime Environments (JREs) at:
http://www.ibm.com/support
HP-UX. Make sure that you have the environment variable SHLIB_PATH set to include the JVM's jre and server directories. For example:
```
setenv SHLIB_PATH /opt/java/jre/lib/PA_RISC2.0:/opt/java/jre/lib/PA_RISC2.0/
server:${SHLIB_PATH}
```
Set the variable LD_PRELOAD to the full path of the Java library.
Oracle Solaris, Windows. No additional settings are needed.

When a Java business service is invoked on UNIX from a server component (for example, the JMS Receiver; see EAI JMS Transport for more information), the necessary settings must be done in the script that creates the component.

For the receiver, the script is siebshw; for the Application Object Managers, it is siebmtshw. These scripts are present in the bin directory where the Siebel Server is installed.

Creating a Java Business Service

The following topics describe how to create a Java business service:

Defining a Business Service in Java

You define a business service in Java by:

Defining a new business service in the repository using Siebel Tools.
Specifying the necessary Java classes.

To define and specify a new Java business service in Siebel Tools

Copy the EAI Java Business Service (using the Copy Record command in Siebel Tools) and rename the copy.

Note: Checking the Cache column when you are creating the new Java business service causes the same Java object to be reused by subsequent invocations within the same session. See About the Lifecycle of a 32-bit Java Business Service.
Add a business service user property named @class, whose value is the fully qualified name of the Java class (for example, com.example.siebelBusinessService.ImportCustomer).

About Implementing a Business Service in Java

Once the Java business service has been defined in Siebel Tools, the Java class must be implemented. The Java class implementing the business service must extend com.siebel.eai.SiebelBusinessService.

SiebelBusinessService is an abstract Java class found in Siebel.jar. It declares three methods:

destroy. This method is called when the Java object is released by the Siebel application. It has a default empty implementation and can be overridden for the purpose of performing any cleanup.
invokeMethod. This method contains a default implementation that calls doInvokeMethod and catches any exceptions that are thrown by it. It does not declare any exceptions. It is invoked by means of JNI in the Siebel application’s native process. This method is not intended to be overridden.
doInvokeMethod. This method must be implemented by the subclass that implements the business service. It takes as arguments the methodName, input property set, and output property set. The property sets are instances of com.siebel.data.SiebelPropertySet. This method throws SiebelBusinessServiceException.

About Exception Handling for the Java Business Service

Errors are handled by throwing a com.siebel.eai.SiebelBusinessServiceException class. The constructor for this class takes two String arguments, an error code and an error message. The error code can be used for programmatic handling in Siebel eScript when the business service is called. Both the error code and the error message are displayed as an ordinary Siebel error message.

It is strongly recommended that proper error handling be employed when implementing the Java Business Service class. By invoking a SiebelBusinessServiceException, the standard Siebel error handling facilities are employed.

If any other exception is received from doInvokeMethod, then an error is produced with the details of the exception.

About the Lifecycle of a 32-bit Java Business Service

A JVM is created in-process with the Siebel process the first time a Java business service is invoked. Thereafter, the same JVM is used for all invocations of any Java business services.

An instance of the Java class implementing a business service is created the first time that business service is invoked. This instance is released through JNI when the native business service is destroyed. For business services that are not cached, this occurs whenever the caller (workflow, script) releases the native business service. For business services that are cached, this occurs when the session is destroyed (for example the user logs out). For a business service marked as cached in the repository, repeated invocations by a user during a single session invoke methods on the same Java object.

Example of a Java Business Service

Following is an example of a Java class implementing a business service:

package com.example.jbs;
import com.siebel.data.SiebelPropertySet;
import com.siebel.eai.SiebelBusinessServiceException;
public class AddBusinessService extends com.siebel.eai.SiebelBusinessService {
public void doInvokeMethod(String methodName, SiebelPropertySet input, 
   SiebelPropertySet output) throws SiebelBusinessServiceException {
   String X = input.getProperty("X");
   String Y = input.getProperty("Y");
   if (X == null || X.equals("") || (Y == null) || Y.equals("")) 
      throw new SiebelBusinessServiceException("NO_PAR", "Missing param");
   if (!methodName.equals ("Add"))
      throw new SiebelBusinessServiceException("NO_SUCH_METHOD�?, "No such method");
   else {
      int x = 0;
      int y = 0;
      try {
         x = Integer.parseInt(X);
         y = Integer.parseInt(Y);
      }
      catch (NumberFormatException e) {
         throw new SiebelBusinessServiceException("NOT_INT", "Noninteger passed");
      }
      int z = x + y; 
      output.setProperty("Z", new Integer(z).toString());
      }
   }
}

About the Lifecycle of a 64-bit Java Business Service

An instance of a Java class implementing a business service is created when it is invoked for the first time. This Java instance is stored in the Object Pool that is maintained inside the Java Web Container server. The Java instance is released from the Object Pool when the destroy method is called on the business service, or if the business service has been idle for more than 1800 seconds. During a single session, all repeated invocations by a user are invoked on the same Java Object. The Java Object is borrowed from the Object Pool and is returned to the pool after execution of a request.

You can configure the Java Object idle time in the siebsrvr.properties file. For the 64-bit Java Business Service, the following parameters have been added to the siebsrvr.properties file:

Lang. This parameter defines the language for logging messages. The default value is enu.
JBSLogLevel. This parameter defines the log level for the Java Business Service. The value of this parameter is an integer between 0-5. The default value is 2.
JBSSessKeepAlive. This parameter defines the idle time for a Java Business Service class object in the Object Pool. The default values is 1800 seconds.

Restrictions for Implementing a Java Business Service

When implementing a Java business service, keep in mind the following recommendations and restrictions:

Each business service method invocation is atomic and stateless.
The explicit creation of threads is discouraged. It is not recommended that customers invoke a threaded component from a Java business service.
All data and context required to perform the necessary business functions must be provided as input to the class. The external Java class cannot call back into the Siebel application to obtain additional context.

Troubleshooting the Java Business Service

A common source of errors is the Java CLASSPATH. Remember the following conventions of the Java CLASSPATH:

On UNIX, CLASSPATH entries are separated by a colon (:); on Windows, by a semicolon (;).
If .class files are to be used instead of .jar files, then the root directory (for example, the one containing the com folder) must be listed in the CLASSPATH.

If the Java business service states that the com.siebel.data.SiebelPropertySet class is not found, then the Siebel.jar files are not correctly specified in the CLASSPATH.

If the Java business service implementation cannot be found, then the .class or .jar file containing its code is not properly specified in the CLASSPATH.

To help troubleshoot CLASSPATH errors, you can use one of the following utilities to see where the Application Object Manager or Web client is looking for the .jar files:

Windows: filemon. For more information about filemon, see:
http://www.microsoft.com
UNIX: truss/strace