MBean listeners
Resin 3.0

Features
Installation
Configuration
Web Applications
IOC/AOP
Resources
JSP
Quercus
Servlets and Filters
Databases
Admin (JMX)
CMP
EJB
Amber
EJB 3.0
Security
XML and XSLT
XTP
JMS
Performance
Protocols
Third-party
Troubleshooting/FAQ

Servlet
JMX Consoles
Instrumenting
Tutorials
Cookbook

Basic JMX
MBeanServer
Listener
Registration
MBeanServer
Tutorials
Registration

Find this tutorial in: /usr/local/resin/webapps/resin-doc/jmx/tutorial/listener
Try the Tutorial
Example showing configuration of MBean event listeners.

  1. Files in this tutorial
  2. Emitter and Listener
    1. web.xml configuration
    2. Using the listener
    3. Configuration with Dependency Injection
  3. Compatibility

Files in this tutorial

WEB-INF/web.xml Configures the JMX-managed bean
WEB-INF/classes/example/Listener.java The listener bean implementation.
WEB-INF/classes/example/ListenerMBean.java The management interface for the listener.
WEB-INF/classes/example/Emitter.java The emitter bean implementation.
WEB-INF/classes/example/EmitterMBean.java The management interface for the emitter.
WEB-INF/classes/example/ListenerServlet.java Using the managed bean.

Emitter and Listener

JMX provides a general notification capability where MBean emitters send data to MBean listeners. Any managed bean can be an emitter or a listener by implementing the proper interfaces. The listeners are hooked up to the emitters either in the configuration file or through MBeanServer calls.

A listener implements NotificationListener to receive Notification events. The notification contains information for the type of the notification, the sender of the notification, and any notification-specific information.

The listener implements the single handleNotification method. It's parameters are the notification and an opaque handback object. The handback is specified during the listener registration and can be any information the listener wants.

Listener.java
package example;

import javax.management.NotificationListener;
import javax.management.Notification;

public class Listener
  implements NotificationListener, ListenerMBean {
  private int _count;

  public void handleNotification(Notification notif,
                                 Object handback)
  {
    _count++;
  }

  public int getNotificationCount()
  {
    return _count;
  }
}

The Emitter sends notifications. Any managed bean which implements the NotificationEmitter interface can be an emitter. Many Emitters will extend the NotificationBroadcasterSupport, although this is not required.

NotificationBroadcasterSupport will handle the logic for adding and removing listeners as well as sending notifications to the proper listener. By extending NotificationBroadcasterSupport, the emitter only needs to call sendNotification to send the notification.

The first argument for the Notification is the notification type. Because each emitter can send multiple notifications, the type tells the listener which event has happened.

The second argument is typically the ObjectName for the emitter. Often, emitters will use the MBeanRegistration interface to find out the ObjectName.

Emitter.java
package example;

import javax.management.NotificationBroadcasterSupport;
import javax.management.Notification;

/**
 * Implements an MBean which sends notifications.
 */
public class Emitter extends NotificationBroadcasterSupport
  implements EmitterMBean {
  private long _sequence;
  
  /**
   * Sends a notification.
   */
  public void send()
  {
    Notification notif;

    notif = new Notification("example.send", this, _sequence++);

    sendNotification(notif);
  }
}

web.xml configuration

The web.xml (or resin.conf) configures the resource with the <resource> tag just as with other resources . The resources is registered as an MBean by specifying an mbean-name.

web.xml
<web-app xmlns="http://caucho.com/ns/resin">
  <resource mbean-name="example:name=emitter"
            type="example.Emitter">
  </resource>

  <resource mbean-name="example:name=listener"
            type="example.Listener">
    <listener mbean-name="example:name=emitter" handback="tutorial"/>
  </resource>
</web-app>

tagdescription
resourcedefines the resource
mbean-namethe MBean name of the resource
typethe class name of the resource bean
listenerregisters the mbean with a notification emitter mbean
handbacka custom object to be passed back to the listener

Using the listener

This example provides a send() method to trigger a notification, but most notifications occuring when specific events occur, e.g. when a pool fills up.

In this case, invoking the send() method triggers the notification which will be sent to any waiting listeners. Calling listener.getNotificationCount() checks that the listener is getting called back.

ListenerServlet.java
public class ListenerServlet extends GenericServlet {
  private EmitterMBean _emitter;
  private ListenerMBean _listener;

  public void setEmitter(EmitterMBean emitter)
  {
    _emitter = emitter;
  }

  public void setListener(ListenerMBean listener)
  {
    _listener = listener;
  }

  public void service(ServletRequest request,
		      ServletResponse response)
    throws ServletException, IOException
  {
    PrintWriter out = response.getWriter();
    
    _emitter.send();

    out.println("listener count: " + _listener.getNotificationCount());
  }
}

output
count: 15

log
[15:37:15.545] notification(type=example.send,handback=tutorial)
[15:37:16.624] notification(type=example.send,handback=tutorial)
[15:37:17.453] notification(type=example.send,handback=tutorial)

Configuration with Dependency Injection

The ListenerServlet example follows the Dependency Injection pattern. Resin's web.xml will assemble the correct EmitterMBean and ListenerMBean. Using the Dependency Injection pattern simplifies the servlet, makes it more configurable, and more testable.

The configuration takes advantage of the "mbean:" JNDI scheme in Resin. The name following "mbean:" is used to lookup the mbean instance. The "mbean:" scheme then constructs a proxy for the mbean. The proxy of the JNDI lookup is then passed to setEmitter and setListener.

web.xml
<servlet-mapping url-pattern="/listener"
                 servlet-class="example.ListenerServlet">
  <init>
    <emitter>${jndi:lookup("mbean:example:name=emitter")}</emitter>
    <listener>${jndi:lookup("mbean:example:name=listener")}</listener>
  </init>
</servlet-mapping>

Compatibility

Notifications and listeners are part of the JMX standard. Client MBean proxies are standard and can be generated with javax.management.MBeanServerInvocationHandler

The <resource> configuration is Resin-specific. The support for the Dependency Injection for servlet configuration and the "mbean:" JNDI scheme are also Resin-specific.

Try the Tutorial


MBeanServer
Tutorials
Registration
Copyright © 1998-2006 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.