Chapter 79. JMX
JMX Component
The JMX component enables consumers to subscribe to an MBean's notifications. The component supports passing the
Notification object directly through the exchange or serializing it to XML according to the schema provided within this project. This is a consumer-only component. Exceptions are thrown if you attempt to create a producer for it.
Camel on EAP deployment
This component is supported by the Camel on EAP (Wildfly Camel) framework, which offers a simplified deployment model on the Red Hat JBoss Enterprise Application Platform (JBoss EAP) container. For details of this model, see chapter "Apache Camel on Red Hat JBoss EAP" in "Deploying into a Web Server".
In the context of the JBoss EAP container, the JMX component integrates with the JBoss EAP JMX subsystem as follows:
CamelContext camelctx = contextFactory.createWildflyCamelContext(getClass().getClassLoader());
camelctx.addRoutes(new RouteBuilder() {
@Override
public void configure() throws Exception {
String host = InetAddress.getLocalHost().getHostName();
from("jmx:platform?format=raw&objectDomain=org.apache.camel&key.context=" + host + "/system-context-1&key.type=routes&key.name=\"route1\"" +
"&monitorType=counter&observedAttribute=ExchangesTotal&granularityPeriod=500").
to("direct:end");
}
});
camelctx.start();
ConsumerTemplate consumer = camelctx.createConsumerTemplate();
MonitorNotification notifcation = consumer.receiveBody("direct:end", MonitorNotification.class);
Assert.assertEquals("ExchangesTotal", notifcation.getObservedAttribute());URI Format
The component can connect to the local platform MBean server with the following URI:
jmx://platform?options
A remote MBean server URL can be specified after the
jmx: scheme prefix, as follows:
jmx:service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi?options
You can append query options to the URI in the following format,
?option=value&option=value&....
URI Options
| Property | Required | Default | Description |
|---|---|---|---|
format
|
xml
|
Format for the message body. Either xml or raw. If xml, the notification is serialized to XML. If raw, the raw java object is set as the body.
|
|
password
|
Credentials for making a remote connection. | ||
objectDomain
|
Yes | The domain of the MBean you are connecting to. | |
objectName
|
The name key for the MBean you are connecting to. Either this property of a list of keys must be provided (but not both). For more details, see the section called “ObjectName Construction”. | ||
notificationFilter
|
Reference to a bean that implements the NotificationFilter interface. The #beanID syntax should be used to reference the bean in the registry.
|
||
handback
|
Value to hand back to the listener when a notification is received. This value will be put into the jmx.handback message header.
|
||
testConnectionOnStartup
|
true
|
*Camel 2.11* If true, the consumer will throw an exception when unable to establish the JMX connection upon startup. If false, the consumer will attempt to establish the JMX connection every 'x' seconds until the connection is made - where 'x' is the configured reconnectDelay. | |
reconnectOnConnectionFailure
|
false
|
*Camel 2.11* If true, the consumer will attempt to reconnect to the JMX server when any connection failure occurs. The consumer will attempt to re-establish the JMX connection every 'x' seconds until the connection is made-- where 'x' is the configured reconnectDelay. | |
reconnectDelay
|
10
|
*Camel 2.11* The number of seconds to wait before retrying creation of the initial connection or before reconnecting a lost connection. |
ObjectName Construction
The URI must always have the
objectDomain property. In addition, the URI must contain either objectName or one or more properties that start with key.
Domain with Name property
When the
objectName property is provided, the following constructor is used to build the ObjectName instance for the MBean:
ObjectName(String domain, String key, String value)
The
key value in the preceding constructor must be name and the value is the value of the objectName property.
Domain with Hashtable
ObjectName(String domain, Hashtable<String,String> table)
The
Hashtable is constructed by extracting properties that start with key. The properties will have the key prefix stripped prior to building the Hashtable. This allows the URI to contain a variable number of properties to identify the MBean.
Example
from("jmx:platform?objectDomain=jmxExample&key.name=simpleBean").
to("log:jmxEvent");Full example
A complete example using the JMX component is available under the
examples/camel-example-jmx directory.
Monitor Type Consumer
Available as of Camel 2.8 One popular use case for JMX is creating a monitor bean to monitor an attribute on a deployed bean. This requires writing a few lines of Java code to create the JMX monitor and deploy it. As shown below:
CounterMonitor monitor = new CounterMonitor();
monitor.addObservedObject(makeObjectName("simpleBean"));
monitor.setObservedAttribute("MonitorNumber");
monitor.setNotify(true);
monitor.setInitThreshold(1);
monitor.setGranularityPeriod(500);
registerBean(monitor, makeObjectName("counter"));
monitor.start();
The 2.8 version introduces a new type of consumer that automatically creates and registers a monitor bean for the specified objectName and attribute. Additional endpoint attributes allow the user to specify the attribute to monitor, type of monitor to create, and any other required properties. The code snippet above is condensed into a set of endpoint properties. The consumer uses these properties to create the CounterMonitor, register it, and then subscribe to its changes. All of the JMX monitor types are supported.
Example
from("jmx:platform?objectDomain=myDomain&objectName=simpleBean&" +
"monitorType=counter&observedAttribute=MonitorNumber&initThreshold=1&" +
"granularityPeriod=500").to("mock:sink");
The example above will cause a new Monitor Bean to be created and depoyed to the local mbean server that monitors the
MonitorNumber attribute on the simpleBean. Additional types of monitor beans and options are detailed below. The newly deployed monitor bean is automatically undeployed when the consumer is stopped.
URI Options for Monitor Type
| property | type | applies to | description |
|---|---|---|---|
monitorType
|
enum
|
all | one of the counters, guage, string |
observedAttribute
|
string
|
all | the attribute being observed |
granularityPeriod
|
long
|
all | granularity period (in millis) for the attribute being observed. As per JMX, default is 10 seconds |
initThreshold
|
number
|
counter | initial threshold value |
offset
|
number
|
counter | offset value |
modulus
|
number
|
counter | modulus value |
differenceMode
|
boolean
|
counter, gauge | true if difference should be reported, false for actual value |
notifyHigh
|
boolean
|
gauge | high notification on/off switch |
notifyLow
|
boolean
|
gauge | low notification on/off switch |
highThreshold
|
number
|
gauge | threshold for reporting high notification |
lowThreshold
|
number
|
gauge | threshold for reporting low notificaton |
notifyDiffer
|
boolean
|
string | true to fire notification when string differs |
notifyMatch
|
boolean
|
string | true to fire notification when string matches |
stringToCompare
|
string
|
string | string to compare against the attribute value |
The monitor style consumer is only supported for the local mbean server. JMX does not currently support remote deployment of mbeans without either having the classes already remotely deployed or an adapter library on both the client and server to facilitate a proxy deployment.
