Embedded Java Support

This feature provides the ability to write CEP plug-ins in Java.

This feature provides a Java Software Development Kit (SDK) for building CEP plug-ins: input and output in-process adapters (in both regular and guaranteed delivery mode), and remote procedure calls (RPCs). In-process adapters run within the Complex Event Processing (CEP) server process. Due to the communications overhead involved with out of process adapters, in-process adapters tend to have better performance.

In-process adapters and RPCs for Sybase CEP can be written in C/C++ or Java. The Java SDK and the C/C++ SDK are functionally equivalent. Thus, Java and C/C++ in-process adapters have functionally identical run-time behavior. But the C/C++ adapters may have slightly better performance.

This feature requires Java 1.5 or higher. The Sybase CEP package does not include a Java Runtime Environment (JRE). You must install an appropriate Java package on the same machine as the Sybase CEP server to use the Embedded Java Support. After installing Java, you will need to make the Java Virtual Machine (JVM) shared library available. On Windows, add the directory containing the jvm.dll file to the PATH environment variable. On Linux or Solaris, add the directory containing the file to the LD_LIBRARY_PATH environment variable. If your environment uses the LD_LIBRARY_PATH_64 environment variable, add the directory containing the jvm.so file to it.

The API for the Java SDK is described completely in its accompanying Javadoc.

When ESD#1 is applied to an existing CEP R4 installation, it puts a newc8-server.conf.src file in the CEP_INSTALL/SybaseC8/server/conf directory. This file includes a new section (that looks like the following) to enable the JVM for the CEP server.

 
<section name="Java">
     <!-- The flag control whether JVM will be enabled or not, default value is false
       -->
     <preference name="JVMEnabled" value="false"/>

     <!-- The flag control whether Java adapter will be enabled or not, default value
          is true
       -->
     <preference name="JavaAdapterEnabled" value="true"/>

     <!-- The flag control whether Java rpc will be enabled or not, default value
          is true
       -->
     <preference name="JavaRpcEnabled" value="true"/>

     <!-- If ignoreUnrecognized is true, CreateJavaVM ignore all unrecognized
          option strings that begin with "-X" or "_".  If ignoreUnrecognized is false,
          CreateJavaVM returns Error as soon as it encounters any unrecognized
          option strings; default value is true
      -->
     <preference name="ignoreUnrecognized" value="true"/>

     <!-- configure all vm parameters separated by " " except system property which
          begin with "-D"
       -->
     <preference name="VMArgs" value="-verbose:jni"/>

     <! This subsection is used to configure the system property -->
     <section name="SystemProperty">
          <!-- The list of semicolon(;) separated paths which can be used to search
               java classes
            -->
          <preference name="java.class.path"
           value="CONFIG_INSTALL_FOLDER/sdk/java5/lib/log4j-1.2.15.jar;
           CONFIG_INSTALL_FOLDER/sdk/java5/lib/jaxrpc.jar;
           CONFIG_INSTALL_FOLDER/sdk/java5/c8-sdk-java5.jar;"/>
     </section>
</section>

To use the Embedded Java feature, copy this section of c8-server.conf.src file to the same spot in the c8-server.conf file (located in the same directory). Edit the c8-server.conf file:

change the value of the JVMEnabled preference to true
change the string CONFIG_INSTALL_FOLDER to the folder in which CEP is installed

When ESD#1 is installed, it puts a new c8-service.xml file, which includes an example configuration of a Java RPC plug-in, in the CEP_INSTALL/SybaseC8/server/conf directory. The example looks like the following code fragment:

<!-- sample service configuration for java rpc
     Please don't change the value of the parameters RpcLibrary, RpcInitCallback,
     RpcExecuteCallback, RpcShutdownCallback
     Please change the value of parameter "JavaRpcClass" to your java rpc's class name
     Please change the value of parameter "ClassPath" to the path that contains your
     rpc class, if it already contained in class path configured in c8-server.conf,
     you can simply remove this parameter
  -->
  <!--  <Service Name="TestJavaRpc" Type="REMOTESERVICE">
    <Description>Sample service configuration for Java Rpc</Description>
    <Param Name="RpcLibrary">c8_java_rpc_lib</Param>
    <Param Name="RpcInitCallback">c8_java_rpc_initialize</Param>
    <Param Name="RpcExecuteCallback">c8_java_rpc_execute</Param>
    <Param Name="RpcShutdownCallback">c8_java_rpc_shutdown</Param>

    <Param Name="JavaRpcClass">com.sybase.c8.rpc.TestRpc</Param>
    <Param Name="ClassPath"></Param>
  </Service>
  -->

An example ADL file for a Java in-process adapter, c8_java_adapter_demo.adl, is located in the CEP_INSTALL/SybaseC8/server/plugin directory.

User developed RPC plug-ins or in-process adapters can be a set of .class files or a single .jar file. A plug-in or adapter can have dependencies on other .jar files. Locations of all the files must be added to the classpath. Multiple locations are separated by semicolons on Windows and by colons on Linux and Solaris. The classpath to find the file(s) for user-developed Java RPC plug-ins and in-process adapters can be set using any of the following methods:

changing the value of the java.class.path preference in the c8-server.conf file
setting the"ClassPath" parameter for the Java RPC plug-in in the c8-services.xml file
changing the "ClassPath" parameter's default value in the in-process adapter's ADL file

These methods of setting the classpath are provided because this feature does not use the CLASSPATH environment variable to load the Java adapter's classes or jars.

When searching for in-process Java adapters, classpaths are read in the following order:

First, the classpath specified by the ClassPath parameter in the in-process adapter's ADL file is read.
If nothing is found, the classpath specified by the java.class.path preference in the c8-server.conf file is read.
If nothing is found, "ClassNotFoundException" exception is thrown.

When searching for a Java RPC, classpaths are read in the following order:

First, the classpath specified by the ClassPath parameter in the c8-services.xmlfile is read.
If nothing is found, the classpath specified by the java.class.path preference ins the c8-server.conf file is read.
If nothing is found, a "ClassNotFoundException" exception is thrown.

ESD#1 includes the following additional example files:

c8-in-process-adapters.jar is a binary of the example Java in-process adapter.
c8-in-process-adapters-src.jar contains the source files for the example Java in-process adapter (unzip before using).
c8-rpcs.jar is a binary of the example Java RPC plug-in.
c8-rpcs-src.jar contains the source files for the example Java RPC plug-in (unzip before using).