Administration and Configuration Guide

Creating and Updating an Oracle CEP Domain

This section contains information on the following subjects:

Overview of Oracle Complex Event Processing Domains

A domain is the basic administration unit for Oracle Complex Event Processing (or Oracle CEP for short). It consists of one or more Oracle CEP server instances, zero or more deployed applications, and logically related resources and services that are managed, collectively, as one unit. If the domain contains more than one server instance, they can be clustered together. For details, see Configuring and Using Oracle CEP Clustered Domains.

After you install Oracle CEP, use the Configuration Wizard to create a new domain to deploy your applications. The Configuration Wizard creates, by default, the domains in the BEA_HOME/user_projects/domains directory, where BEA_HOME refers to the parent directory of the main Oracle CEP installation directory such as d:/beahome. You can, however, create a domain in any directory you want. The Configuration Wizard creates a single default server in the domain; all the server-related file are located in a subdirectory of the domain directory named the same as the server. Once you have created a domain with a single default server, you can use the Configuration Wizard to create additional servers in the domain.

The following list describes the important files and directories of a server in a domain, relative to the server directory (which is a subdirectory of the main domain directory):

deployments.xml—XML file that contains the list of applications, packaged as OSGi bundles, that are currently deployed to the Oracle CEP instance of this domain.
startwlevs.cmd—Command file used to start an instance of Oracle CEP. The UNIX equivalent is called startwlevs.sh.
stopwlevs.cmd—Command file used to stop an instance of Oracle CEP. The UNIX equivalent is called stopwlevs.sh.
config/config.xml—XML file that describes the services that have been configured for the Oracle CEP instance. Services include logging, debugging, Jetty Web Service, and JDBC data sources.
config/security*—Files that configure security for the domain.
config/atnstore.txt—File that lists the configured users and groups for this domain.

You can also use the Configuration Wizard to add a new server to an existing domain, or update an existing server to reconfigure its administration user, listen ports, and JDBC configuration.

Creating a Domain Using the Configuration Wizard

To create an Oracle CEP domain, use the Configuration Wizard. This tool guides you through the entire process, allowing you to customize the domain to more closely match your particular environment by:

Adding a default server.
Configuring the server’s administration user and password.
Configuring the default server to use a database or database driver that is different from the default. In this case, you need to customize the JDBC settings to point to the appropriate database.
Configuring the server’s listen port, the JMX RMI registry listen port, or the JMX RMI JRMP listen port.
Configuring the password for the identity keystore and private keystore.

You can use the Configuration Wizard in the following modes:

Graphical mode

Graphical-mode configuration is an interactive, GUI-based method for creating and configuring a domain. It can be run on both Windows and UNIX systems. See Creating a Domain in Graphical Mode.

Silent mode

Silent-mode configuration is a non-interactive method of creating and configuring a domain that requires the use of an XML properties file for selecting configuration options. You can run silent-mode configuration in either of two ways: as part of a script or from the command line. Silent-mode configuration is a way of setting configurations options only once and then using those options to duplicate the creating and configuration of a domain on many machines. See Creating a Domain in Silent Mode.

Creating a Domain in Graphical Mode

The following procedure shows how to invoke and use the Configuration Wizard in graphical mode by executing the relevant command script for both Windows or Unix. You can also invoke the Configuration Wizard on Windows using the Start ment:

Start > All Programs > Oracle CEP 3.0 > Tools > Configuration Wizard

To invoke and use the Configuration Wizard in graphical mode, follow these steps:

Open a command window and set your environment as described in Setting Up Your Development Environment.
Change to the WLEVS_HOME/common/bin directory, where WLEVS_HOME refers to the main Oracle CEP installation directory, such as /beahome_wlevs/wlevs30:

prompt> cd /beahome_wlevs/wlevs30/common/bin

Invoke the config.cmd (Windows) or config.sh (UNIX) command to invoke the wizard:

prompt> config.sh

After the Configuration Wizard has finished loading, you will see a standard Oracle Welcome window. Click Next.

Note:

The Oracle CEP Configuration Wizard is self-explanatory; however, if you want more information about using the tool, continue reading this procedure.

In the Choose Create or Update Domain window, choose Create a New Oracle CEP Domain. Click Next.
Enter the name of the administrator user for the default server of the domain. Click Next.
Enter basic configuration information about the default server in the domain. In particualr:

Enter the name of the default server. This name will also be used as the name of the directory that contains the default server files.
The listen port for Oracle CEP itself. Default is 9002.
The listen port for the JMX RMI registry, or the port on which to start the RMI registry. Default is 1099.
The listen port for JMX RMI JRMP, or the port on which to listen for RMI Java Remote Method Protocol (JRMP) JMX requests. Default is 9999.

Click Next.

Enter and confirm the password for the Oracle CEP domain identity keystore. By default, the password for the certificate private key will be the same as the identity keystore; if you want it to be different, uncheck Use Keystore Password and enter the private key password. Click Next.
In the Configuration Options window, choose Yes if you want to change the default JDBC data source configuration, No to accept the defaults.

The Configuration Wizard bases the creation of a new domain on the Oracle CEP domain template; by default, this template does not configure any JDBC data source for a domain. This means that, unless you change the default domain template used by the Configuration Wizard, if you choose No at this step, no JDBC data source is configured. If you want to configure a JDBC data source, choose Yes at this step to proceed to the page in which you can enter the data source information.

Click Next.

If you chose to change the default JDBC data source configuration, enter the information in the Configure Database Properties window.

In the top section, enter the name of the datasource. Then select the database type (Oracle or Microsoft SQL Server) and corresponding drivers; you can also browse to new drivers using the Browse/Append button.

In the lower section, enter the details about the database to which this data source connects, such as its name, the name of the computer that hosts the database server, the port, and the name and password of the user that connects to the database. The JDBC connection URL is automatically generated for you based on this information.

Click Next.

In the Configure Server window, enter the name of the new domain and the full pathname of its domain location. The configuration wizard creates the domain using its domain name in the domain location directory. Click Create.

Note: Oracle recommends you always use the default domain location to create your domains: BEA_HOME/user_projects/domains (UNIX) or BEA_HOME\user_projects\domains (Windows).

If the creation of the domain succeeded, you will see a message similar to the following in the Creating Domain window:

Domain created successfully!
Domain location: C:\bea_wlevs\user_projects\domains\wlevs30_domain

Click Done.

Creating a Domain in Silent Mode

Using the Configuration Wizard in silent mode allows a non-interactive method of creating and configuring a domain; this method requires the use of an XML properties file for selecting configuration options. To run the Configuration Wizard using silent mode:

Create a silent.xml file that defines the configuration settings normally entered by a user during an interactive session of the Configuration Wizard. See Creating a silent.xml File.

Note: Incorrect entries in the silent.xml file can cause failures. To help you determine the cause of a failure, we recommend that you create a log file when you launch the Configuration Wizard.

Open a command window and change to the WLEVS_HOME/common/bin directory, where WLEVS_HOME refers to the main Oracle CEP installation directory, such as /beahome_wlevs/wlevs30:

prompt> cd /beahome_wlevs/wlevs30/common/bin:

Invoke the config.cmd (Windows) or config.sh (UNIX) command in silent mode:

prompt> config.cmd -mode=silent -silent_xml=path_to_xml_file

where path_to_xml_file is the full pathname of the silent.xml template file you created in the preceding step.

If you want to create an execution log, use the -log=full_path_to_log_file option; for example:

prompt> config.cmd -mode=silent -silent_xml=path_to_xml_file  -log=C:\logs\create_domain.log

The command does not return any messages if it completes successfully. See Returning Exit Codes to the Command Window for getting information about the success or failure of the silent execution of the Configuration Wizard.

Creating a silent.xml File

When you run the Configuration Wizard in silent mode, the program uses an XML file (silent.xml) to determine which configuration options should be used.

To create a silent.xml file, follow these steps:

Using your favorite XML editor, create an empty file called silent.xml on the computer on which you want to run the Configuration Wizard in silent mode.
Copy the contents of the sample XML file, shown in Sample silent.xml File, into your own silent.xml file.
In the silent.xml file you just created, edit the values for the keywords shown in Table 2-1 to reflect your configuration.

For example, if you want to create the new domain in the C:\bea_wlevs\user_projects\domains directory, update the corresponding <data-value> element as follows

    <data-value name="DOMAIN_LOCATION"
                value="C:\bea_wlevs\user_projects\domains" />

Save the file in the directory of your choice.

Table 2-1 Values for the silent.xml File
For this data-value name...	Enter the following value...
CONFIGURATION_OPTION	Specifies whether you want to create a new domain or update an existing domain. Valid values are `createDomain` or `updateDomain`. Default value is `createDomain`.
EXISTING_DOMAIN_PATH	Specifies the full pathname of an existing server in the domain. Use this option only when updating an existing server in a domain.
USERNAME	The username of the administrator of the created or updated server in the domain.
PASSWORD	The password of the administrator of the created or updated server in the domain.
SERVER_NAME	The name of the default server in this domain. This name will also be used as the name of the directory that contains the default server files.
DOMAIN_NAME	The name of the domain.
DOMAIN_LOCATION	The full name of the directory that will contain the domain. The standard location for Oracle CEP domains is `BEA_HOME/user_projects/domains`, where `BEA_HOME` refers to the top-level installation directory, such as `c:/beahome`.
NETIO_PORT	The port number to which the Oracle CEP server instance itself listens.
RMI_REGISTRY_PORT	The port on which to start the JMX RMI registry.
RMI_JRMP_PORT	The port on which to listen for RMI Java Remote Method Protocol (JRMP) JMX requests.
KEYSTORE_PASSWORD	The password for the Oracle CEP identity keystore.
PRIVATEKEY_PASSWORD	The password for the certificate private key. The default value of this option is the value of the KEYSTORE_PASSWORD.
DB_URL	The URL used to connect to a database using JDBC. This option is used to configure the data source. The database configuration parameters are optional; if you do not specify them, then no datasource is configured for the server.
DB_USERNAME	The name of the user that connects to the database via the data source. The database configuration parameters are optional; if you do not specify them, then no datasource is configured for the server.
DB_PASSWORD	The password of the user that connects to the database via the data source. The database configuration parameters are optional; if you do not specify them, then no datasource is configured for the server.

Sample silent.xml File

<?xml version="1.0" encoding="UTF-8"?>

<bea-installer xmlns="http://www.bea.com/plateng/wlevs/config/silent">

  <input-fields>

    <data-value name="CONFIGURATION_OPTION" value="createDomain" />
    <data-value name="USERNAME" value="wlevs" />
    <data-value name="PASSWORD" value="wlevs" />

    <data-value name="SERVER_NAME" value="my_wlevs_server" />
    <data-value name="DOMAIN_NAME" value="mydomain" />
    <data-value name="DOMAIN_LOCATION" value="C:\bea_wlevs\user_projects\domains" />

    <data-value name="NETIO_PORT" value="9002" />
    <data-value name="RMI_REGISTRY_PORT" value="1099" />
    <data-value name="RMI_JRMP_PORT" value="9999" />
    <data-value name="KEYSTORE_PASSWORD" value="my_keystore_password" /> 
    <data-value name="PRIVATEKEY_PASSWORD" value="my_privatekey_password" />

    <data-value name="DB_URL" value="jdbc:bea:oracle://localhost:1521:XE" />
    <data-value name="DB_USERNAME" value="db_user" />
    <data-value name="DB_PASSWORD" value="db_password" />

  </input-fields>

</bea-installer>

Returning Exit Codes to the Command Window

When run in silent mode, the Configuration Wixard generates exit codes that indicate the success or failure of the creation and configuration of the domain. These exit codes are shown in the following table.

Table 2-2 Exit Codes
Code	Description
0	Configuration Wizard execution completed successfully
-1	Configuration Wizard execution failed due to a fatal error
-2	Configuration Wizard execution failed due to an internal XML parsing error

Listing 2-1 provides a sample Windows command file that invokes the Configuration Wizard in silent mode and echoes the exit codes to the command window from which the script is executed.

Listing 2-1 Sample Windows Command File Displaying Silent-Mode Exit Codes

rem Execute the Configuration Wizard in silent mode
@echo off
config.cmd -mode=silent -silent_xml=c:\scripts\silent.xml  -log=C:\logs\create_domain.logs

@rem Return an exit code to indicate success or failure
set exit_code=%ERRORLEVEL%

@echo.
@echo Exitcode=%exit_code%
@echo.
@echo Exit Code Key
@echo ---------------
@echo  0=Configuration Wizard completed successfully
@echo -1=Configuration Wizard failed due to a fatal error
@echo -2=Configuration Wizard failed due to an internal XML parsing error
@echo.

Adding New Servers to an Existing Domain Using the Configuration Wizard

Use the Configuration Wizard to add new servers to an existing domain. The procedure is similar to creating a new domain, so be sure you read Creating a Domain Using the Configuration Wizard before continuing with this section.

For clarity, it is assumed that:

You have already created a new domain and its domain directory is C:\bea_wlevs\user_projects\domains\mydomain.
The domain includes a single server called defaultserver and the server files are located in the C:\bea_wlevs\user_projects\domains\mydomain\defaultserver directory.
You want to create a new server in the mydomain domain called productionServer.

Adding New Servers in Graphical Mode

Follow these steps to add a new server to an existing domain in graphical mode:

Invoke the Configuration Wizard as described in Creating a Domain in Graphical Mode.
In the Choose Create or Update Domain window, choose Create a New Oracle CEP Domain. Click Next.
Enter the name and password of the administrator user for the new server you are adding to the domain. Click Next.
Enter basic configuration information about the new server in the domain. Be sure all this information is different from that of the other servers in the domain to prevent conflicts when starting all servers. In particular:

Enter the name of the new server. This name will also be used as the name of the directory that contains the new server’s files. Following our example, this value is productionServer.
The listen port for Oracle CEP itself.
The listen port for the JMX RMI registry, or the port on which to start the RMI registry.
The listen port for JMX RMI JRMP, or the port on which to listen for RMI Java Remote Method Protocol (JRMP) JMX requests.

Click Next.

Enter and confirm the password for the Oracle CEP identity keystore. By default, the password for the certificate private key will be the same as the identity keystore; if you want it to be different, uncheck Use Keystore Password and enter the private key password. Click Next.
In the Configuration Options window, choose Yes if you want to change the default JDBC data source configuration, No to accept the defaults. Click Next.
If you chose to change the default JDBC data sourceconfiguration, enter the information in the Configure Database Properties window.

Click Next.

In the Configure Server window, enter the name of the existing domain and the full pathname of its location. Following our example, you would enter mydomain for the domain name and C:\bea_wlevs\user_projects\domains for the domain location. Click Create.
If the creation of the new server succeeded, you will see a message similar to the following in the Creating Domain window:

Domain created successfully!
Domain location: C:\bea_wlevs\user_projects\domains\mydomain

Click Done.

Adding New Servers in Silent Mode

Adding a new server to an existing domain in silent mode is similar to creating a new domain, as described in Creating a Domain in Silent Mode. The only difference is in the values of the options in the silent.xml file. In particular:

Set CONFIGURATION_OPTION to createDomain.
Set the DOMAIN_NAME and DOMAIN_LOCATION options to the name and location of the existing domain.
Set the SERVER_NAME option to the name of the new server you want to add to the existing domain.
Be sure that the new server configuration options, such as NETIO_PORT, RMI_REGISTRY_PORT, and RMI_JRMP_PORT, are different than the options for any existing server in the domain. The database options can be the same if you want the new server to connect to the same database as the existing servers.

Based on the assumptions described in Adding New Servers to an Existing Domain Using the Configuration Wizard, the silent.xml file would look something like the following:

<?xml version="1.0" encoding="UTF-8"?>

<bea-installer xmlns="http://www.bea.com/plateng/wlevs/config/silent">

  <input-fields>

    <data-value name="CONFIGURATION_OPTION" value="createDomain" />
    <data-value name="USERNAME" value="wlevs" />
    <data-value name="PASSWORD" value="wlevs" />

    <data-value name="SERVER_NAME" value="productionServer" />
    <data-value name="DOMAIN_NAME" value="mydomain" />
    <data-value name="DOMAIN_LOCATION" value="C:\bea_wlevs\user_projects\domains" />

    <data-value name="NETIO_PORT" value="9102" />
    <data-value name="RMI_REGISTRY_PORT" value="1199" />
    <data-value name="RMI_JRMP_PORT" value="9998" />
    <data-value name="KEYSTORE_PASSWORD" value="my_keystore_password" /> 
    <data-value name="PRIVATEKEY_PASSWORD" value="my_privatekey_password" />

    <data-value name="DB_URL" value="jdbc:bea:oracle://localhost:1521:XE" />
    <data-value name="DB_USERNAME" value="db_user" />
    <data-value name="DB_PASSWORD" value="db_password" />

  </input-fields>

</bea-installer>

Updating an Existing Server Using the Configuration Wizard

Use the Configuration Wizard to update an existing servers in a domain. The procedure has similarities with creating a new domain and default server, so be sure you read Creating a Domain Using the Configuration Wizard before continuing with this section.

You can update the only following configuration options of an existing server in your domain:

The listen ports
The configuration of the JDBC datasource.

For clarity, it is assumed in this section that you want to update a server called productionServer whose server-related files are located in the C:\bea_wlevs\user_projects\domains\mydomain\productionServer directory.

Updating an Existing Server in Graphical Mode

Follow these steps to update an existing server in your domain using the Configuration Wizard in graphical mode.

Invoke the Configuration Wizard as described in Creating a Domain in Graphical Mode.
In the Choose Create or Update Domain window, choose “Update an existing Oracle CEP domain”. Click Next.
In the text box, enter the full pathname of the server directory that contains the files for the server you want to update. Following our example, this value would be C:\bea_wlevs\user_projects\domains\mydomain\productionServer. Click Next.
Update the listen ports for the server. Be sure that you do not enter the same values used by other servers in the domain so as to prevent any conflicts when all servers are running at the same time. Click Next.
If you want to change the JDBC datasource configuration, select Yes, click Next, and enter the new values. Otherwise, select No and click Next.
Click Update to update the server.

Updating an Existing Server in Silent Mode

Updating an existing server in a domain in silent mode is similar to creating a new domain, as described in Creating a Domain in Silent Mode. The main difference is in the values of the options in the silent.xml file. In particular:

Set CONFIGURATION_OPTION to updateDomain.
Set EXISTING_DOMAIN_PATH to the full pathname of the server directory that contains the files for the server you want to update. In our example, the value would be C:\bea_wlevs\user_projects\domains\mydomain\productionServer.
Do not set the DOMAIN_NAME and DOMAIN_LOCATION options. This is because the Configuration Wizard already knows these values, based on what you entered for EXISTING_DOMAIN_PATH.
Se the listen port and JDBC datasource options to the new values.

Be sure that the new server configuration options, such as NETIO_PORT, RMI_REGISTRY_PORT, and RMI_JRMP_PORT, are different than the options for any other servers in the domain. The database options can be the same if you want the updated server to connect to the same database as the other servers.

Based on the assumptions described in Updating an Existing Server Using the Configuration Wizard, the silent.xml file would look something like the following:

<?xml version="1.0" encoding="UTF-8" ?>

<bea-installer xmlns="http://www.bea.com/plateng/wlevs/config/silent">

 <input-fields>
  <data-value name="CONFIGURATION_OPTION" value="updateDomain" /> 
  <data-value name="EXISTING_DOMAIN_PATH" value="C:\bea_wlevs\user_projects\domains\mydomain\productionServer" />

  <data-value name="NETIO_PORT" value="9102" />
  <data-value name="RMI_REGISTRY_PORT" value="1199" />
  <data-value name="RMI_JRMP_PORT" value="9998" />

  <data-value name="DB_URL" value="jdbc:bea:oracle://localhost:1521:XE" />
  <data-value name="DB_USERNAME" value="db_user" />
  <data-value name="DB_PASSWORD" value="db_password" />

 </input-fields>

