Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.3)
  3. Deploying Mule ESB 3

  4. Mule Server Notifications

Mule Server Notifications

Mule ESB provides an internal notification mechanism that you can use to access changes that occur on the Mule Server, such as a flow component being added, a Mule Model being initialized, or Mule being started. You can set up your agents or flow components to react to these notifications.

Configuring Notifications

Message notifications provide a snapshot of all information sent into and out of the Mule Server. These notifications are fired whenever a message is received or sent. These additional notifications have some impact on performance, so they are disabled by default. To enable message notifications, you set the type of messages you want to enable using the <notifications> element in your Mule configuration file. You also register the notification listeners and associate interfaces with specific notifications.

For example, first you create beans for the notification listeners, specifying the class of the type of notification you want to receive:

<spring:bean name="componentNotificationLogger" class="org.myfirm.ComponentMessageNotificationLogger"/>
<spring:bean name="endpointNotificationLogger"
class="org.myfirm.EndpointMessageNotificationLogger"/>

Next, you specify the notifications you want to receive using the <notification> element, and then register the listeners using the <notification-listener> element:

<notifications>
  <notification event="COMPONENT-MESSAGE"/>
  <notification event="ENDPOINT-MESSAGE"/>
  <notification-listener ref="componentNotificationLogger"/>
  <notification-listener ref="endpointNotificationLogger"/>
</notifications>

When you specify the COMPONENT-MESSAGE notification, a notification is sent before and after a component is invoked. When you set ENDPOINT-MESSAGE, a notification is sent whenever a message is sent, dispatched, or received on an endpoint. Because the listeners implement the interface for the type of notification they want to receive (for example, the ComponentMessageNotificationLogger class would implement org.mule.api.context.notification.ComponentMessageNotificationListener), the listeners receive the correct notifications.

For a list of notification types, see Notifications Configuration Reference. For a list of notification listener interfaces, see Notification Interfaces below.

Specifying a Different Interface

If you want to change the interface that is associated with a notification, you specify the new interface with the interface-class and interface attributes:

<notifications>
  <notification event="COMPONENT-MESSAGE" interface-class="org.myfirm.MyMessageNotifications" interface="myComponentListener"/>

Configuring a Custom Notification

If you create a custom notification, you also specify the event-class attribute:

<notifications>
  <notification event="CUSTOM-MESSAGE" event-class="org.myfirm.MyMessageNotificationsCustomMessage"
interface-class="org.myfirm.MyMessageNotifications" interface="myCustomListener"/>
...

Disabling Notifications

If you want to block a specific interface from receiving a notification, you specify it with the <disable-notification> element. You can specify the notification type (event), event class, interface, and/or interface class to block.

<notifications>
  <disable-notification interface="ComponentMessageNotificationListener"/>
...

Using Subscriptions

When registering a listener, you can specify that it only receive notifications from a specific component using the subscription attribute. For example, to specify that the listener only receive notifications from a flow component called "MyService1", you would configure the listener as follows:

<notification-listener ref="endpointNotificationLogger" subscription="MyService1"/>

You can also register listeners and filter the subscriptions from your Java code:

muleContext.registerListener(listener, "MyService1");

To register interest in notifications from all flow components with "Service" in the name, you would use a wildcard string as follows:

muleContext.registerListener(listener, "*Service*");

For more information, see Registering Listeners Programmatically below.

Firing Custom Notifications

Custom notifications can be fired by objects in Mule to notify custom listeners. For example, a discovery agent might fire a Client Found notification when a client connects.

You fire a custom notification as follows:

CustomNotification n = new CustomNotification("Hello");
muleContext.fireNotification(n);

Any objects implementing CustomNotificationListener will receive this notification. It’s a good idea to extend CustomNotification and define actions for your custom notification type. For example:

DiscoveryNotification n = new DiscoveryNotification(client, DiscoveryNotification.CLIENT_ADDED);
muleContext.fireNotification(n);

Note that non-system objects in Mule can only fire custom notifications through the manager. Attempting to fire other notifications such as ModelNotification will cause an UnsupportedOperationException.

Notification Interfaces

The following table describes the Mule server notifications and the interfaces in the

org.mule.api.context.notification

class an object can implement to become a listener for that notification. All listeners extend the ServerNotificationListener interface.

Notification Description Interface

Component Message Notification

A message was processed by a flow component. These notifications are very good for tracing, but they are not enabled by default because they have an impact on performance.

ComponentMessageNotificationListener

Connection Notification

A connector connected to its underlying resource or released the connection, or the connection attempt failed.

ConnectionNotificationListener

Custom Notification

Can be fired by objects themselves to custom notification listeners and can be used to customize notifications on agents, flow components, connectors, and more.

CustomNotificationListener

Endpoint Message Notification

A message was sent or received from an endpoint. These notifications are very good for tracing, but they are not enabled by default because they have an impact on performance.

EndpointMessageNotificationListener

Exception Notification

An exception was thrown.

ExceptionNotificationListener

Management Notification

The state of the Mule instance or its resources have changed.

ManagementNotificationListener

Model Notification

The state is changing on a model, such as initializing, starting and stopping, or flow components within the model are being registered or unregistered.

ModelNotificationListener

Mule Context Notification

An event occurred on the Mule Manager.

MuleContextNotificationListener

Registry Notification

An event occurred on the registry.

RegistryNotificationListener

Routing Notification

A routing event such as an async-reply miss occurred.

RoutingNotificationListener

Security Notification

A request was denied security access.

SecurityNotificationListener

Service Notification

An event occurred on a service.

ServiceNotificationListener

Transaction Notification

During transaction life cycle after a transaction has begun, was committed, or was rolled back.

TransactionNotificationListener

Async-Message Notification

An ansynchronous message arrived.

AsyncMessaheNotificationListener

Pipeline-Message Notification

A pipelined message arrived.

PipelineMessageNotificationListener

Message-Processor Notification

A message processor was invoked.

MessageProcessorNotificationListener

Exception Strategy Notification

An exception strategy was invoked.

ExceptionStrategyNotificationListener

The listener interfaces all have a single method:

public void onNotification(T notification);

where T is a notification class (listener class without the 'Listener' at the end).

Depending on the listener implemented, only certain notifications will be received. For example, if the object implements ManagerNotificationListener, only notifications of type ManagerNotification will be received. Objects can implement more than one listener to receive more types of notifications.

Registering Listeners Programmatically

You can register listeners on the Mule Context as follows:

muleContext.registerListener(listener);

Registering Listeners Dynamically

By default, you cannot register listeners in the Mule context after Mule has started. Therefore, you would register your listeners in your code before starting Mule. For example:

MuleContext context = new DefaultMuleContextFactory().createMuleContext
(new SpringXmlConfigurationBuilder("foo-config.xml"));
context.registerListener(listener, "*Service*");
context.start();

To change this behavior so that you can add listeners dynamically at run time, you can set the dynamic attribute on the <notifications> element. If you just want to enable dynamic notifications for a specific connector, you can set the dynamicNotification attribute on the connector.

Depending on the nature of your app you may need to call context.unregisterListener() to prevent memory leaks.

Notification Action Codes

Each notification has an action code that determines the notification type. The action code can be queried to determine its type. For example:

MyObject.java

public class MyObject implements ConnectionNotificationListener<ConnectionNotification>, MuleContextAware
{

    // muleContext injection and field omitted for brevity

    public void onNotification(ConnectionNotification notification)
    {
        if (notification.getAction() == ConnectionNotification.CONNECTION_FAILED)
        {
            System.out.println("Connection failed");
        }
    }
}

For a list of the action codes available with each notification type, see the Javadocs for the

org.mule.context.notification

package and click on the class of the notification type you want.

Notification Payloads

All notifications extend java.util.EventObject, and the payload of the object can be accessed using the getSource() method. The following table describes the payloads for each type of notification.

Notification Payload Type Resource ID Description

Component Message Notification

Component

Component name

The flow component that triggered this notification

Connection Notification

Connectable

<connector-name>.receiver(<endpoint-uri>)

The message receiver or message dispatcher that was connected

Custom Notification

Any object

Any String

The object type is custom to the object firing the notification

Endpoint Message Notification

ImmutableEndpoint

Endpoint URI

The endpoint that triggered this notification

Exception Notification

Throwable

Component Name

The flow component that triggered this notification

Management Notification

Object

The object ID

The monitored object that triggered this notification

Model Notification

Model

Model Name

The Model instance on the Mule Context. Equivalent to calling MuleContext.getRegistry().lookupModel()

Mule Context Notification

MuleContext

Mule context ID

The Mule context instance. Equivalent to calling getMuleContext().

Registry Notification

Registry

Mule registry ID

The Mule registry. Equivalent to calling MuleContext.getRegistry().

Routing Notification

MuleMessage

Message ID

The message sent or received

Security Notification

SecurityException

The exception message

The security exception that occurred

Service Notification

Service

Service ID

The service that triggered this notification

Transaction Notification

Transaction

Component name

The component that triggered this notification