This chapter describes how to administer Oracle Event Processing multi-server domains that are based on Oracle Event Processing native clustering. It describes how to create and update these domains, secure messages within them, manage group members, and start and stop servers.
This chapter includes the following sections:
Section 7.3, "Securing the Messages Sent Between Servers in a Multi-Server Domain"
Section 7.4, "Using the Multi-Server Domain APIs to Manage Group Membership Changes"
Section 7.5, "Starting and Stopping an Oracle Event Processing Server in a Multi-Server Domain"
This section describes how to create and configure a multi-server domain from two or more Oracle Event Processing servers using Oracle Event Processing native clustering. This section includes the following:
Note:
To properly configure servers in a multi-server domain, you must configure them with the same multicast address and port and the same domain name. It is an error to configure servers using the same multicast address and port and port but different domain names.
This procedure describes how to create a multi-server domain that uses only the two predefined groups: the singleton group and domain group. In a domain that uses default groups, all servers must be completely homogenous.
If a domain must support servers that are not completely homogeneous, you configure this by creating custom groups. See Section 7.1.2, "How to Create an Oracle Event Processing Multi-Server Domain With Custom Groups Using Oracle Event Processing Native Clustering".
For more information about default and custom groups, see Section 6.2, "Groups".
Note:
In this section it is assumed that you have already created a domain that contains a single server and that you want to add additional servers to the domain to make it a multi-server domain. See Chapter 3, "Administering Oracle Event Processing Standalone-Server Domains" for details on creating a domain.
To create an Oracle Event Processing multi-server domain with default groups using Oracle Event Processing Native Clustering:
Create a domain that contains a single, initial server.
See Chapter 3, "Administering Oracle Event Processing Standalone-Server Domains".
Add one or more servers to the domain using the Configuration Wizard.
Note:
Even though the Configuration WIzard does not support adding new servers to a multi-server domain, one can use the Configuration Wizard to generate a new stand-alone server, and then manually update its configuration to join a multi-server domain.
Configure all the servers in the multi-server domain by manually editing their config.xml files and adding a cluster element with specific information.
To configure the servers in a multi-server domain using default groups, update the config.xml file for each member server by adding a cluster child element of the root config element as Example 7-1 shows.
Include the following child elements of cluster:
server-name: The server-name child element of cluster specifies a unique name for the server. Oracle Event Processing Visualizer uses the value of this element when it displays the server in its console. The default value if the element is not set is Server-identity where identity is the value of the identity element.
server-host-name: Specifies the host address/IP used for point-to-point HTTP multi-server communication. Default value is localhost.
This element is mandatory if one or more Oracle Event Processing servers in your multi-server domain are on different hosts and you plan to manage the multi-server domain using the Oracle Event Processing Visualizer. It is also mandatory if a server is deployed on a host machine that has multiple IP addresses configured (whether in a multi-server or standalone-server environment).
multicast-address: The multicast-address element is required unless all servers of the multi-server domain are hosted on the same computer; in that case you can omit the multicast-address element and Oracle Event Processing automatically assigns a multicast address to the multi-server domain based on the computer's IP address.
If, however, the servers are hosted on different computers, then you must provide an appropriate domain-local address. Oracle recommends you use an address of the form 239.255.X.X, which is what the auto-assigned multicast address is based on.
All the Oracle Event Processing servers using this multicast-address must be on the same subnet.
identity: The identity element identifies the server's identity and must be an integer between 1 and INT_MAX. Oracle Event Processing numerically compares the server identities during multi-server operations; the server with the lowest identity becomes the domain coordinator. Be sure that each server in the multi-server domain has a different identity; if servers have the same identity, the results of multi-server operations are unpredictable.
enabled: By default the clustering of the servers in a multi-server domain is enabled for Oracle Coherence, so to enable Oracle Event Processing native clustering use <enabled>evs4j</enabled>.
Note:
When adding cluster element child elements, observe the correct element order as Section 6.5, "Order of cluster Element Child Elements" describes.
Example 7-1 myServer1 config.xml File
<config>
<domain>
<name>myDomain</name>
</domain>
<cluster>
<server-name>myServer1</server-name>
<multicast-address>239.255.0.1</multicast-address>
<identity>1</identity>
<enabled>evs4j</enabled>
</cluster>
...
</config>
In Example 7-2, the server is part of a domain called myDomain.
For each server of the multi-server domain, the multicast-address elements must contain the same value. The identity and server-name elements, however, must be different for each server in the multi-server domain.
Example 7-2 shows the config.xml file of a second server, called myServer2, in the myDomain multi-server domain; note that this server's identity is 2.
Example 7-2 myServer2 config.xml File
<config>
<domain>
<name>myDomain</name>
</domain>
<cluster>
<server-name>myServer2</server-name>
<multicast-address>239.255.0.1</multicast-address>
<identity>2</identity>
<enabled>evs4j</enabled>
</cluster>
...
</config>
See Section 6.5, "Order of cluster Element Child Elements" for a description of additional multi-server-related configuration elements and the required order of child elements.
Optionally, secure the messages that are shared between the servers in a domain by configuring encryption and digital signatures.
To avoid a single point of failure, consider enabling Oracle Event Processing Visualizer on a small subset of n machines in the domain.
See "How to Start Oracle Event Processing Visualizer in a Multi-Server Domain" in the Oracle Fusion Middleware Visualizer User's Guide for Oracle Event Processing.
Note:
Enabling Oracle Event Processing Visualizer on a given Oracle Event Processing Server may impact the performance of the server depending on the Oracle Event Processing Visualizer workload.
Start all servers in your multi-server domain.
See Section 7.5, "Starting and Stopping an Oracle Event Processing Server in a Multi-Server Domain".
This procedure describes how to create a multi-server domain that uses custom groups to accommodate servers which are not completely homogenous.
If all the servers in your domain are completely homogeneous, you do not need to create custom groups. Instead, you can use the predefined groups: the singleton group and domain group. See Section 7.1.1, "How to Create an Oracle Event Processing Multi-Server Domain With Default Groups Using Oracle Event Processing Native Clustering".
For more information about default and custom groups, see Section 6.2, "Groups".
Note:
In this section it is assumed that you have already created a domain that contains a single server and that you want to add additional servers to the domain to make it a multi-server domain. See Chapter 3, "Administering Oracle Event Processing Standalone-Server Domains" for details on creating a domain.
In this procedure, assume you have created three servers: myServer1, myServer2, and myServer3. You want myServer1 to be a member of the selector group and myServer2 and myServer3 to be members of the strategy group.
To create an Oracle Event Processing multi-server domain with custom groups using Oracle Event Processing Native Clustering:
Create a domain that contains a single, initial server.
See Chapter 3, "Administering Oracle Event Processing Standalone-Server Domains".
Add one or more servers to the domain using the Configuration Wizard.
Note:
Even though the Configuration WIzard does not support adding new servers to a multi-server domain, one can use the Configuration Wizard to generate a new stand-alone server, and then manually update its configuration to join a multi-server domain.
Configure all the servers in the multi-server domain by manually editing their config.xml files and adding a cluster element with specific information.
To configure the servers in a multi-server domain using custom groups, update the config.xml file for each member server by adding (if one does not already exist) a groups child element of cluster and specifying the name of the group as the value of the groups element.
Note:
When adding cluster element child elements, observe the correct element order as Section 6.5, "Order of cluster Element Child Elements" describes.
The groups element can include more than one group name in the case that the server is a member of more than one group; separate multiple group names using commas.
The groups element is optional; if a server configuration does not include one, then the server is a member of the default groups (domain and singleton). For more information about the domain and singleton groups, see Section 6.2, "Groups".
Example 7-3, Example 7-4, and Example 7-5 show the relevant snippets of the config.xml file for each server.
Example 7-3 Server Configuration File config.xml for myServer1
<config>
<domain>
<name>myDomain</name>
</domain>
<cluster>
<server-name>myServer1</server-name>
<multicast-address>239.255.0.1</multicast-address>
<identity>1</identity>
<enabled>evs4j</enabled>
<groups>selector</groups>
</cluster>
...
</config>
Example 7-4 Server Configuration File config.xml for myServer2
<config>
<domain>
<name>myDomain</name>
</domain>
<cluster>
<server-name>myServer2</server-name>
<multicast-address>239.255.0.1</multicast-address>
<identity>2</identity>
<enabled>evs4j</enabled>
<groups>strategy</groups>
</cluster>
...
</config>
Example 7-5 Server Configuration File config.xml for myServer3
<config>
<domain>
<name>myDomain</name>
</domain>
<cluster>
<server-name>myServer3</server-name>
<multicast-address>239.255.0.1</multicast-address>
<identity>3</identity>
<enabled>evs4j</enabled>
<groups>strategy</groups>
</cluster>
...
</config>
Optionally, secure the messages that are shared between the servers in a domain by configuring encryption and digital signatures.
To avoid a single point of failure, consider enabling Oracle Event Processing Visualizer on a small subset of n machines in the domain.
See "How to Start Oracle Event Processing Visualizer in a Multi-Server Domain" in the Oracle Fusion Middleware Visualizer User's Guide for Oracle Event Processing.
Note:
Enabling Oracle Event Processing Visualizer on a given Oracle Event Processing Server may impact the performance of the server depending on the Oracle Event Processing Visualizer workload.
Start all servers in your multi-server domain.
See Section 7.5, "Starting and Stopping an Oracle Event Processing Server in a Multi-Server Domain".
Use the Configuration Wizard to add a new server to an existing standalone server domain so as to later convert it into a multi-server domain. The procedure is similar to creating a new domain, so be sure you read Section 3.1, "Creating an Oracle Event Processing Standalone-Server Domain" before continuing with this section.
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.
Note:
On Windows, you can also invoke the Configuration Wizard using the Start menu:
Start > All Programs > Oracle Event Processing 10gR3 > Tools > Configuration Wizard
For clarity, it is assumed that:
You have already created a new domain and its domain directory is C:\oracle_cep\user_projects\domains\myDomain.
The domain includes a single server called myServer1 and the server files are located in the C:\oracle_cep\user_projects\domains\myDomain\myServer1 directory.
You want to create a new server in the existing myDomain domain called myServer2.
To update an Oracle Event Processing multi-server domain using the Configuration Wizard in graphical mode:
Open a command window and set your environment as described in "Setting Your Development Environment" in the Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse.
Change to the ORACLE_CEP_HOME/ocep_11.1/common/bin directory, where ORACLE_CEP_HOME refers to the main Oracle Event Processing installation directory, such as /oracle_cep:
prompt> cd /oracle_cep/ocep_11.1/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.
Note:
The Oracle Event Processing Configuration Wizard is self-explanatory; however, if you want more information about using the tool, continue reading this procedure.
Click Next.
In the Choose Create or Update Domain window, choose Create a New Oracle Event Processing 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.
Note:
If the new server is located on the same computer as any other servers in the domain, be sure the following information is different from that of the other servers 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 myServer2.
The listen port for the Oracle Event Processing server.
Click Next.
Enter and confirm the password for the Oracle Event Processing 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, clear 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.
Note:
When you deploy an application to a group in the domain, Oracle Event Processing replicates the application to each server that is a member of the group. This means that if your application uses a datasource, and you have configured the datasource differently for each server in the domain, then the storage and retrieval of data to and from this data source will differ depending on the server on which the application is running.
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 existing domain and the full pathname of its location.
Following our example, you would enter myDomain for the domain name and C:\oracle_cep\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:\oracle_cep\user_projects\domains\myDomain
Click Done.
The servers in a multi-server domain update their state by exchanging multi-server-related messages. It is important that these messages be at least checked for integrity. A private key can be used to achieve integrity. This key must be shared by all servers in the domain.
This section describes:
You can secure the messages sent between servers in a multi-server domain using Oracle Event Processing native clustering.
To secure the messages sent between servers in an Oracle Event Processing multi-server domain using Oracle Event Processing Native Clustering:
Stop all servers in your multi-server domain, if they are currently running.
See Section 7.5, "Starting and Stopping an Oracle Event Processing Server in a Multi-Server Domain".
Edit the config.xml file of each server in the multi-server domain by adding the security child element to the cluster element, as Example 7-6 shows.
Example 7-6 The cluster Element security Child Element
<config>
<domain>
<name>myDomain</name>
</domain>
<cluster>
<server-name>myServer1</server-name>
<multicast-address>239.255.0.1</multicast-address>
<identity>1</identity>
<enabled>coherence</enabled>
<security>encrypt</security>
</cluster>
...
</config>
The config.xml file is located in the DOMAIN_DIR/servername/config directory of each server, where DOMAIN_DIR refers to the domain directory and servername refers to the name of your server, such as d:\oracle_cep_home\user_projects\domains\mydomain\myserver1\config.
You must specify one of the following values for the security child element:
none—Default value. Specifies that no security is configured for the multi-server domain.
encrypt—Specifies that multi-server messages should be encrypted.
Observe the correct order of child elements in the cluster element. See Section 6.5, "Order of cluster Element Child Elements".
Edit the DOMAIN_DIR/servername/config/security-config.xml file of each server in the multi-server domain by adding the encryption-service child element of the config root element, as Example 7-7 shows.
Ensure that the DOMAIN_DIR/servername/.aesinternal.dat file for each server in the multi-server domain is exactly the same by copying the file from one server to the other servers.
This file is automatically created by the Configuration Wizard when you first created the server; Oracle Event Processing uses this file for encrypting messages.
For example, assume all the servers in your domain are located in the d:\oracle_cep\user_projects\domains\mydomain directory, and that the domain has three servers: server1, server2, and server3. To ensure they all have the same .aesinternal.dat file, copy the one from server1 to the other servers:
prompt> cd d:\oracle_cep\user_projects\domains\mydomain\server1 prompt> cp .aesinternal.dat ..\server2 prompt> cp .aesinternal.dat ..\server3
Start one of the servers in your domain.
See Section 7.5, "Starting and Stopping an Oracle Event Processing Server in a Multi-Server Domain".
Because of the encryption-service element that you added to the security-config.xml file in step 3, Oracle Event Processing automatically creates the .msasig.dat file in the main server directory. Oracle Event Processing uses this file for digitally signing messages.
Stop the server you just started.
See Section 7.5, "Starting and Stopping an Oracle Event Processing Server in a Multi-Server Domain".
Copy the .msasig.dat file you created in step 5 to the other servers.
For example:
prompt> cd d:\oracle_cep\user_projects\domains\mydomain\server1 prompt> cp .msasig.dat ..\server2 prompt> cp .msasig.dat ..\server3
If you plan to use Oracle Event Processing Visualizer with the servers in this domain, see Section 10.5.3, "How to Configure SSL in a Multi-Server Domain for Oracle Event Processing Visualizer".
Start all servers in your multi-server domain.
See Section 7.5, "Starting and Stopping an Oracle Event Processing Server in a Multi-Server Domain".
In an active-active system, applications are deployed homogeneously across several servers and are actively executing.
There are cases, however, when these homogeneously-deployed applications need to elect a primary one as the coordinator or leader. In this case, events that result from the coordinator application are kept and passed on to the next component in the EPN; the results of secondary servers are dropped. However, if the coordinator fails, then one of the secondary servers must be elected as the new coordinator.
To enable this in an application, the adapter or event bean, generally in the role of an event sink, must implement the com.bea.wlevs.ede.api.cluster.GroupMembershipListener interface which allows the event sinks to listen for multi-server domain group membership changes. At runtime, Oracle Event Processing automatically invokes the onMembershipChange callback method whenever membership changes occur.
The signature of the callback method is as follows:
onMembershipChange(Server localIdentity, Configuration groupConfiguration);
In the implementation of the onMembershipChange callback method, the event sink uses the Server object (localIdentity) to verify if it is the leader. This can be done be comparing localIdentity with the result of Configuration.getCoordinator() run on the second parameter, groupConfiguration. This parameter also allows a server to know what the current members of the group are by executing Configuration.getMembers().
In order to only keep events if it is a coordinator, the event sink must get a new Server identity every time membership in the group changes. Group membership changes occur if, for example, another server within the group fails and is no longer the coordinator.
A similar interface com.bea.wlevs.ede.api.cluster.DomainMembershipListener exists for listening to membership changes to the domain as a whole, rather than just changes to the group.
Note that in a hot-hot configuration, there is a non-zero delay in failure notification. If you are using the notification APIs to implement clustering, you will lose and not process events that occur in the window between the server failure and the notification being delivered to the new master server.
For more information, see Oracle Fusion Middleware Java API Reference for Oracle Event Processing.
To start the servers in a multi-server domain, start each server separately by running its start script. This is the same way you start a server in a standalone server domain. See Section 3.3, "Starting and Stopping an Oracle Event Processing Server in a Standalone-Server Domain" for details.
If you have not configured custom groups for the multi-server domain, then all servers are members of just the pre-defined domain group, which contains all the servers in the multi-server domain, and a singleton group, one for each member server. This means, for example, if there are three servers in the multi-server domain then there are three singleton groups.
If, however, you have configured custom groups for the multi-server domain, then the servers are members of the groups for which they have been configured, as well as the pre-defined groups.