Administration and Configuration Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Managing Applications, Servers, and Domains Using MBeans

This section contains information on the following subjects:


Overview of Management

Oracle CEP applications define an event processing network (EPN) that is made up of components such as processors, streams, and adapters. You deploy these applications to an Oracle CEP instance that has been started in a domain.

Note: Components are also sometimes referred to as stages, in particular in the management Javadocs. However, for consistency with the rest of the Oracle CEP documentation, this section uses the term components.

You can dynamically configure each component in the EPN using managed beans, or MBeans. Typical configuration tasks include adding and removing EPL rules, changing stream max size, subscribing to notifications, and executing operations. You manipulate the MBeans either by using the standard Java Management Extension (JMX) APIs, using wlevs.Admin (the Oracle CEP administration command-line utility) or Visualizer, a graphical administration tool. It is assumed in this section you are going to use JMX. See the following sections for information on using wlevs.Admin or Visualizer:

You can also perform some configuration and application life cycle management of the server, domain, and deployed applications using MBeans, although this section predominantly describes configuring individual application components. However, because server, domain, and application configuration is also done using MBeans, much of the information in this section is applicable.

Each component in a deployed application (adapter, stream, or processor) has a configuration MBean that manages the underlying configuration of the component. Each type of component has its own set of manageable artifacts. For example, you can dynamically configure the maximum number of threads for a stream or the EPL rules associated with a processor.

You can also gather monitoring information for each component in the EPN using runtime MBeans. Monitoring information includes throughput (number of events passing through a component) and latency (how long it takes an event to pass through a component)


Overview of Oracle CEP MBeans

Oracle CEP exposes the following types of MBeans:

For full reference information about Oracle CEP MBeans and management in general, see the following Javadocs:

Configuration MBeans

When you deploy an Oracle CEP application, the server automatically creates a configuration MBean for each component in the EPN whose manageability has been enabled, or in other words, for each component registered in the EPN assembly file. If you have extended the configuration of an adapter, then the server deploys a a custom configuration MBean for the adapter.

Using JMX, you can dynamically configure the component using its configuration MBean. For example, using the StreamMBean.setMaxSize() method you can set the size of a stream component.

Runtime MBeans

You can also gather monitoring information for each component in the EPN using runtime MBeans. WebLogic Event Server defines the following metrics that you can monitor for each component:


MBean Hierarchy

The following graphic describes the Oracle CEP MBean tree.

All MBeans must be registered in an MBean server under an object name of type Oracle CEP follows a convention in which object names for child MBeans contain part of its parent MBean object name.

There are two main MBean roots: DomainMBean and DomainRuntimeMBean. The former includes configuration MBeans for the entire domain, the latter contains runtime information, such as statistics, and local services, such as Monitor, that are generally scoped to a single server instance.

ApplicationMBean is a child of the DomainMBean instead of the ServerMBean. This is because an application is unique within a domain, and can span multiple servers.

The following diagram shows the main classes and relationships that make up the object model.

Most MBeans are notification emitters that generate AttributeChangeNotifications. In other words, a JMX client can register to receive attribute change notifications regarding changes to application state, insertion and removal of applications at the domain, stream size and thread changes, insertion and removal of rules, and so on.


MBean Naming

This section is divided into configuration and runtime MBean naming.

Configuration MBean Naming

Oracle CEP configuration MBeans are arranged in a hierarchy. The object name of each MBean reflects its position in the hierarchy. A typical object naming pattern is as follows:



The order of the key properties is not significant, but the object name must begin with com.bea:wlevs:.

For example, the object name of the MBean corresponding to a processor called myprocessor in the application myapplication in the domain is as follows:


The following table describes the key properties that Oracle WebLogic Server encodes in its MBean object names.

Table 6-1 Oracle CEP MBean Object Name Key Properties
This Key Property
The string that you provided when you created the resource that the MBean represents. This is typically the name of a component.
The name of a particular component is specified in the EPN assembly file using the id attribute of the component registration.
For example, in the case of processors, the entry in the EPN assembly file might look like the following:

<wlevs:processor id="myprocessor" manageable="true" />

In this case, the key property would be Name=myprocessor.
The short name of the MBean's type. The short name is the unqualified type name without the MBean suffix.
For example, for an MBean that is an instance of the EPLProcessorMBean, use EPLProcessor. In this case, the key property would be Type=EPLProcessor.
Specifies the type and name of the parent MBean.
For components, this is always Application=application_name, where application_name refers to the name of the application of which the component is a part.
The name of a particular Oracle CEP application is specified with the Bundle-SymbolicName header of the MANIFEST.MF file of the application bundle. For example, if an application has the following MANIFEST.MF snippet (only relevant parts are shown):

Manifest-Version: 1.0
Build-Jdk: 1.5.0_06
Bundle-SymbolicName: myapplication

then the key property would be Application=myapplication.

The following table shows examples of configuration MBean objects names that correspond to the component declarations in the HelloWorld sample EPN assembly file. In each example, the application name is helloworld and the domain name is mydomain

Table 6-2 Component Declaration Example With Corresponding MBean Object Names
Sample Component Declaration in EPN Assembly File
Corresponding Configuration MBean Object Name
id="helloworldProcessor" />
EPLProcessor is the standard configuration MBean for processor components. The manageable property is rules.
<wlevs:listener ref="helloworldProcessor"/>
<wlevs:source ref="helloworldAdapter"/>
Stream is the standard configuration MBean for a stream component. The manageable properties are MaxSize and MaxThreads.

Runtime MBean Naming

Runtime MBeans are named using the same pattern as with configuration mbeans except for one extra property: Direction. This property has two valid values: OUTBOUND or INBOUND that refere to the point at which you want to gather the statistic OUTBOUND means that you want to gather throughput or latency as events flow out of the specified component; similary INBOUND means you want to gather the monitoring information as events flow into a component.

For example, the object name of the runtime MBean corresponding to a processor called myprocessor in the application myapplication, in which events will be monitored as they flow into the component, is as follows:


See Configuration MBean Naming for details about configuration MBean naming.


Dynamically Configuring a Component Using JMX: Typical Steps

It is assumed in this section that you are going to use the Java Management Extensions (JMX) APIs to manipulate the configuration MBeans. If you want to use wlevs.Admin, see wlevs.Admin Command-Line Reference. Be sure you have read the following sections that describe Oracle CEP configuration MBeans:

To dynamically configure a component of an EPN, follow these steps:

  1. Be sure that the JMX service is configured for your domain. For details see Configuring JMX for Oracle Complex Event Processing.
  2. Write the JMX Java code to configure the component using the appropriate MBean. See Programming with JMX for some programming hints.

Programming with JMX

One of the first things you must do in your JMX program is to establish a connection to the JMX server running in the Oracle CEP server. The following code snippet shows an example:

public static void initConnection(String hostname, int port, String username, char[] password) 
throws IOException, MalformedURLException {
  JMXServiceURL serviceURL = new JMXServiceURL("rmi", "localhost", 9004, "/jndi/rmi://localhost:" + 9004 + "/jmxrmi");
System.out.println("Service: " + serviceURL.toString());
Map<String,Object> h = makeSecureEnv();
connector = JMXConnectorFactory.connect(serviceURL, h);
connection = connector.getMBeanServerConnection();

The JMXConnectorFactory.connect() method takes as a second parameter a Map object that sets up a secure environment using the makeSecureEnv() method, which looks like the following:

private static Map<String,Object> makeSecureEnv() {
Map<String,Object> env = new HashMap<String,Object>();
String username = "wlevs" ;
char[] password = { 'w','l','e','v','s' };
env.put(JMXConnector.CREDENTIALS, new Serializable[]{username,password});
env.put("jmx.remote.authenticator", "com.bea.core.jmx.server.CEAuthenticator");
System.setProperty("jmx.remote.authenticator", "com.bea.core.jmx.server.CEAuthenticator");
return env;

The example then shows how to start getting information about the domain and its deployed applications by querying MBeans. First the code shows how to get all MBeans whose type is Domain; there should only be one. Then, using the DomainMBean, the sample shows how to retrieve a list of all the deployed applications in the domain (using ApplicationMBean):

Set domainObjectNames = 
ManagementConstants.DOMAIN_NAME + ":" +
ManagementConstants.TYPE_PROPERTY + "=" +
DomainMBean.MBEAN_TYPE + ",*"), null);
ObjectName domainName = 
((ObjectInstance) domainObjectNames.iterator().next()).getObjectName();
System.out.println("Domain Name: " + domainName.getKeyProperty(ManagementConstants.NAME_PROPERTY));
ObjectName [] applicationNames =
(ObjectName[]) connection.getAttribute(domainName, "ApplicationMBeans");
ObjectName selectedApplicationObjectName = null ;
for (ObjectName applicationName : applicationNames) {
String name =
String status =
(String) connection.getAttribute(applicationName, "State");
System.out.println("Application: " + name + " Status: " + status);
selectedApplicationObjectName = applicationName ;


Dynamically Monitoring the Throughput and Latency of a Component

The first thing you do is get an instance of a MonitorRuntimeMBean for the component you want to monitor. Be sure you specify whether you want to monitor incoming events (INBOUND) or outgoing events (OUTBOUND). For example:

  m_processorInbound =

The MonitorRuntimeMBean has methods for each type of statistic you can gather. For example, you execute monitorAvgLatency() if you want to monitor the average latency, monitorAvgThroughput() to monitor the average throughput, and so on. These methods all retuan ProbeRuntimeMBean. For example:

ObjectName probeON = m_testBean.getMonitorRuntimeMBean().monitorAvgThroughput(m_processorInbound, 1000, 1000);

Once you you have an instance of the ProbeRuntimeMbean, you have two ways of getting the actual runtime metrics:

When you are finished gathering monitoring information, use ProbeRuntimeMBean.terminate() to unregister the MBean from the MBean server.

For additional details about these MBean interfaces and how to use them to monitor throughput and latency, see runtime monitoring Javadocs.

  Back to Top       Previous  Next