JBoss.org Community Documentation
The JMX standard defines a timer MBean (javax.management.timer.Timer) which can send notifications at predetermined times. The a timer MBean can be instantiated within JBoss as any other MBean.
<mbean code="javax.management.timer.Timer" name="jboss.monitor:name=Heartbeat,type=Timer"/>
A standard JMX timer doesn't produce any timer events unless it is asked to. To aid in the configuration of the timer MBean, JBoss provides a complementary TimerService MBean. It interacts with the timer MBean to configure timer events at regular intervals and to transform them into JMX notifications more suitable for other services. The TimerService MBean takes the following attributes:
NotificationType : This is the type of the notification to be generated.
NotificationMessage : This is the message that should be associated with the generated notification.
TimerPeriod
: This is the time period between notification. The time period is in milliseconds, unless otherwise specified with a unit like "30min" or "4h". Valid time suffixes are msec, sec, min and h.
Repeatitions : This is the number of times the alert should be generated. A value of 0 indicates the alert should repeat indefinitely.
TimerMbean
: This is the ObjectName of the time MBean that this TimerService instance should configure notifications for.
The following sample illustrates the the use of the TimerService MBean.
<mbean code="org.jboss.monitor.services.TimerService"
name="jboss.monitor:name=Heartbeat,type=TimerService">
<attribute name="NotificationType">jboss.monitor.heartbeat</attribute>
<attribute name="NotificationMessage">JBoss is alive!</attribute>
<attribute name="TimerPeriod">60sec</attribute>
<depends optional-attribute-name="TimerMBean">
jboss.monitor:name=Heartbeat,type=Timer
</depends>
</mbean>
This MBean configuration configures the jboss.monitor:name=Heartbeat,type=Timer timer to generate a jboss.monitor.heartbeat notification every 60 seconds. Any service that that wants to receive this periodic notifications can subscribe to the notification.
As an example, JBoss provides a simple NotificationListener MBean that can listen for a particular notification and log a log message when an event is generated. This MBean is very useful for debugging or manually observing notifications. The following MBean definition listens for any events generated by the heartbeat timer used in the previous examples.
<mbean code="org.jboss.monitor.services.NotificationListener"
name="jboss.monitor:service=NotificationListener">
<attribute name="SubscriptionList">
<subscription-list>
<mbean name="jboss.monitor:name=Heartbeat,type=Timer" />
</subscription-list>
</attribute>
</mbean>
The subscription-list element lists which MBeans the listener should listen to. Notice that the MBean we are listening to is the name of the actual timer MBean and not the TimerService MBean. Because the timer might generate multiple events, configured by multiple TimerService instances, you may need to filter by notification type. The filter element can be used to create notification filters that select only the notification types desired. The following listing shows how we can limit notifications to only the jboss.monitor.heartbeat type the timer service configured.
<mbean code="org.jboss.monitor.services.NotificationListener"
name="jboss.monitor:service=NotificationListener">
<attribute name="SubscriptionList">
<subscription-list>
<mbean name="jboss.monitor:name=Heartbeat,type=Timer">
<filter factory="NotificationFilterSupportFactory">
<enable type="jboss.monitor.heartbeat"/>
</filter>
</mbean>
</subscription-list>
</attribute>
</mbean>
As an example of a slightly more interesting listener, we'll look at the ScriptingListener. This listener listens for particular events and then executes a specified script when events are received. The script can be written in any bean shell scripting language. The ScriptingListener accepts has the following parameters.
ScriptLanguage
: This is the language the script is written in. This should be beanshell, unless you have loaded libraries for another beanshell compatible language.
Script : This is the text of the script to evaluate. It is good practice to enclose the script in a CDATA section to minimize conflicts between scripting language syntax and XML syntax.
SubscriptionList : This is the list of MBeans that this MBean will listen to for events that will trigger the script.
The following example illustrates the use of the ScriptingListener. When the previously configured timer generates a heartbeat notification, the beanshell script will execute, printing the current memory values to STDOUT. (This output will be redirected to the log files) Notice that the beanshell script has a reference to the MBean server and can execute operations against other MBeans.
<mbean code="org.jboss.monitor.services.ScriptingListener"
name="jboss.monitor:service=ScriptingListener">
<attribute name="SubscriptionList">
<subscription-list>
<mbean name="jboss.monitor:name=Heartbeat,type=Timer"/>
</subscription-list>
</attribute>
<attribute name="ScriptLanguage">beanshell</attribute>
<attribute name="Script">
<![CDATA[
import javax.management.ObjectName;
/* poll free memory and thread count */
ObjectName target = new ObjectName("jboss.system:type=ServerInfo");
long freeMemory = server.getAttribute(target, "FreeMemory");
long threadCount = server.getAttribute(target, "ActiveThreadCount");
log.info("freeMemory" + freeMemory + ", threadCount" + threadCount);
]]>
</attribute>
</mbean>
Of course, you are not limited to these JBoss-provided notification listeners. Other services such as the barrier service (see Section 10.9, “The BarrierController Service”) receive and act on notifications that could be generated from a timer. Additionally, any MBean can be coded to listen for timer-generated notifications.