This chapter provides an overview of administering Oracle Event Processing, introducing Oracle Event Processing servers and domains and server lifecycle, as well as server configuration, administration tools and tasks.
This chapter includes the following sections:
Section 1.1, "Understanding Oracle Event Processing Servers and Domains"
Section 1.2, "Understanding Oracle Event Processing Server Lifecycle"
Section 1.3, "Understanding Oracle Event Processing Server Configuration"
Section 1.4, "Understanding Oracle Event Processing Server Administration Tools"
Section 1.5, "Understanding Oracle Event Processing Server Administration Tasks"
An Oracle Event Processing server consists of logically related resources and services to which you deploy Oracle Event Processing applications. Services include:
Network Input/Output (I/O)—server and client Internet Protocol (IP) port access, IPv4 and IPv6 support, and a variety of blocking and non-blocking network I/O providers.
Security—security services such as SSL, password stores, and authentication and authorization providers.
Jetty—HTTP server.
Java Management Extensions (JMX)—to provide programmatic access to Oracle Event Processing server and application behavior.
JDBC datasources—to access relational databases to store events for event record and playback, to access a table as an event source for Oracle CQL queries, and to join a table in EPL queries.
HTTP publish-subscribe server—to push event messages to subscribed clients such as the Oracle Event Processing Visualizer and your own Web 2.0 applications.
logging—to support monitoring and troubleshooting server and application operation.
All the files that apply to a server are contained in a single server directory. The main configuration file for the server is called config.xml
—this is where you configure the server's services and specify to which domain the server belongs. For more information, see Section 1.3.1, "Oracle Event Processing Server Configuration Files".
An Oracle Event Processing domain is the management unit of a set of one or more servers. There are two types of domain:
Standalone-server domain—A domain that contains a single server. This is the type of domain created by default by the Configuration Wizard and is the starting point for a multi-server domain.
For more information, see Chapter 3, "Administering Oracle Event Processing Standalone-Server Domains".
Multi-server domain—A domain that contains two or more servers that share the same multicast address and port and share a security provider. Multi-server domains enable high availability for Oracle Event Processing applications. When you deploy an application to a multi-server domain, the application is replicated to each server in the domain.
The servers in a multi-server domain can be located on the same computer or on separate computers; what ties the servers together in a multi-server domain is that they have the same multicast address and port and belong to the same domain, all of which are configured in the server's config.xml
file.
For more information, see:
Figure 1-1 shows a state diagram for the Oracle Event Processing server lifecycle. In this diagram, the state names (STARTING
, RUNNING
, and SHUTTING_DOWN
) correspond to the ServerRuntimeMBean
method getState()
return values. These states are specific to Oracle Event Processing; they are not OSGi bundle states.
Figure 1-1 Oracle Event Processing Server Lifecycle State Diagram
Note:
For information on Oracle Event Processing application lifecycle, see "Oracle Event Processing Application Lifecycle" in the Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse.
This section describes the lifecycle of an application deployed to Oracle Event Processing and the sequence of com.bea.wlevs.ede.api
API callbacks. The lifecycle description is broken down into actions that a user performs, including:
Section 1.2.1, "User Action: Start Oracle Event Processing Server"
Section 1.2.2, "User Action: Stop Oracle Event Processing Server"
This information explains how Oracle Event Processing manages an application's lifecycle so that you can better use the lifecycle APIs in your application. For a description of these APIs (such as RunnableBean
and SuspendableBean
), see:
"Oracle Event Processing APIs" in the Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse
Oracle Fusion Middleware Java API Reference for Oracle Event Processing
After you start the Oracle Event Processing server, it performs the following actions:
Starts core engine bundles.
Starts Oracle Event Processing bundles.
Registers MBeans.
Oracle Event Processing server state is now STARTING
.
Starts application bundles.
Oracle Event Processing server state is now RUNNING
.
After you shutdown the Oracle Event Processing server, it performs the following actions:
Oracle Event Processing server state is SHUTTING_DOWN
.
Unregister ServerRuntimeMBean
.
Oracle Event Processing server ceases to have a state.
Shuts down Oracle Event Processing bundles.
Shuts down application bundles.
Shuts down core engine bundles.
Oracle Event Processing server configuration falls into two categories:
configuring a server
configuring the applications you deploy to a server
For each configuration category, you can perform the configuration task:
Statically: by editing an XML file manually.
Using this approach, you must restart the server or redeploy the application after making a change.
Dynamically: by manipulating management beans (MBeans) using Oracle Event Processing Visualizer, wlevs.Admin
command-line utility, or programmatically using JMX,
Using this approach, you do not have to restart the server or redeploy the application after making a change
You configure the server statically by:
Stopping the Oracle Event Processing server.
Editing the Oracle Event Processing server config.xml
file located in the server's domain directory
Starting the Oracle Event Processing server.
There are some server configuration tasks that you can only perform statically, such as configuring Jetty.
There are some server configuration tasks that you can perform dynamically using management beans (MBeans). In this case you do not have to manually stop and start the server for the changes to take effect.
You can dynamically configure Oracle Event Processing servers and applications using Oracle Event Processing Visualizer, wlevs.Admin
command line utility, or your own Java code using Oracle Event Processing standards-based interfaces that are fully compliant with JMX APIs (http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/
).
Typically, you statically configure an application when you initially create it, as described in Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse. In particular, you configure the event processing network (EPN) of the application by creating the EPN assembly file, and configure individual components of the application (adapters, channels, and processors) by creating their configuration files.
After you deploy an application, you can dynamically change its configuration, as well as the configuration of its individual components, by manipulating the MBeans that the Oracle Event Processing server automatically creates for the application and its components. A typical task is to dynamically configure the Oracle CQL rules for the processors of a deployed application. You do this using Oracle Event Processing Visualizer, wlevs.Admin command-line utility, or JMX.
This section describes:
Section 1.3.1, "Oracle Event Processing Server Configuration Files"
Section 1.3.4, "Configuring the Oracle Event Processing Server bootclasspath"
For more information, see:
Section 1.5.3, "Configuring Oracle Event Processing Servers"
Oracle Fusion Middleware Visualizer User's Guide for Oracle Event Processing
By default, the Configuration Wizard creates domains in the ORACLE_CEP_HOME
/user_projects/domains
directory, where ORACLE_CEP_HOME
refers to the Oracle Event Processing installation directory such as d:\oracle_cep
.
For example, d:\oracle_cep\user_projects\domains\my_domain
, where my_domain
is the a domain directory. Each Oracle Event Processing server you create in this domain will have a subdirectory in my_domain such as c:\oracle_cep\user_projects\domains\my_domain\server1
.
The following list describes the important files and directories of a server in a domain, relative to the server directory (such as c:\oracle_cep\user_projects\domains\my_domain\server1
):
deployments.xml
—XML file that contains the list of applications, packaged as OSGi bundles, that are currently deployed to the Oracle Event Processing instance of this domain. You never update this file manually to deploy applications, but rather, use the deployer tool.
startwlevs.cmd
—Command file used to start an instance of Oracle Event Processing. The UNIX equivalent is called startwlevs.sh
.
stopwlevs.cmd
—Command file used to stop an instance of Oracle Event Processing. The UNIX equivalent is called stopwlevs.sh
.
config/config.xml
—XML file that describes the services that have been configured for the Oracle Event Processing instance. Services include logging, debugging, Jetty Web Service, and JDBC data sources.
For more information, see Section 1.3.2, "Configuring an Oracle Event Processing Server by Manually Editing the config.xml File".
config/security*
—Files that configure security for the domain.
config/atnstore.txt
—File that lists the configured users and groups for this domain.
The most efficient, least error-prone way to configure an Oracle Event Processing server is to use one or more of the Oracle Event Processing administration tools as Section 1.4, "Understanding Oracle Event Processing Server Administration Tools" describes.
Optionally, you can perform Oracle Event Processing server configuration by manually editing the Oracle Event Processing server config.xml
file. For more information on the location of the Oracle Event Processing server config.xml
file, see Section 1.3.1, "Oracle Event Processing Server Configuration Files".
Caution:
If you update the config.xml
file manually to change the configuration of an Oracle Event Processing server, you must restart the server for the change to take effect.
You can configure the following server objects and features using the config.xml
file (the referenced sections describe the exact elements you must add or update):
How the servers in a multi-server domain are configured together. This includes the multicast address and port, the groups, and so on.
See:
Network I/O.
See Chapter 9, "Configuring Network I/O for Oracle Event Processing."
Security.
See Chapter 10, "Configuring Security for Oracle Event Processing."
Jetty, an open-source, standards-based, full-featured Java Web Server.
See Chapter 11, "Configuring Jetty for Oracle Event Processing."
JMX, required to use the Oracle Event Processing Visualizer, wlevs.Admin
utility, and Deployer utility
See Chapter 12, "Configuring JMX for Oracle Event Processing."
JDBC data source, used to connect to a relational database.
See Chapter 13, "Configuring JDBC for Oracle Event Processing."
HTTP publish-subscribe server.
See Chapter 14, "Configuring HTTP Publish-Subscribe for Oracle Event Processing."
Logging and debugging properties of the server. By default, the log level is set to NOTICE
.
See Chapter 15, "Configuring Logging and Debugging for Oracle Event Processing."
Example 1-1 shows a sample config.xml
, from the ORACLE_CEP_HOME
/user_projects/domains/ocep_domain/defaultserver
template domain, shows how to configure some of these services.
Example 1-1 Sample Oracle Event Processing Server config.xml File
<?xml version="1.0" encoding="UTF-8"?> <!--Sample XML file generated by XMLSpy v2007 sp2 (http://www.altova.com)--> <n1:config xsi:schemaLocation="http://www.bea.com/ns/wlevs/config/server wlevs_server_config.xsd" xmlns:n1="http://www.bea.com/ns/wlevs/config/server" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <netio> <name>NetIO</name> <port>9002</port> </netio> <netio> <name>sslNetIo</name> <ssl-config-bean-name>sslConfig</ssl-config-bean-name> <port>9003</port> </netio> <work-manager> <name>JettyWorkManager</name> <min-threads-constraint>5</min-threads-constraint> <max-threads-constraint>10</max-threads-constraint> </work-manager> <jetty> <name>JettyServer</name> <network-io-name>NetIO</network-io-name> <work-manager-name>JettyWorkManager</work-manager-name> <secure-network-io-name>sslNetIo</secure-network-io-name> </jetty> <rmi> <name>RMI</name> <http-service-name>JettyServer</http-service-name> </rmi> <jndi-context> <name>JNDI</name> </jndi-context> <exported-jndi-context> <name>exportedJndi</name> <rmi-service-name>RMI</rmi-service-name> </exported-jndi-context> <jmx> <rmi-service-name>RMI</rmi-service-name> <jndi-service-name>JNDI</jndi-service-name> </jmx> <ssl> <name>sslConfig</name> <key-store>./ssl/evsidentity.jks</key-store> <key-store-pass> <password>{Salted-3DES}j4XEtuXmmvEl4M/NInwq0A==</password> </key-store-pass> <key-store-alias>evsidentity</key-store-alias> <key-manager-algorithm>SunX509</key-manager-algorithm> <ssl-protocol>TLS</ssl-protocol> <enforce-fips>false</enforce-fips> <need-client-auth>false</need-client-auth> </ssl> <http-pubsub> <name>pubsub</name> <path>/pubsub</path> <pub-sub-bean> <server-config> <name>/pubsub</name> <supported-transport> <types> <element>long-polling</element> </types> </supported-transport> <publish-without-connect-allowed>true</publish-without-connect-allowed> </server-config> <channels> <element> <channel-pattern>/evsmonitor</channel-pattern> </element> <element> <channel-pattern>/evsalert</channel-pattern> </element> <element> <channel-pattern>/evsdomainchange</channel-pattern> </element> </channels> </pub-sub-bean> </http-pubsub> <cluster> <server-name>productionServer</server-name> </cluster> <domain> <name>ocep_domain</name> </domain>
When you deploy an application to the Oracle Event Processing server, the Oracle Event Processing server creates a configuration history for the application. Any configuration changes you make to the application are recorded in this history. You can view and roll-back (undo) these changes using the Oracle Event Processing Visualizer or wlevs.Admin
tool.
For more information, see:
"Configuration History Management" in the Oracle Fusion Middleware Visualizer User's Guide for Oracle Event Processing
In general, you configure all Oracle Event Processing server options using the Oracle Event Processing server configuration file, you configure all Oracle Event Processing application options using Oracle Event Processing assembly and component configuration files, and you satisfy all Oracle Event Processing application run-time dependencies by importing the relevant private artifacts into an Oracle Event Processing project or deploying a shared application library that contains the relevant shared artifacts that applications import indirectly.
If necessary, you can configure the Oracle Event Processing bootclasspath
with artifacts, such as native code libraries, that the Oracle Event Processing server makes available before both application libraries and Oracle Event Processing applications are deployed.
You can use this technique to satisfy application or application library dependencies that you cannot satisfy using simple application imports or application libraries.
For more information, see "Application Dependencies" in the Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse.
Optionally, you can use the bootclasspath
to make native code libraries available to application libraries that depend on them.
To configure the Oracle Event Processing bootclasspath:
Update the server start script in the server directory of your domain directory so that Oracle Event Processing finds the appropriate native library JAR file when it boots up.
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 Oracle Event Processing 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_3.0.jar
file. Set the -Xbootclasspath/a
option to the full path name of the native library you are going to use.
For example, if you want to use the native library mynativelib
located in Oracle Event Processing server directory %USER_INSTALL_DIR%\bin
, update the java
command in the start script as follows -- the updated section shown in bold (the example is broken here for readability; in practice you should have the full command on one line):
%JAVA_HOME%\bin\java -Dwlevs.home=%USER_INSTALL_DIR% -Dbea.home=%BEA_HOME%
-Xbootclasspath/a:%USER_INSTALL_DIR%\bin\mynativelib.jar
-jar "%USER_INSTALL_DIR%\bin\wlevs_3.0.jar"
-disablesecurity %1 %2 %3 %4 %5 %6
In the example, %USER_INSTALL_DIR%
points to ORACLE_CEP_HOME
\ocep_11.1
.
If Oracle Event Processing is running, restart it so it reads the new java
option and data source information.
For more information, see Section 1.5.4, "Starting and Stopping Oracle Event Processing Servers".
This section describes the various Oracle Event Processing server administration tools that you can use to administer Oracle Event Processing servers, domains, and applications.
You can administer Oracle Event Processing servers, domains, and applications using any of the following:
For more information, see:
Section 1.3, "Understanding Oracle Event Processing Server Configuration"
Section 1.5, "Understanding Oracle Event Processing Server Administration Tasks"
The Configuration Wizard is a Java application that you can invoke graphically to create and update Oracle Event Processing servers and domains.
For more information, see:
The Oracle Event Processing Visualizer is the Oracle Event Processing graphical administration console.
It is a Web 2.0 application that consumes data from Oracle Event Processing, displays it in a useful and intuitive way to system administrators and operators, and, for specified tasks, accepts data that is then passed back to Oracle Event Processing to change its configuration.
Using Oracle Event Processing Visualizer, you can perform a wide variety of Oracle Event Processing server, domain, and application administration tasks for existing Oracle Event Processing standalone server domains and Oracle Event Processing multi-server domains.
For more information, see "Overview of Visualizer" in the Oracle Fusion Middleware Visualizer User's Guide for Oracle Event Processing.
The wlevs.Admin
command-line utility is a Java application that you can invoke locally or remotely to perform a wide variety of Oracle Event Processing server, domain, and application administration tasks.
For more information, see Appendix A, "wlevs.Admin Command-Line Reference".
The Deployer command-line utility is a Java application that you can invoke locally or remotely to perform application deployment and application administration tasks.
For more information, see Appendix B, "Deployer Command-Line Reference".
Oracle Event Processing provides a variety of command-line utilities that simplify security administration.
For more information, see Appendix C, "Security Utilities Command-Line Reference".
Using standards-based interfaces that are fully compliant with the Java Management Extensions (JMX) specification, you can perform a wide variety of Oracle Event Processing server, domain, and application administration tasks programmatically using JMX and Oracle Event Processing MBeans.
For more information, see:
This section describes some of the important Oracle Event Processing server administration tasks, including:
Section 1.5.1, "Creating Oracle Event Processing Servers and Domains"
Section 1.5.2, "Updating Oracle Event Processing Servers and Domains"
Section 1.5.3, "Configuring Oracle Event Processing Servers"
Section 1.5.4, "Starting and Stopping Oracle Event Processing Servers"
Section 1.5.5, "Deploying Applications to Oracle Event Processing Servers"
Section 1.5.6, "Managing Oracle Event Processing Applications, Servers, and Domains"
The most important administration task is to create Oracle Event Processing servers and domains.
For more information, see:
Once you create an Oracle Event Processing server and domain, you can update it to change its configuration or group membership.
For more information, see:
Once you create an Oracle Event Processing server and domain, you must configure the various services they provide.
For more information, see:
After you have created an Oracle Event Processing domain along with at least a single server, you start a server instance so you can then deploy applications and begin running them. During upgrades and after some configuration changes, you must stop and start the Oracle Event Processing server.
For more information, see:
Section 3.3, "Starting and Stopping an Oracle Event Processing Server in a Standalone-Server Domain"
Oracle Coherence: Section 5.5, "Starting and Stopping an Oracle Event Processing Server in a Multi-Server Domain"
Oracle Event Processing Native Clustering: Section 7.5, "Starting and Stopping an Oracle Event Processing Server in a Multi-Server Domain"
Note:
on Windows, do not stop the Oracle Event Processing server by clicking the Close button in the command prompt in which you started it. Always stop the Oracle Event Processing server using the stopwlevs.cmd
script or Ctrl-C
.
Once you have created and configured an Oracle Event Processing server and domain, you can deploy Oracle Event Processing applications to them.
For more information, see:
Section 4.1, "Deploying an Application to an Oracle Event Processing Standalone-Server Domain"
"Overview of Creating Oracle Event Processing Applications" in the Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse.
Once you have deployed applications to an Oracle Event Processing server and domain, you must manage the application to perform tasks such as monitor its performance and perform upgrades.
For more information, see: