This section contains information on the following subjects:
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)
Oracle CEP exposes the following types of MBeans:
EPLProcessorMBean
and StreamMBean
.See Configuration MBeans for additional information.
See Runtime MBeans.
For full reference information about Oracle CEP MBeans and management in general, see the following Javadocs:
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.
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:
The following graphic describes the Oracle CEP MBean tree.
All MBeans must be registered in an MBean server under an object name of type javax.management.ObjectName
. 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.
This section is divided into configuration and runtime 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:
com.bea.wlevs:Name=name,Type=type,[TypeOfParentMBean
=NameOfParentMBean]
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:
com.bea.wlevs:Name=myprocessor,Type=EPLProcessor,Application=myapplication
The following table describes the key properties that Oracle WebLogic Server encodes in its MBean object names.
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
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:
com.bea.wlevs:Name=myprocessor,Type=EPLProcessor,Application=myapplication,Direction=INBOUND
See Configuration MBean Naming for details about configuration MBean naming.
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:
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 =
connection.queryMBeans(ObjectName.getInstance(
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 =
applicationName.getKeyProperty(ManagementConstants.NAME_PROPERTY);
String status =
(String) connection.getAttribute(applicationName, "State");
System.out.println("Application: " + name + " Status: " + status);
selectedApplicationObjectName = applicationName ;
}
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 =
ObjectName.getInstance("com.bea.wlevs:Name=myprocessor,Type=EPLProcessor,Application=myapplication,Direction=INBOUND");
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.