This section contains information on the following subjects:
The following sections introduce use cases and terminology related to the management and availability of a set of Oracle CEP servers.
An Oracle CEP multi-server domain is a set of two or more servers logically connected for the purposes of management, and physically connected using a shared User Datagram Protocol (UDP) multicast address and port. All servers in an Oracle CEP multi-server domain are aware of all other servers in the domain and any one server can be used as an access point for making changes to the deployments in the domain.
Management of the multi-server infrastructure is done at the domain level. Thus server failure, start, or restart is detected by every member of the multi-server domain. Each member of the multi-server domain has a consistent, agreed notion of domain membership enforced by the multi-server infrastructure.
For servers to be considered a part of the same multi-server domain they must share the same multicast address and port and the same domain name.
The servers of a multi-server domain must be homogenous. For example, you cannot have two servers, one configured with the IPv6 (Internet Protocol version 6) protocol and the other with the IPv4 protocol, be members of the same domain.
In order to support the deployment to, and management of, the multi-server domain at a finer grained-level than the domain, Oracle CEP introduces the concept of groups. A group is a set of one or more servers with a unique name within the domain. In an Oracle CEP domain, an arbitrary number of groups may exist with a configurable group membership. A server may be a member of more than one group, although typically this information is transparent to the user. The following pre-defined groups always exist:
When you deploy an application to a multi-server domain, you deploy it to a particular group. Applications deployed to the domain or custom groups must have a unique name across the domain.
In order to provide high availability (HA)-like capabilities to adapter and event beam implementations, Oracle CEP provides a number of notification and messaging APIs at both the group- and domain-level. Using these APIs, you can configure a server to receive notification when its group or domain membership changes, either because an administrator deliberately changed it or due to a server failure. Similarly you can use these APIs to send messages to both individual groups and to the domain.
Servers in an Oracle CEP domain store their files in a single directory. By convention, the directories of the servers in a multi-server domain are sub-directories of the domain directory. Additionally, the name of the servers and domain correspond to the name of the server directories and domain directory, respectively. This is by convention only, and not required, although Oracle recommends you set up your domains this way for simplicity and consistency. If the servers of the multi-server domain are located on different computers, you can replicate the directory structure on both computers, also for simplicity and consistency.
The following diagram shows a multi-server domain directory with three servers. A snippet of the configuration file for myServer1
is shown to show how the domain directory and domain object are configured with the same name, as well as the server directory and server name. The domain directory is located in the ORACLE_CEP_HOME
/user_projects/domains
directory, which is the default location for Oracle CEP domains.
This section describes how to create and configure a simple multi-server domain from two or more Oracle CEP servers. The multi-server domain is simple because it is not configured with any custom groups, other than the two predefined ones (singleton group and domain group.) See Configuring Custom Groups for a Multi-Server Domain for a description of how to configure custom groups within the multi-server domain.
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 Creating and Updating an Oracle CEP Standalone-Server Domain for details on creating a domain. |
The following high level steps describe configuring a multi-server domain:
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. |
See Adding New Servers to an Existing Domain Using the Configuration Wizard.
config.xml
files and adding a <cluster>
element with specific information. See Configuring the Servers in a Multi-Server Domain for details.
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 Creating a Standalone-Server Domain Using the Configuration Wizard before continuing with this section.
For clarity, it is assumed that:
user_projects\domains\mydomain
.defaultserver
and the server files are located in the C:\oracle_cep\user_projects\domains\myDomain\myServer1
directory.mydomain
domain called myServer2
.You can use the Configuration Wizard in graphical or silent mode.
Follow these steps to add a new server to an existing domain in graphical mode:
myServer1
.NOTE: When you deploy an application to a group in the domain, Oracle CEP 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.
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.
myDomain
for the domain name and C:\oracle_cep\user_projects\domains
for the domain location. Click Create.Domain created successfully!
Domain location: C:\oracle_cep\user_projects\domains\myDomain
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:
createDomain
.myDomain
and C:\oracle_cep\user_projects\domains, respectively.myServer1
.If the server is on a different machine than the other servers in the multi-server domain, then the ports do not have to be different.
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="myServer1" />
<data-value name="DOMAIN_NAME" value="myDomain" />
<data-value name="DOMAIN_LOCATION" value="C:\oracle_cep\user_projects\domains" />
<data-value name="NETIO_PORT" value="9102" />
<data-value name="RMI_REGISTRY_PORT" value="9104" />
<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>
To configure the servers in a multi-server domain, update the config.xml
file for each member server by adding a <cluster>
child element of the root <config>
element. Include the <server-name>
, <multicast-address>
, <identity>
, and <enabled>
child elements of <cluster>
. The order of the elements is important; see Order and Additional Child Elements of the <cluster> Element for details. The following example shows a possible configuration:
<config>
<domain>
<name>myDomain</name>
</domain>
<cluster>
<server-name>myServer1</server-name>
<multicast-address>239.255.0.1</multicast-address>
<identity>1</identity>
<enabled>true</enabled>
</cluster>
...
</config>
In the example, 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.
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 CEP 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.
The <identity>
element identifies the server’s identity and must be an integer between 1 and INT_MAX. Oracle CEP 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.
The <server-name>
child element of <cluster>
specifies a unique name for the server. 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>
.
Finally, by default the clustering of the servers in a multi-server domain is disabled, so you must explicitly enable it with the <enabled>
element.
An example of configuring a second server, called myServer2
, in the myDomain
multi-server domain is shown below; note that its identity is 2:
<config>
<domain>
<name>myDomain</name>
</domain>
<cluster>
<server-name>myServer2</server-name>
<multicast-address>239.255.0.1</multicast-address>
<identity>2</identity>
<enabled>true</enabled>
</cluster>
...
</config>
See Order and Additional Child Elements of the <cluster> Element for a brief description of additional multi-server-related configuration elements and the required order of child elements.
There are cases where the application logic cannot simply be replicated across a homogenous set of servers in a multi-server domain. Examples of these types of applications are those that must determine the best price provided by different pricing engines, or applications that send an alert when a position crosses a threshold. In these cases, the application is not idempotent; it must calculate only once or send a single event. In other cases, the application has a singleton nature, such as a monitoring application, the HTTP pub-sub server, and so on.
As a more complex example, consider a domain that has two applications: the strategies
application uses several strategies for calculating different prices for some derivative and then feeds its results to a selector
application. The selector
application then selects the best price amongst the different options provided by the strategies’
application results. The strategies
application can be replicated to achieve fault-tolerance. However, the selector
application must be able to keep state so as to determine the best price; for this reason, the selector
application cannot be replicated in a hot/hot fashion.
For all these reasons, a domain must support servers that are not completely homogeneous; you configure this by creating custom groups.
To configure a group, update the config.xml
file of each member of the group, 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. 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 example, assume you have created three servers (myServer1
, myServer2
, and myServer3
) and you want myServer1
to be a member of the selector
group and myServer2
and myServer3
to be members of the strategy
group. The relevant snippets of the config.xml
file for each server are shown below:
<config>
<domain>
<name>myDomain</name>
</domain><cluster>
<server-name>myServer1</server-name>
<multicast-address>239.255.0.1</multicast-address>
<identity>1</identity>
<enabled>true</enabled>
<groups>selector</groups>
</cluster>
...
</config>
<config>
<domain>
<name>myDomain</name>
</domain><cluster>
<server-name>myServer2</server-name>
<multicast-address>239.255.0.1</multicast-address>
<identity>2</identity>
<enabled>true</enabled>
<groups>strategy</groups>
</cluster>
...
</config>
<config>
<domain>
<name>myDomain</name>
</domain><cluster>
<server-name>myServer3</server-name>
<multicast-address>239.255.0.1</multicast-address>
<identity>3</identity>
<enabled>true</enabled>
<groups>strategy</groups>
</cluster>
...
</config>
See Order and Additional Child Elements of the <cluster> Element for a brief description of additional multi-server-related configuration elements and the required order of child elements.
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 Stopping and Starting the Server 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.
When you deploy an application to a multi-server domain, you typically specify a target group, and Oracle CEP then deploys the application to the set of running servers in that group. Oracle CEP dynamically maintains group membership based on running servers. This means that if new servers in the group are started, Oracle CEP automatically propagates the appropriate set of deployments to the new server.
Take, for example, the simple multi-server domain configured in the section Creating and Configuring a Simple Multi-Server Domain. Assume that only myServer1
had been started, and then an application is deployed to the domain group, which includes myServer1
and myServer2
. At that point, because only myServer1
of the multi-server domain has been started, the application will be deployed only to myServer1
. When myServer2
is subsequently started, Oracle CEP automatically replicates and propagates the deployment of the application to myServer2
without the user having the explicitly deploy it.
Deployment propagation only occurs when a server is missing a required deployment. If a server already has a local deployment, then this deployment is used. This means that Oracle CEP does not automatically propagate changes to a deployment on one server of the multi-server domain to the other servers if they already have that deployment. This means that it is possible to have slightly different versions of the same deployment on different servers if the deployment is configured manually through copying application jar files.
If different configuration is required on different servers for an application then currently it is best to achieve this by using system properties.
For complete reference on the Deployer command-line tool, see Deployer Command-Line Reference.
If you do not specify a group when you deploy an application, Oracle CEP deploys the application to the singleton server group that includes only the specific server to which you deploy the application. This is the standard case in single-server domains, but is also applicable to multi-server domains.
Note: | When you upgrade a 2.0 domain to execute in a multi-server domain, any deployed applications are deployed to the singleton server group. |
The following example shows how to deploy to a singleton group; note that the command does not specify a -group
option:
prompt> java -jar wlevsdeploy.jar -url http://ariel:9002/wlevsdeployer -install myapp_1.0.jar
In the example, the myapp_1.0.jar
application will be deployed to the singleton server group that contains a single server: the one running on host ariel
and listening to port 9002
. If the domain is multi-server and other servers are members of the domain group, the application will not be deployed to these servers.
The domain group is a live group that always exists and contains all servers in a domain. In another words, all servers are always a member of the domain group. However, you must still explicitly deploy applications to the domain group. The main reason for this is for simplicity and consistency in usage.
When you explicitly deploy an application to the domain group, Oracle CEP guarantees that all servers of this homogenous environment have this deployment.
To deploy to the domain group, use the -group all
option. The following example shows how to deploy to a domain group:
prompt> java -jar wlevsdeploy.jar -url http://ariel:9002/wlevsdeployer -install myapp_1.0.jar -group all
In the example, the myapp_1.0.jar
application will be deployed to all servers of the domain group on host ariel
listening to port 9002
.
To deploy to a custom group, use the -group
groupname
option of the deploy command.
In the following examples, assume the multi-server domain has been configured as described in Configuring Custom Groups for a Multi-Server Domain.
The following example shows how to deploy an application called strategies_1.0.jar
to the strategygroup
:
prompt> java -jar wlevsdeploy.jar -url http://ariel:9002/wlevsdeployer -install strategies_1.0.jar -group strategygroup
Based on the multi-server domain configuration, the preceding command deploys the application to myServer2
and myServer3
, the members of the group strategygroup
.
The following example shows how to deploy an application called selector_1.0.jar
to the selectorgroup
:
prompt> java -jar wlevsdeploy.jar -url http://ariel:9002/wlevsdeployer -install selector_1.0.jar -group selectorgroup
Based on the multi-server domain configuration, the preceding command deploys the application only to myServer1
, which is the sole member of group selectorgroup
.
Note that both commands are executed to the same server (the one on host ariel
listening to port 9002
). However, you can specify any of the servers in the domain in the deploy command, even if the server is not part of the group to which you want to deploy the application.
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 CEP 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.
As specified by the Server Configuration XSD Schema, the order of the child elements of the <cluster> element in the config.xml file is important; if you include elements in the incorrect order you may encounter an error. The following lists describes the order in which you should list the child elements; see the end of this section for information about elements that have not yet been discussed:
The preceding sections discuss some of the child elements of the <cluster>
element of the config.xml
file, in particular <server-name>
, <multicast-address>
, <identity>
, <groups>
, and <security>
.
This section briefly describes additional child elements. For the complete XSD Schema of the config.xml file, including a description of the <cluster>
element, see
Server Configuration XSD Schema.
You can add the following optional child elements to the <cluster>
element of the config.xml
file to further configure your multi-server domain:
<server-host-name>
—Specifies the host address/IP used for point-to-point HTTP multi-server communication. Default value is localhost
.<multicast-port>
—Specifies the port used for multicast traffic. Default value is 9005
.<operation-timeout>
—Specifies, in milliseconds, the timeout for point-to-point HTTP multi-server requests. Default value is 30000
.
Question: After I deploy my application to a multi-server domain, Oracle CEP stops it after about 30 seconds.
Answer: Be sure you do not have more than one VPN software package installed on the same computer hosting your multi-server domain.