NotificationWorkers Description

• Overview
  
  The JMX notification mechanism is a flexible, extensible design that can be used for many things. The objects that ship with the Sun JMX RI have several significant drawbacks to using them in a production environment. To list the big ones: they are single threaded and block calls, there is no native event chaining mechanism, and there is no native aggregation menchanism.
  
  The NotificationWorkers try to overcome some fo these limitations. It allows you to make objects into NotificationListeners easily. The NotificationCoupler thread enables the notification framwork.
  
  
  
• The Main Components
  
  
  
  
  • org.jmx4odp.notificationWorker.NotificationLogger
    
    This is a decoupled logging object for MBeans. The logger object will send a notification for any thing logged to it. The notification uses an event thread. This means that the notification will be processed on a sperate thread than the MBean that logs to it. But, since it is an event thread, it can only handle one logging event at a time. So for objects that need to periodically log, this provides a unified mechanism, but will bog down under a high load.
    
    The real strength of this object is that any log hanlder can subscribe to this MBean and start receiving events from the logging MBean.
    
    If this object runs in the context of J4ONet, it will find the local J4ONet configuration and set this information in the Notification source object so that distrubuted systems will know the absolute source of the notification.
    
    
    
  • org.jmx4odp.junitRunner.EventRunner
    
    This MBean uses the Junit TestRunner framework with the JMX4ODP SuiteAssembler to run diagnostic agents in a JMX agent. This bean will use the SuiteAssembler to covert a TestSuite.xml file into a Junit TestSuite and run it in its own TestRunner. It will then propigate each failure and error as an event to the hosting JMX agent. Other objects can then subscribe to this MBean to listen for these failure/error events. So this object can act as the sensors for a JMX based monitoring system.
    
    It will log error messages to the error topic and failures to the failure topic. The messages will be formated like TestFailure.getName() + ": " + failure.toString() and it failure.toString() returns a null, it will use failure.thrownException().toString().
    
    
    
  • org.jmx4odp.notificationWorker.NotificationCoupler
    
    Traditionally, the NotificationListener plugs into a NotificationBroadcaster. This works just like other Java event/notification models. The broadcaster is responsible for tracking all of the registered listeners and sending the notification to each of them.
    
    In the JMX model, the Listener is not allowed to modify the passback object, or to veto the event. So there is no practical reason to notify each listener serially or to wait upon it to handle the object. In fact, this could introduce latency into the system. Imagine if when you clicked on a Swing button if you had to wait for processing to finish before it could handle another event. The javax.management.NotificationBroadcasterSupport is not threaded and does just this.
    
    The NotificationCoupler is simply both a listener and a broadcaster. You register it with a broadcaster and it listens for its events. Then when the NotificationCoupler receives an event, it will cycle through all of its registered listeners. For each listener, the coupler will spawn a thread and dispatch the notification to the listener. This should help with latency issues. This also means that you have no guarantee in which order the notification events will be handled. In addition, the coupler holds listners as WeakReferences, so this object will not prevent them or their resources from being reclaimed or collected.
    
    
    
  • org.jmx4odp.notificationWorker.NotificationWorker
    
    This object's intention is to make it easier to create NotificationListener and to wrap the basic functionality for notifactionListeners. It makes the listener managable as an MBean, through which you can add and remove listened to objects, add and remove notification types from a filter, and set the listener as active/inactive.
    
    This object will listen for Notifications and send them to a NotificationProcessor. The easiest way is to extend this object and have your MBeanInterface extend the NotificationWorkerMBean interface. No have your extended class implement a NotificationProcessor object and regsiter it.
    
    
    
  • org.jmx4odp.notificationWorker.NotificationProcessor
    
    Objects must implement this interface to be regsitered with NotificationWorkers. When the NotificationWorker receives a notification that passes the filters, it will pass it to its registered NotificationProcessor. When the NotificationWorker is set to active, it will cann preStart on the NotificationProcessor. When the object is set to inactive, it will call postStop. If the NotificationWorker's NotifcationProcessor is set to null, it will set active to false.
    
    
    
  • org.jmx4odp.notificationWorker.NotificationMailer
    
    This object implements the NotificationListener interface. It uses the javax.mail library to send these Notifications as email. It takes a list of target address and a list of Notification Types. Whenever it receives a notification that is one of the types, or it's children, it will send an email addressed to everyone on the list.
    
    In pagerMode, it will igonore the subjectLine and send the notification message as the subject line. When pagerMode is off, it will use the provided subject line and send the notification message as the email message, and it will include a header to tell where the email is comming from.