14 Assembling and Deploying Oracle CEP Applications

This section contains information on the following subjects:

Section 14.1, "Overview of Application Assembly and Deployment"
Section 14.2, "Assembling an Oracle CEP Application"
Section 14.3, "Deploying Oracle CEP Applications"

14.1 Overview of Application Assembly and Deployment

The term application assembly refers to the process of packaging the components of an application, such as the Java files and XML configuration files, into an OSGI bundle that can be deployed to Oracle CEP. The term application deployment refers to the process of making an application available for processing client requests in an Oracle CEP domain.

In the context of Oracle CEP assembly and deployment, an application is defined as an OSGi bundle (see http://www2.osgi.org/javadoc/r4/org/osgi/framework/Bundle.html) JAR file that contains the following artifacts:

The compiled Java class files that implement some of the components of the application, such as the adapters, adapter factory, and POJO that contains the business logic.
One or more Oracle CEP configuration XML files that configure the components of the application. The only type of component that is required to have a configuration file is the complex event processor; all other components (adapters and streams) do not require configuration files if the default configuration of the component is adequate. You can combine all configuration files into a single file, or separate the configuration for individual components in their own files.

The configuration files must be located in the META-INF/wlevs directory of the OSGi bundle JAR file if you plan to dynamically deploy the bundle. If you have an application already present in the domain directory, then the configuration files need to be extracted in the same directory.
An EPN assembly file that describes all the components of the application and how they are connected to each other.

The EPN assembly file must be located in the META-INF/spring directory of the OSGi bundle JAR file.
A MANIFEST.MF file that describes the contents of the JAR.

The OSGI bundle declares dependencies by specifying imported and required packages. It also provides functionality to other bundles by exporting packages. If a bundle is required to provide functionality to other bundles, you must use Export-Package to allow other bundles to reference named packages. All packages not exported are not available outside the bundle.

See Section 14.2, "Assembling an Oracle CEP Application" for detailed instructions on creating this deployment bundle.

After you have assembled the application, you deploy it by making it known to the Oracle CEP domain using the Deployer utility (packaged in the wlevsdeploy.jar file). For detailed instructions, see Section 14.3, "Deploying Oracle CEP Applications."

Once the application is deployed to Oracle CEP, the configured adapters immediately start listening for events for which they are configured, such as financial data feeds and so on.

Note:

Oracle CEP applications are built on top of the Spring Framework and OSGi Service Platform and make extensive use of their technologies and services. See Appendix A, "Additional Information about Spring and OSGi," for links to reference and conceptual information about Spring and OSGi.

14.2 Assembling an Oracle CEP Application

Assembling an Oracle CEP application refers to bundling the artifacts that make up the application into an OSGi bundle JAR file as http://www2.osgi.org/javadoc/r4/org/osgi/framework/Bundle.html describes. These artifacts include:

compiled Java classes
Oracle CEP component configuration files that configure application components (such as the processors or adapters)
EPN assembly file
MANIFEST.MF file

See Appendix A, "Additional Information about Spring and OSGi," for links to reference and conceptual information about Spring and OSGi.

14.2.1 Assembling an Oracle CEP Application Using Oracle CEP IDE for Eclipse

You can use Oracle CEP IDE for Eclipse to easily assemble your Oracle CEP application.

For more information, see:

14.2.2 Assembling an Oracle CEP Application Manually

Optionally, you can assemble your Oracle CEP application manually.

For simplicity, the following procedure creates a temporary directory that contains the required artifacts, and then jars up the contents of this temporary directory. This is just a suggestion and you are not required, of course, to assemble the application using this method.

Note:

See the HelloWorld example source directory for a sample build.xml Ant file that performs many of the steps described below. The build.xml file is located in ORACLE_CEP_HOME\ocep_11.1\samples\source\applications\helloworld, where ORACLE_CEP_HOME refers to the main Oracle CEP installation directory, such as d:\oracle_cep.

To assemble an Oracle CEP application manually:

Open a command window and set your environment as described in "Setting Your Development Environment" in the Oracle CEP Getting Started.
Create an empty directory, such as output:
```
prompt> mkdir output
```
Compile all application Java files into the output directory.
Create an output/META-INF/spring directory.
Copy the EPN assembly file that describes the components of your application and how they are connected into the output/META-INF/spring directory.

See Section 1.4, "Creating the EPN Assembly File" for details about this file.
Create an output/META-INF/wlevs directory.
Copy the XML files that configure the components of your application (such as the processors or adapters) into the output/META-INF/wlevs directory.

You create these XML files during the course of creating your application, as described in Section 1.1, "Overview of the Oracle CEP Programming Model."
Create a MANIFEST.MF file that contains descriptive information about the bundle.

See Section 14.2.2.1, "Creating the MANIFEST.MF File."
If you need to access third-party JAR files from your Oracle CEP application, see Section 14.2.2.2, "Accessing Third-Party JAR Files."
Create a JAR file that contains the contents of the output directory.

Be sure you specify the MANIFEST.MF file you created in the previous step rather than the default manifest file.

You can name the JAR file anything you want. In the Oracle CEP examples, the name of the JAR file is a combination of Java package name and version, such as:
```
com.bea.wlevs.example.helloworld_1.0.0.0.jar
```
Consider using a similar naming convention to clarify which bundles are deployed to the server.

See the Apache Ant documentation at http://ant.apache.org/manual/CoreTasks/jar.html for information on using the jar task or the J2SE documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/jar.html for information on using the jar command-line tool.

14.2.2.1 Creating the MANIFEST.MF File

The structure and contents of the MANIFEST.MF file is specified by the OSGi Framework. Although the value of many of the headers in the file is specific to your application or business, many of the headers are required by Oracle CEP.

In particular, the MANIFEST.MF file defines the following:

Application name—Specified with the Bundle-Name header.
Symbolic application name—Specified with the Bundle-SymbolicName header.

Many of the Oracle CEP tools, such as the wlevs.Admin utility and JMX subsystem, use the symbolic name of the bundle when referring to the application.
Application version—Specified with the Bundle-Version header.

Imported packages—Specified with the Import-Package header.

Oracle CEP requires that you import the following packages at a minimum:

Import-Package:  
 com.bea.wlevs.adapter.defaultprovider;version="2.0.0.0",
 com.bea.wlevs.ede;version="2.0.0.0",
 com.bea.wlevs.ede.api;version="2.0.0.0",
 com.bea.wlevs.ede.impl;version="2.0.0.0",
 org.osgi.framework;version="1.3.0",
 org.springframework.beans.factory;version="2.0.5",
 org.apache.commons.logging;version="1.1.0",
 com.bea.wlevs.spring;version="2.0.0.0",
 com.bea.wlevs.util;version="2.0.0.0",
 org.springframework.beans;version="2.0.5",
 org.springframework.util;version="2.0",
 org.springframework.core.annotation;version="2.0.5",
 org.springframework.beans.factory;version="2.0.5",
 org.springframework.beans.factory.config;version="2.0.5",
 org.springframework.osgi.context;version="1.0.0",
 org.springframework.osgi.service;version="1.0.0"

If you have extended the configuration of an adapter, then you must also import the following packages:

 javax.xml.bind;version="2.0",
 javax.xml.bind.annotation;version=2.0,
 javax.xml.bind.annotation.adapters;version=2.0,
 javax.xml.bind.attachment;version=2.0,
 javax.xml.bind.helpers;version=2.0,
 javax.xml.bind.util;version=2.0,
 com.bea.wlevs.configuration;version="2.0.0.0",
 com.bea.wlevs.configuration.application;version="2.0.0.0",
 com.sun.xml.bind.v2;version="2.0.2"

Exported packages—Specified with the Export-Package header. You should specify this header only if you need to share one or more application classes with other deployed applications. A typical example is sharing an event type JavaBean.

If possible, you should export packages that include only the interfaces, and not the implementation classes themselves. If other applications are using the exported classes, you will be unable to fully undeploy the application that is exporting the classes.

Exported packages are server-wide, so be sure their names are unique across the server.

The following complete MANIFEST.MF file is from the HelloWorld example, which extends the configuration of its adapter:

Manifest-Version: 1.0
Archiver-Version:
Build-Jdk: 1.5.0_06
Extension-Name: example.helloworld
Specification-Title: 1.0.0.0
Specification-Vendor: Oracle.
Implementation-Vendor: Oracle.
Implementation-Title: example.helloworld
Implementation-Version: 1.0.0.0
Bundle-Version: 2.0.0.0
Bundle-ManifestVersion: 1
Bundle-Vendor: Oracle.
Bundle-Copyright: Copyright (c) 2006 by Oracle.
Import-Package: com.bea.wlevs.adapter.defaultprovider;version="2.0.0.0",
 com.bea.wlevs.ede;version="2.0.0.0",
 com.bea.wlevs.ede.impl;version="2.0.0.0",
 com.bea.wlevs.ede.api;version="2.0.0.0",
 org.osgi.framework;version="1.3.0",
 org.apache.commons.logging;version="1.1.0",
 com.bea.wlevs.spring;version="2.0.0.0",
 com.bea.wlevs.util;version="2.0.0.0",
 net.sf.cglib.proxy,
 net.sf.cglib.core,
 net.sf.cglib.reflect,
 org.aopalliance.aop,
 org.springframework.aop.framework;version="2.0.5",
 org.springframework.aop;version="2.0.5",
 org.springframework.beans;version="2.0.5",
 org.springframework.util;version="2.0",
 org.springframework.core.annotation;version="2.0.5",
 org.springframework.beans.factory;version="2.0.5",
 org.springframework.beans.factory.config;version="2.0.5",
 org.springframework.osgi.context;version="1.0.0",
 org.springframework.osgi.service;version="1.0.0",
 javax.xml.bind;version="2.0",
 javax.xml.bind.annotation;version=2.0,
 javax.xml.bind.annotation.adapters;version=2.0,
 javax.xml.bind.attachment;version=2.0,
 javax.xml.bind.helpers;version=2.0,
 javax.xml.bind.util;version=2.0,
 com.bea.wlevs.configuration;version="2.0.0.0",
 com.bea.wlevs.configuration.application;version="2.0.0.0",
 com.sun.xml.bind.v2;version="2.0.2"
Bundle-Name: example.helloworld
Bundle-Description: WLEvS example helloworld
Bundle-SymbolicName: helloworld

14.2.2.2 Accessing Third-Party JAR Files

When creating your Oracle CEP applications, you might need to access legacy libraries within existing third-party JAR files. There are two ways to ensure access to this legacy code:

Section 14.2.2.2.1, "Accessing Third-Party JAR Files Using Bundle-Classpath"
Section 14.2.2.2.2, "Accessing Third-Party JAR Files Using -Xbootclasspath/a"

14.2.2.2.1 Accessing Third-Party JAR Files Using Bundle-Classpath

The recommended approach is to package the third-party JAR files in your Oracle CEP application JAR file. You can put the JAR files anywhere you want.

However, to ensure that your Oracle CEP application finds the classes in the third-party JAR file, you must update the application classpath by adding the Bundle-Classpath header to the MANIFEST.MF file. Set Bundle-Classpath to a comma-separate list of the JAR file path names that should be searched for classes and resources. Use a period (.) to specify the bundle itself. For example:

Bundle-Classpath: ., commons-logging.jar, myExcitingJar.jar, myOtherExcitingJar.jar

If you need to access native libraries, you must also package them in your JAR file and use the Bundle-NativeCode header of the MANIFEST.MF file to specify their location in the JAR.

14.2.2.2.2 Accessing Third-Party JAR Files Using -Xbootclasspath/a

If the JAR files include libraries used by all applications deployed to Oracle CEP, such as JDBC drivers, you can add the JAR file to the server's boot classpath by specifying the -Xbootclasspath/a option to the java command in the scripts used to start up an instance of the server.

The name of the server start script is startwlevs.cmd (Windows) or startwlevs.sh (UNIX), and the script is located in the server directory of your domain directory. The out-of-the-box sample domains are located in ORACLE_CEP_HOME/ocep_11.1/samples/domains, and the user domains are located in ORACLE_CEP_HOME/user_projects/domains, where ORACLE_CEP_HOME refers to the main Oracle CEP installation directory, such as d:\oracle_cep.

Update the start script by adding the -Xbootclasspath/a option to the java command that executes the wlevs_2.0.jar file. Set the -Xbootclasspath/a option to the full pathname of the third-party JAR files you want to access system-wide.

For example, if you want all deployed applications to be able to access a JAR file called e:\jars\myExcitingJAR.jar, update the java command in the start script as follows (updated section shown in bold):

  %JAVA_HOME%\bin\java -Dwlevs.home=%USER_INSTALL_DIR% -Dbea.home=%BEA_HOME%  -Xbootclasspath/a:e:\jars\myExcitingJAR.jar -jar "%USER_INSTALL_DIR%\bin\wlevs_2.0.jar" -disablesecurity %1 %2 %3 %4 %5 %6

14.3 Deploying Oracle CEP Applications

After you assemble your Oracle CEP application, you deploy it to an Oracle CEP server domain.

This section describes:

Section 14.3.1, "How to Deploy an Oracle CEP Application Using Oracle CEP IDE for Eclipse"
Section 14.3.2, "How to Deploy an Oracle CEP Application Using Oracle CEP Visualizer"
Section 14.3.3, "How to Deploy an Oracle CEP Application Using the Deployer Utility"

For more information, see:

"Deploying an Oracle CEP Application to a Standalone-Server Domain" in the Oracle CEP Administrator's Guide
"Deploying an Oracle CEP Application to a Multi-Server Domain" in the Oracle CEP Administrator's Guide

14.3.1 How to Deploy an Oracle CEP Application Using Oracle CEP IDE for Eclipse

You can deploy an Oracle CEP application using Oracle CEP IDE for Eclipse.

Using the Oracle CEP IDE for Eclipse, you can deploy an application to a stand-alone domain. To deploy an application to a multi-server domain, see:

Section 14.3.2, "How to Deploy an Oracle CEP Application Using Oracle CEP Visualizer"
Section 14.3.3, "How to Deploy an Oracle CEP Application Using the Deployer Utility"

To deploy an Oracle CEP application using Oracle CEP IDE for Eclipse:

Assemble your Oracle CEP application.

See Section 14.2, "Assembling an Oracle CEP Application."
Use the Oracle CEP IDE for Eclipse to deploy your application.

See Section 4.3.5, "How to Deploy an Application to an Oracle CEP Server".

14.3.2 How to Deploy an Oracle CEP Application Using Oracle CEP Visualizer

The simplest way to deploy an Oracle CEP application to an Oracle CEP server domain is to use the Oracle CEP Visualizer.

Using the Oracle CEP Visualizer, you can deploy an application to either a stand-alone or multi-server domain.

To deploy an Oracle CEP application using Oracle CEP Visualizer:

Assemble your Oracle CEP application.

See Section 14.2, "Assembling an Oracle CEP Application."
Start the Oracle CEP Visualizer.

See Section 4.3.8, "How to Start the Oracle CEP Visualizer from Oracle CEP IDE for Eclipse".
Use the Oracle CEP Visualizer to deploy your application.

See "Deploying an Application" in the Oracle CEP Visualizer User's Guide.

14.3.3 How to Deploy an Oracle CEP Application Using the Deployer Utility

The following procedure describes how to deploy an application to Oracle CEP using the Deployer command-line utility.

Using the Deployer, you can deploy an application to either a stand-alone or multi-server domain.

For more information, see "Deployer Command-Line Reference" in the Oracle CEP Administrator's Guide.

To deploy an Oracle CEP application using the Deployer utility:

Assemble your Oracle CEP application.

See Section 14.2, "Assembling an Oracle CEP Application."
Open a command window and set your environment as described in "Setting Your Development Environment" in the Oracle CEP Getting Started.
Update your CLASSPATH variable to include the wlevsdeploy.jar JAR file, located in the ORACLE_CEP_HOME/ocep_11.1/bin directory where, ORACLE_CEP_HOME refers to the main Oracle CEP installation directory, such as /oracle_cep.

Note:
If you are running the Deployer on a remote computer, see "Running the Deployer Utility Remotely" in the Oracle CEP Administrator's Guide.
Be sure you have configured Jetty for the Oracle CEP instance to which you are deploying your application.

For more information, see "Configuring Jetty for Oracle CEP" in the Oracle CEP Administrator's Guide.
In the command window, run the Deployer utility using the following syntax to install your application:
```
prompt> java -jar wlevsdeploy.jar -url http://host:port/wlevsdeployer -user user -password password -install application_jar_file
```
where
- host refers to the hostname of the computer on which Oracle CEP is running.
- port refers to the port number to which Oracle CEP listens; default value is 9002.
  
  This port is specified in the DOMAIN_DIR/config/config.xml file that describes your Oracle CEP domain, where DOMAIN_DIR refers to your domain directory.
  
  The port number is the value of the <Port> child element of the <Netio> element:
```
<Netio>
    <Name>NetIO</Name>
    <Port>9002</Port>
</Netio>
```
- user refers to the username of the Oracle CEP administrator.
- password refers to the password of the Oracle CEP administrator.
- application_jar_file refers to your application JAR file, assembled into an OSGi bundle as described in Section 14.2, "Assembling an Oracle CEP Application." This file must be located on the same computer from which you execute the Deployer utility.
  
  For example, if Oracle CEP is running on host ariel, listening on port 9002, username and password of the administrator is wlevs/wlevs, and your application JAR file is called myapp_1.0.0.0.jar and is located in the /applications directory, then the command is:
```
prompt> java -jar wlevsdeploy.jar -url http://ariel:9002/wlevsdeployer -user wlevs -password wlevs -install /applications/myapp_1.0.0.0.jar
```
After the application JAR file has been successfully installed and all initialization tasks completed, Oracle CEP automatically starts the application and the adapter components immediately start listening for incoming events.

The Deployer utility provides additional options to resume, suspend, update, and uninstall an application JAR file, as well as deploy an application to a specified group of a multi-server domain. For more information, see "Deployer Command-Line Reference" in the Oracle CEP Administrator's Guide.

Oracle CEP uses the deployments.xml file to internally maintain its list of deployed application OSGi bundles. This file is located in the DOMAIN_DIR/servername directory, where DOMAIN_DIR refers to the main domain directory corresponding to the server instance to which you are deploying your application and servername refers to the actual server. See Appendix B, "Deployment Schema deployment.xsd" for information about this file. This information is provided for your information only; Oracle does not recommend updating the deployments.xml file manually.