|
|
This section contains information on the following subjects:
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 Complex Event Processing, or Oracle CEP for short. 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 JAR file that contains the following artifacts:
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.
The EPN assembly file must be located in the META-INF/spring directory of the OSGi bundle JAR file.
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 Assembling an Oracle CEP Application: Main Steps 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 Deploying Oracle CEP Applications: Main Steps.
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 Additional Information about Spring and OSGi for links to reference and conceptual information about Spring and OSGi. |
Assembling an Oracle CEP application refers to bundling the artifacts that make up the application into an
OSGi bundle JAR file. These artifacts include compiled Java classes, the XML files that configure the components of the application (such as the processors or adapters), the EPN assembly file, and the MANIFEST.MF file.
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.
See Additional Information about Spring and OSGi for links to reference and conceptual information about Spring and OSGi.
| 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 WLEVS_HOME\samples\source\applications\helloworld, where WLEVS_HOME refers to the main installation directory, such as d:\beahome\wlevs30. |
To assemble an Oracle CEP application:
output:prompt> mkdir output
output directory.output/META-INF/spring directory.output/META-INF/spring directory.See Creating the EPN Assembly File for details about this file.
output/META-INF/wlevs directory.output/META-INF/wlevs directory. You create these XML files during the course of creating your application, as described in Overview of the Oracle Complex Event Processing Programming Model.MANIFEST.MF file that contains descriptive information about the bundle. See Creating the MANIFEST.MF File.
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 for information on using the jar task or the
J2SE documentation for information on using the jar command-line tool.
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:
Bundle-Name header.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.Bundle-Version header.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"
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
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:
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.
-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 main domain directory. The out-of-the-box sample domains are located in WLEVS_HOME/samples/domains, and the user domains are located in BEA_HOME/user_projects/domains, where WLEVS_HOME refers to the main Oracle CEP installation directory, such as d:\beahome\wlevs30, and BEA_HOME refers to the directory above WLEVS_HOME, such as d:\beahome.
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
The following procedure describes how to deploy an application to Oracle CEP using the Deployer utility. It is assumed in the procedure that you have assembled your application as described in Assembling an Oracle CEP Application: Main Steps.
See Deployer Command-Line Reference for complete reference information about the Deployer utility, in particular options to the utility that are supported in addition to the ones described in this section. See Additional Information about Spring and OSGi for links to reference and conceptual information about Spring and OSGi.
wlevsdeploy.jar JAR file, located in the WLEVS_HOME/bin directory where, WLEVS_HOME refers to the main Oracle CEP installation directory, such as /beahome/wlevs30.| Note: | If you are running the deployer utility on a remote computer, see Running the Deployer Utility Remotely for instructions. |
Deployer utility using the following syntax to install your application:prompt> java-jar wlevsdeploy.jar-url http://host:port/wlevsdeployer -user user -password password
-installapplication_jar_file
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; its value is 9002 by default. This port is specified in the config.xml file that describes your Oracle CEP domain, located in the DOMAIN_DIR/config directory, 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 Assembling an Oracle CEP Application: Main Steps.
For example, if Oracle CEP is running on host ariel, listening at 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.jarAfter 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. For details, see Deployer Command-Line Reference.
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
XSD Schema For the Deployment File for information about this file. This information is provided for your information only; Oracle does not recommend updating the deployments.xml file manually.
|