To deploy and run an Oracle Stream Explorer application, you assemble the application files into an OSGi bundle and deploy the OSGi bundle to a domain on an Oracle Stream Explorer server. A deployed application processes client requests in the domain to which it is deployed.
You can assemble and deploy an application in Oracle JDeveloper, with Oracle Stream Explorer Visualizer, and manually. This chapter explains how to assemble and deploy an application wrapped in an OSGi bundle manually
See Using Visualizer for Oracle Stream Explorer for information about how to assemble and deploy and application and how to deploy and view an application library with Oracle Stream Explorer Visualizer.
This chapter includes the following sections:
An OSGi bundle contains one or more JAR files that contain the Java classes, packages, and libraries that define an Oracle Stream Explorer application and its services and resources (dependencies). You can make the application services and resources available to other bundles. You can also create an OSGi bundle that contains only services and resources that are used by other bundled applications. For example, an OSGi bundle can contain a JDBC driver that is accessed by other applications that execute in the same domain.
An OSGi bundle that contains an application and its resources is an application bundle, and an OSGi bundle that contains only resources is an application library bundle.
An OSGi application bundle contains the following files:
The compiled Java class files that implement the application components, such as event types and event beans.
One or more Oracle Stream Explorer configuration files that contain the component configurations.
Place the configuration files in the META-INF/wlevs
directory of the OSGi bundle JAR file to deploy. For example, /Oracle/Middleware/my_oep/user_projects/domains/<domain>/<server>/applications/<OSGi_Bundle_Symbolic_Name>
.
If you have an application already in the domain directory, then extract the configuration files in the same directory as the application files.
An assembly file that describes all of the application components and how they connect to each other.
Place the assembly file in the OSGi bundle JAR file META-INF/spring
directory.
A MANIFEST.MF
file that describes the contents of the JAR file. This file enables you to make the application resources available to other bundles.
The following directory structure shows the structure of an OSGi application bundle:
Figure 13-1 OSGi Application Bundle Structure
Applications depend on imported packages and libraries, which can be shared with other applications executing in the same domain. You specify OSGi bundle dependencies in the MANIFEST-MF
as follows:
Use the Import-Package
attribute to list imported packages and libraries.
Use the Export-Package
attribute to list packages that other OSGi bundles need to access. These packages are not bundled in and deployed with the application OSGi bundle, but are deployed to the Oracle Stream Explorer server application library directory.
Application libraries make services and resources available to other applications executing in the same domain. You can use application libraries to add functionality such as drivers or foreign stages to your application. A foreign stage is a stage that is in another Oracle Stream Explorer application.
You can add an application library to a project as an embedded JAR file, but using an OSGI application library has the following advantages:
Simplified application assembly and maintenance activities, such as deploying an updated version of the library.
Artifact reuse.
Reduced server disk space consumption.
You deploy application libraries to the Oracle Stream Explorer server into the library and library extensions directories.
By default, the Oracle Stream Explorer server library directory is DOMAIN_DIR/servername/modules
, for example:
/Oracle/Middleware/my_oep/user_projects/domains/mydomain/myserver/modules
Oracle Stream Explorer loads the libraries in the library directory after the components in the library extensions directory, but before the Oracle Stream Explorer applications. If your library is a driver, such as a JDBC driver, put the library in the library extensions directory so it activates in the correct order.
By default, the Oracle Stream Explorer server library extensions directory is DOMAIN_DIR/servername/modules/ext
. For example:
/Oracle/Middleware/my_oep/user_projects/domains/mydomain/myserver/modules/ext
Oracle Stream Explorer loads the libraries in the library extensions directory first at the same time as the Oracle Stream Explorer server core modules. Put drivers in the library extensions library to activate them first to override an older driver or to provide access to an alternative driver. If your library is not a driver, put it in the library directory.
For more information, see Administering Oracle Stream Explorer.
The Oracle Stream Explorer server loads components in the following order at Oracle Stream Explorer server start up time:
Load libraries in the library extensions directory.
Load libraries in the library directory.
Load Oracle Stream Explorer applications.
The Oracle Stream Explorer server loads libraries from both the library extensions directory and the library directory based on the lexical order of the library names. Lexical ordering includes the relative directory name plus JAR file name. For example:
modules/a.jar
starts before modules/b.jar
.
modules/0/my.jar
starts before module/my.jar
because 0/my.jar
comes before my.jar
in lexical order.
This convention enables you to control the order in which the Oracle Stream Explorer server deploys JAR files by organizing JAR files into appropriately named subdirectories of either the library extensions directory or library directory.
As soon as the application deploys, the Oracle Stream Explorer server creates an application configuration history, and the configured adapters start to listen for events.
Configuration changes that you make to Oracle CQL rules or to the Oracle Stream Explorer high availability adapter configuration are recorded in the history. You can view and roll-back (undo) these changes with the Oracle Stream Explorer Visualizer or wlevs.Admin
command-line tool.
You can export the change history to a file and use that file to update your application source with changes made at runtime. For more information, see:
The appC utility is a command-line tool that enables you to build, validate, and compile an application. You can create or modify the various files that comprise an Oracle Stream Explorer project. The appC tool validates against the following schema versions: spring-wlevs-v12_1_3_0.xsd
and spring-beans.xsd
and spring-osgi.xsd
. You must have the JDK installed for this command to work because it depends on the Java compiler.
Note:
The appC tool does not support multiple component configuration files and multiple assembly files. In this case, use the bundle.sh
script or Oracle JDeveloper.
The appC tool validates the configuration and assembly files and the created OSGi bundle to ensure Oracle CQL validation and that the OSGi bundle deploys successfully.
Note:
Currently, appC performs only schema validations with no extensive semantic validations. Custom adapter providers are not validated.
The appC.jar
file is located in /Oracle/Middleware/my_oep/bin
.
Syntax
java -jar appC.jar -cmd [cmd option] -basedir <path to workspace> [arguments]
cmd options
Choose one of the following command options to execute with the -cmd
argument.
buildAll
: Creates the template, generates the manifest, and validates the component configuration file and the assembly file.
createTemplate
: Creates the workspace file structure with either input XML files or template XML files.
generateManifest:
Compiles the input source files and generates the OSGi manifest file based on resulting class files.
validate
: Validates the component configuration and assembly files against their schemas.
arguments
-cmd
: Execute one of the command options. Specify the root directory with -basedir
to indicate the root of the project workspace.
-help
: Prints help information for the command options and arguments to the command line.
-basedir
: The root of the project workspace that you set up previous to using the appC utility.
-cp
: The class path to use to compile the bundle classes.
-config
: The full path to the component configuration file.
-context
: The full to the assembly file.
-manifest
: An optional input manifest file. When no manifest file is specified, the appC utility generates one.
Note:
The underlying BND package used in Oracle Stream Explorer to generate the manifest cannot find reflection usage.
-name
: The name of the project (OSGi bundle name).
-destdir
: The full path to the directory for the output JAR file. The default is basedir
.
-srcdir
: The full path to the source root directory.
-excludedirs
: A comma-separated list of directory names to exclude from the source tree. These directories are subdirectories of the source directory root (srcdir
).
Examples
Compile the input source files and generate the OSGi MANIFEST.MF
file.
java -jar appC.jar -cmd generateManifest -basedir
Create the template, generate the MANIFEST.MF
file, and validate the component configuration file and the assembly file.
java -jar appC.jar -cmd buildALL -basedir
Oracle Stream Explorer provides the bundler.sh
UNIX shell script that you can use to manually assemble an OSGi bundle that provides services and packages to other bundles. For example, you can deploy a JDBC driver in an OSGi bundle JAR file to make it available to other OSGi applications. For more information, see Administering Oracle Stream Explorer.
Note:
There is no Windows support (no bundler.cmd
).
The bundle.sh
shell script reads the source JAR files and creates a target JAR file that includes the content of the source JAR files and a MANIFEST.MF
file with the appropriate bundle-related entries specified. All Java packages found in the source archive are exported to the target bundle.
With bundler.sh
, you can also generate a bundle activator. A bundler activator instantiates one or more classes in the JAR file and registers each instantiated object as an OSGi service. This feature enables component bundles to access and manipulate multiple versions of specific factory classes during execution.
The procedure to manually assembly an OSGi bundle consists of the following steps:
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/Middleware/my_oep/ oep/examples/source/applications/helloworld.
To bundle an application or library into an OSGi bundle manually, you first need to prepare and organize the files to be bundled. For simplicity, this procedure creates a temporary directory that contains the required artifacts, and then jars the contents of this temporary directory. This is a suggested approach, and you are not required to assemble the application this way.
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 Stream Explorer.
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 Stream Explorer 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 Stream Explorer requires that you import the following packages at a minimum:
Import-Package: com.bea.wlevs.adapter.defaultprovider;version="11.1.1", com.bea.wlevs.ede;version="11.1.1", com.bea.wlevs.ede.api;version="11.1.1", com.bea.wlevs.ede.impl;version="11.1.1", org.osgi.framework;version="1.3.0", org.springframework.beans.factory;version="2.5.6", org.apache.commons.logging;version="1.1.0", com.bea.wlevs.spring;version="11.1.1", com.bea.wlevs.util;version="11.1.1", org.springframework.beans;version="2.5.6", org.springframework.util;version="2.0", org.springframework.core.annotation;version="2.5.6", org.springframework.beans.factory;version="2.5.6", org.springframework.beans.factory.config;version="2.5.6", org.springframework.osgi.context;version="1.2.0", org.springframework.osgi.service;version="1.2.0"
Exported packages: Specified with the Export-Package
header. You should specify this header only when you need to share one or more application classes with other deployed applications. A typical example is sharing an event bean.
If possible, you should export packages that include only the interfaces, and not the implementation classes themselves. If other applications use the exported classes, you cannot 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 is the MANIFEST.MF
file from the HelloWorld example application.
Note:
Oracle Stream Explorer requires the following MANIFEST.MF
setting to deploy to an Oracle WebLogic Server container: Bundle-ManifestVersion 2
. This is because Oracle Stream Explorer uses Felix in the Oracle WebLogic Server container.
Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Version: 1.0.0 Bundle-Vendor: Oracle Corporation Bundle-Copyright: Copyright (c) 2006-2009 by Oracle. Export-Package: com.bea.wlevs.event.example.helloworld;version="12.1.2", com.bea.wlevs.example.helloworld;version="12.1.2" Import-Package: com.bea.wlevs.configuration;version="12.1.2" com.bea.wlevs.ede.api;version="12.1.2", com.bea.wlevs.ede.impl;version="12.1.2", com.bea.wlevs.ede.spi;version="12.1.2", com.bea.wlevs.ede;version="12.1.2", com.bea.wlevs.management.spi;version="12.1.2", com.bea.wlevs.spring.support;version="12.1.2", com.bea.wlevs.spring;version="12.1.2", com.bea.wlevs.util;version="12.1.2", org.apache.commons.logging;version="1.1.0", org.springframework.beans.factory.config;version="2.5.6", org.springframework.beans.factory;version="2.5.6", org.springframework.beans;version="2.5.6", org.springframework.core.annotation;version="2.5.6", org.springframework.osgi.context;version="1.2.0", org.springframework.osgi.extensions.annotation;version="1.2.0", org.springframework.osgi.service;version="1.2.0", org.springframework.util;version="2.5.6" Bundle-Name: example.helloworld Bundle-Description: OCEP example helloworld Bundle-SymbolicName: helloworld
When you create your Oracle Stream Explorer applications, you might need to access legacy libraries within existing third-party JAR files. You can ensure access to this legacy code with any of the following approaches:
Bundle-Classpath
The recommended approach is to package the third-party JAR files in your Oracle Stream Explorer application JAR file. You can put the JAR files anywhere you want.
Note:
This approach gives you little control over the order in which JAR files are loaded and it is possible that dependency conflicts may occur. For this reason, Oracle recommends that you use the Oracle Stream Explorer server application library approach instead.
To ensure that your Oracle Stream Explorer application finds the classes in the third-party JAR file, you must update the application class path 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.
Operating System Path
You can create an application library that depends on native code libraries that you do not choose to package as application libraries. In this case, you can put the native code libraries in the operating system path (bootclasspath
) of the Oracle Stream Explorer server. When the server starts, the library bundles that need to call this native code load the native code libraries. For more information, see Administering Oracle Stream Explorer.
-Xbootclasspath
If the JAR files include libraries used by all applications deployed to Oracle Stream Explorer, such as JDBC drivers, you can add the JAR file to the server's boot class path by specifying the -Xbootclasspath/a
option to the java
command in the scripts used to start up an instance of the server.
Note:
This approach gives you little control over the order in which JAR files are loaded and dependency conflicts can occur. Oracle recommends that you use the Oracle Stream Explorer server application library approach instead. For more information, see Operating System Path approach instead.
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 Stream Explorer 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 path name 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. The updated section is shown in bold (in practice, the command should be on one line):
%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
You can refer to a stage that is in another Oracle Stream Explorer application. A stage from another application is called a foreign stage. When you assemble applications that depend on foreign stages, be aware of class path dependencies. Consider the application dependency graph that Figure 13-2 shows.
Figure 13-2 Foreign Stage Dependency Graph
In this example, Application A depends on Application B, Application B depends on Application C, and Application C depends on Application A. Application C declares and exports the MarketEvent
class. Applications A and B import the MarketEvent
class that Application C provides. In this example the MANIFEST.MF
files of the OSGi bundles A and B should contain Require-Bundle: C
.
Note the following:
When you redeploy a foreign stage, you must redeploy all foreign stages that depend on that application or foreign stage.
For example, if you redeploy Application B, you must redeploy Application A.
If there is a class path dependency between one foreign stage and another, when you deploy the foreign stage that declares and exports the shared class, you must redeploy all foreign stages that import the shared class.
For example, if you redeploy Application C, you must also redeploy Application A and B because Application A and B have a class path dependency on Application C (MarketEvent
).
Once you prepare and organize the files, you can use the bundle.sh
shell script to assemble the files into an OSGi bundle and define the activator classes. You can find the bundle.sh
script in the /Oracle/Middleware/my_oep/
bin
directory.
If want to bundle an application library for a new JDBC driver, see Administering Oracle Stream Explorer.
You can find the bundler.sh
script in the /Oracle/Middleware/my_oep/
bin
directory. The following shows the bundler.sh command syntax. Table 13-1 describes the command arguments.
bundler -source JAR -name NAME -version VERSION [-factory CLASS+] [-service INTERFACE+] [-fragmenthost HOST] [-stagedir PATH] [-targetdir PATH] [+import PACKAGE|REGEX+] [-imods REGEX;MODS+] [-import PACKAGE+] [+export PACKAGE|REGEX+] [-emods REGEX;MODS+] [-dimport PACKAGE+] [-explode] [-verbose]
Table 13-1 bundler.sh Command-Line Options
|
Execute the bundler.sh
script to create an OSGi bundle. See Command Location, Syntax, and Arguments.
The following bundle.sh
command shows how to use the bundler.sh
to create an OSGi bundle for an Oracle JDBC driver.
bundler.sh \ -source C:\drivers\com.oracle.ojdbc14_11.2.0.jar \ -name oracle12c \ -version 12.1.3.0 \ -factory oracle.jdbc.xa.client.OracleXADataSource oracle.jdbc.OracleDriver \ -service javax.sql.XADataSource java.sql.Driver \ -targetdir C:\stage
The -source
option specifies a JAR file that is an Oracle driver located in directory C:\drivers
. The name of the generated bundle JAR is the concatenation of the -name
and -version
arguments (oracle10g_11.2.0.jar
) and is created in the C:\stage
directory. The bundle JAR contains the following files:
1465 Thu Jun 29 17:54:04 EDT 2006 META-INF/MANIFEST.MF 1540457 Thu May 11 00:37:46 EDT 2006 com.oracle.ojdbc14_11.2.0.jar 1700 Thu Jun 29 17:54:04 EDT 2006 com/bea/core/tools/bundler/Activator.class
The -factory
option specifies that there are two factory classes to be instantiated and registered as an OSGi service when the bundle activates, each under a separate object class as Table 13-2 shows.
Table 13-2 Factory Class and Service Interfaces
|
The -service
option registers services with a name
property set to oracle12c
and a version
property with a value of 12.1.3.0
. The following example shows the Oracle Stream Explorer server log messages with the service registrations:
... INFO: [Jun 29, 2006 5:54:18 PM] Service REGISTERED: { version=12.1.3.0, name=oracle12c, objectClass=[ javax.sql.XADataSource ], service.id=23 } INFO: [Jun 29, 2006 5:54:18 PM] Service REGISTERED: { version=12.1.3.0, name=oracle12c, objectClass=[ java.sql.Driver ], service.id=24 } INFO: [Jun 29, 2006 5:54:18 PM] Bundle oracle11g STARTED ...
Copy the application library JAR to the appropriate Oracle Stream Explorer server application library directory:
If your bundle is a driver, you put it in the library extensions directory.
If your bundle is not a driver, you can put it in the library directory.
Stop and start the Oracle Stream Explorer server.
After you assemble your Oracle Stream Explorer application or library into an OSGi bundle, you deploy it to an Oracle Stream Explorer server domain. You can deploy an application with Oracle JDeveloper, Oracle Stream Explorer Visualizer, and with the Deployer utility. This section explains how to use the Deployer utility.
With the Deployer utility, you can deploy an application to either a stand-alone or multiserver domain. You can only deploy to a group when the server is part of a multiserver domain (clustering is enabled). You cannot deploy to a group when the server is part of a standalone server domain (clustering is disabled).
Oracle Stream Explorer uses the deployments.xml
file to internally maintain a list of deployed 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 Schema Reference for Oracle Stream Explorer for information about this file. The information is provided for your information only; Oracle does not recommend updating the deployments.xml
file manually.
Before you Begin
Be sure you have configured Jetty for the Oracle Stream Explorer instance to which you are deploying your application. For more information, see Administering Oracle Stream Explorer.
Open a command window and update your CLASSPATH
variable to include the wlevsdeploy.jar JAR
file, which is in the following directory. The Deployer utility is in the JAR file.
/Oracle/Middleware/my_oep/bin
Deploy an OSGi Bundle with the Deployer Utility
After the OSGi bundle successfully installs and all initialization tasks complete, Oracle Stream Explorer starts the application and the adapter components listen for incoming events.
Assemble your OSGi bundle as described in Assemble an OSGi Bundle with bundle.sh.
Open a command window and run the Deployer utility as follows. Keep everything on one line.
prompt> java -jar wlevsdeploy.jar -url http://host:port/wlevsdeployer -user user -password password -install application_jar_file
host
: The name of the computer where the Oracle Stream Explorer server is running.
port
: The port number where Oracle Stream Explorer listens. The default value is 9002
. This port is specified in the DOMAIN_DIR
/config/
file that describes the Oracle Stream Explorer domain. The port number is the value of the <Port>
child element of the <Netio>
element in the file:
<Netio> <Name>NetIO</Name> <Port>9002</Port> </Netio>
user
: The user name of the Oracle Stream Explorer administrator.
password
: The password of the Oracle Stream Explorer administrator.
application_jar_file
: The OSGi bundle. The OSGi bundle must be located on the same computer where you execute the Deployer utility. For example, if Oracle Stream Explorer is running on host ariel
, listening on port 9002
, user name 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 the following. Keep everything on one line.
prompt> java -jar wlevsdeploy.jar -url http://ariel:9002/wlevsdeployer
-user wlevs -password wlevs -install /applications/myapp_1.0.0.0.jar
The Deployer utility provides additional options over what was described here to resume, suspend, update, uninstall and deploy an OSGi bundle to a specified group of multiserver domains. For more information, see Administering Oracle Stream Explorer.