</bea-installer>

Stopping and Starting the Server

Each Oracle CEP server directory contains a command script that starts a server instance; by default, the script is called startwlevs.cmd (Windows) or startwlevs.sh (UNIX). The script to stop the server is called stopwlevs.cmd (Windows) or stopwlevs.sh (UNIX).

Starting the Server

To start an instance of Oracle CEP:

Ensure that the JAVA_HOME variable in the server start script points to the correct Oracle JRockit JDK. If it does not, edit the script.

The server start script is located in the server directory under the main domain directory. For example, the default server directory of the HelloWorld domain is located in WLEVS_HOME/samples/domains/helloworld_domain/defaultserver, where WLEVS_HOME refers to the main Oracle CEP installation directory, such as /beahome_wlevs/wlevs30.

If using the Oracle JRockit JDK installed with Oracle CEP 3.0, the JAVA_HOME variable should be set as follows:

  JAVA_HOME=BEA_HOME_WLEVS/jrockit-R27.6.0-23-1.5.0_15 (UNIX)

  set JAVA_HOME=BEA_HOME_WLEVS\jrockit-R27.6.0-23-1.5.0_15 (Windows)

where BEA_HOME_WLEVS refers to the installation directory of Oracle CEP 3.0, such as /beahome_wlevs (UNIX) or c:\beahome_wlevs (Windows).

If using the Oracle JRockit JDK installed with Oracle JRockit Real Time 2.0, the JAVA_HOME variable should be set as follows:

  JAVA_HOME=BEA_HOME_WLRT/jrockit-realtime20_150_11 (UNIX)

  set JAVA_HOME=BEA_HOME_WLRT\jrockit-realtime20_150_11 (Windows)

where BEA_HOME_WLRT refers to the installation directory of Oracle JRockit Real Time 2.0, such as /beahome_wlrt (UNIX) or c:\beahome_wlrt (Windows).

Open a command window and change to the server directory of the domain directory. For example, to start the HelloWorld sample server:

prompt> cd C:\bea_wlevs\wlevs30\samples\domains\helloworld_domain\defaultserver

Execute the startwlevs.cmd (Windows) or startwlevs.sh (UNIX) script:

prompt> startwlevs.cmd

If you are using the Oracle JRockit JDK included in Oracle JRockit Real Time 2.0, enable the deterministic garbage collector by passing the -dgc parameter to the command:

prompt> startwlevs.cmd -dgc

Stopping the Server Using the stopwlevs Script

To stop a running Oracle CEP server instance:

Open a command window and change to the server directory. For example, to stop the running HelloWorld sample server:

prompt> cd C:\bea_wlevs\wlevs30\samples\domains\helloworld_domain\defaultserver

Execute the stopwlevs.cmd (Windows) or stopwlevs.sh (UNIX) script. Use the -url argument to pass the URL that establishes a JMX connection to the server you want to stop. This URL takes the form service:jmx:rmi:///jndi/rmi://host:jmxport/jmxrmi, where host refers to the computer hosting the server and jmxport refers to the server’s JMX port, configured in config.xml file. For example:

prompt> stopwlevs.sh -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi

In the example, the host is ariel and the JMX port is 1099.

See Table 5-1, Connection Arguments, on page 5-6 for additional details about the -url argument.

Next Steps

After creating your own Oracle CEP domain:

Optionally configure the server and domain. See Overview of Configuring Oracle Complex Event Processing.
Create an Oracle CEP application. See Oracle CEP Application Development Guide for a description of the programming model, details about the various components that make up an application, and how they all fit together.
Deploy your new, or existing, Oracle CEP application to the domain. See Deploying Oracle CEP Applications.