1 Overview of Oracle Event Processing Server Administration

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:

1.1 Understanding Oracle Event Processing Servers and Domains

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:

1.2 Understanding Oracle Event Processing Server Lifecycle

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

Description of Figure 1-1 follows
Description of "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:

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:

1.2.1 User Action: Start Oracle Event Processing Server

After you start the Oracle Event Processing server, it performs the following actions:

  1. Starts core engine bundles.

  2. Starts Oracle Event Processing bundles.

  3. Registers MBeans.

  4. Oracle Event Processing server state is now STARTING.

  5. Starts application bundles.

  6. Oracle Event Processing server state is now RUNNING.

1.2.2 User Action: Stop Oracle Event Processing Server

After you shutdown the Oracle Event Processing server, it performs the following actions:

  1. Oracle Event Processing server state is SHUTTING_DOWN.

  2. Unregister ServerRuntimeMBean.

    Oracle Event Processing server ceases to have a state.

  3. Shuts down Oracle Event Processing bundles.

  4. Shuts down application bundles.

  5. Shuts down core engine bundles.

1.3 Understanding Oracle Event Processing Server Configuration

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:

  1. Stopping the Oracle Event Processing server.

  2. Editing the Oracle Event Processing server config.xml file located in the server's domain directory

  3. 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:

For more information, see:

1.3.1 Oracle Event Processing Server Configuration Files

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.

1.3.2 Configuring an Oracle Event Processing Server by Manually Editing the config.xml File

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):

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>

1.3.3 Configuration History Management

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:

1.3.4 Configuring the Oracle Event Processing Server bootclasspath

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.

1.3.4.1 How to Configure the Oracle Event Processing Server bootclasspath

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:

  1. 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.

  2. 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".

1.4 Understanding Oracle Event Processing Server Administration Tools

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:

1.4.1 Configuration Wizard

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:

1.4.2 Oracle Event Processing Visualizer

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.

1.4.3 wlevs.Admin Command-Line Utility

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".

1.4.4 Deployer Command-Line Utility

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".

1.4.5 Security Command-Line Utilities

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".

1.4.6 JMX

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:

1.5 Understanding Oracle Event Processing Server Administration Tasks

This section describes some of the important Oracle Event Processing server administration tasks, including:

1.5.1 Creating Oracle Event Processing Servers and Domains

The most important administration task is to create Oracle Event Processing servers and domains.

For more information, see:

1.5.2 Updating Oracle Event Processing Servers and Domains

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:

1.5.4 Starting and Stopping Oracle Event Processing Servers

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:

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.

1.5.5 Deploying Applications to Oracle Event Processing Servers

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:

1.5.6 Managing Oracle Event Processing Applications, Servers, and Domains

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: