<spring:bean name="componentNotificationLogger" class="org.myfirm.ComponentMessageNotificationLogger"/>
<spring:bean name="endpointNotificationLogger"
class="org.myfirm.EndpointMessageNotificationLogger"/>
Mule Server Notifications
Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version. |
Mule 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:
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
causes 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. |
|
Connection Notification |
A connector connected to its underlying resource or released the connection, or the connection attempt failed. |
|
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. |
|
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. |
|
Exception Notification |
An exception was thrown. |
|
Management Notification |
The state of the Mule instance or its resources have changed. |
|
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. |
|
Mule Context Notification |
An event occurred on the Mule Manager. |
|
Registry Notification |
An event occurred on the registry. |
|
Routing Notification |
A routing event such as an async-reply miss occurred. |
|
Security Notification |
A request was denied security access. |
|
Transaction Notification |
During transaction life cycle after a transaction has begun, was committed, or was rolled back. |
|
Async-Message Notification |
An ansynchronous message arrived. |
|
Pipeline-Message Notification |
A pipelined message arrived. |
|
Message-Processor Notification |
A message processor was invoked. |
|
Exception Strategy Notification |
An exception strategy was invoked. |
|
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 |
|
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 |
Transaction Notification |
Transaction |
Component name |
The component that triggered this notification |