---
schema_version: "1"
id: 1f1cf9d7b30438848e8f1d37f1e045c05478382d17c1db379faa934226ebc60e
title: Mule Server Notifications
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-runtime/4.4/mule-server-notifications.md
canonical_url: https://docs.mulesoft.com/mule-runtime/4.4/mule-server-notifications
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 868e9a5d9dfa965183fc1d821a1e06335430ac83dfeebbb9dbc76f2ab6bbe8a4
description: MuleSoft Documentation Site
release: "4.4"
latest: false
---
---
product: Mule Runtime
version: 4.4
---

# Mule Server Notifications

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Mule provides an internal notification mechanism that you can use to access changes that occur on
the Mule Server, such as adding a flow component, a request for authorization failing, or Mule
starting. 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.
Mule fire these notifications whenever it receives or sends a message. 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 in your spring configuration
file, specifying the class of the type of notification you want to receive:

```xml
<bean name="notificationLogger" class="org.myfirm.ProcessorNotificationStore"/>
```

And then, add the reference for your spring configuration:

```xml
<spring:config name="springConfig" files="notification-beans.xml"/>
```

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

```xml
<notifications>
    <notification event="MESSAGE-PROCESSOR"/>
    <notification-listener ref="notificationLogger"/>
</notifications>
```

When you specify the MESSAGE-PROCESSOR notification, a notification is sent before and after a
message processor is invoked. Because the listeners implement the interface for the type of
notification they want to receive, the listeners receive the correct notifications.

For example, the `ProcessorNotificationLogger` class would implement
`org.mule.runtime.api.notification.MessageProcessorNotificationListener`:

```java
public class ProcessorNotificationLogger implements MessageProcessorNotificationListener<MessageProcessorNotification> {

    @Override
    public void onNotification(MessageProcessorNotification notification) {
        // write here the logic to process the notification event
    }
}
```

> [!CAUTION] Don’t forget to add the mule-api dependency in your pom file with `provided` as scope,
> so the api classes will be available in your classpath. The dependency will then be provided by
> mule in runtime.

For a list of notification types, see
[Notifications Configuration Reference](https://docs.mulesoft.com/mule-runtime/4.4/notifications-configuration-reference). For a list of
notification listener interfaces, see [Notification Interfaces](#notification-interfaces) below.

### Specifying a Different Interface

If you want to change the interface associated with a notification, you specify the new interface
with the `interface-class` attribute:

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

### Configuring a Custom Notification

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

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

### 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.

```xml
<notifications>
    <disable-notification interface="SECURITY"/>
</notifications>
```

### Using Subscriptions

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

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

<object name="endpointNotificationLogger" class="org.myfirm.EndpointNotificationLogger"/>
```

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

<notification-listener ref="endpointNotificationLogger" subscription="\*Service\*"/>

For more information, see
[Registering Listeners Programmatically](#registering-listeners-programmatically) below.

## Firing Custom Notifications

Objects can fire custom notifications 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:

```text
CustomNotification n = new CustomNotification("Hello");

notificationDispatcher.dispatch(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:

```text
DiscoveryNotification n = new DiscoveryNotification(client, DiscoveryNotification.CLIENT_ADDED);

notificationDispatcher.dispatch(n);
```

## Notification Interfaces

The following table describes the Mule server notifications and the interfaces in the
`org.mule.runtime.api.notification` package. An object can implement one of these interfaces to
become a listener for the associated notification. All listeners extend the `NotificationListener`
interface.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Notification</th><th>Description</th><th>Interface</th></tr></thead><tbody><tr><td><div><div><p>Connection Notification</p></div></div></td><td><div><div><p>Is fired when a connection is made or disconnected.</p></div></div></td><td><div><div><p><code>ConnectionNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Custom Notification</p></div></div></td><td><div><div><p>Can be fired by components and other objects such as routers, transformers, agents to communicate a change of state to each other.</p></div></div></td><td><div><div><p><code>CustomNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Exception Notification</p></div></div></td><td><div><div><p>An exception was thrown.</p></div></div></td><td><div><div><p><code>ExceptionNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Management Notification</p></div></div></td><td><div><div><p>The state of the Mule instance or its resources have changed, such as internal queues reach capacity.</p></div></div></td><td><div><div><p><code>ManagementNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Mule Context Notification</p></div></div></td><td><div><div><p>Can be fired when an event such as the mule context start occurs.</p></div></div></td><td><div><div><p><code>MuleContextNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Routing Notification</p></div></div></td><td><div><div><p>Async-Reply routers use this when an event is received for an event group that has already been processed.</p></div></div></td><td><div><div><p><code>RoutingNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Security Notification</p></div></div></td><td><div><div><p>Is fired when a request for authorization failed.</p></div></div></td><td><div><div><p><code>SecurityNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Transaction Notification</p></div></div></td><td><div><div><p>Is fired after a transaction has begun, was committed, or was rolled back.</p></div></div></td><td><div><div><p><code>TransactionNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Async-Message Notification</p></div></div></td><td><div><div><p>Can be fired when async work is scheduled and completed for a given flow.</p></div></div></td><td><div><div><p><code>AsyncMessageNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Pipeline-Message Notification</p></div></div></td><td><div><div><p>Is fired at key steps in the processing of pipeline.</p></div></div></td><td><div><div><p><code>PipelineMessageNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Message-Processor Notification</p></div></div></td><td><div><div><p>A message processor was invoked.</p></div></div></td><td><div><div><p><code>MessageProcessorNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Exception Strategy Notification</p></div></div></td><td><div><div><p>An exception strategy was invoked.</p></div></div></td><td><div><div><p><code>ExceptionStrategyNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Extension Notification</p></div></div></td><td><div><div><p>Can be fired by extensions, including custom data.</p></div></div></td><td><div><div><p><code>ExtensionNotificationListener</code></p></div></div></td></tr><tr><td><div><div><p>Connector-Message Notification</p></div></div></td><td><div><div><p>Is fired when a message is received or sent through a Connector.</p></div></div></td><td><div><div><p><code>ConnectorMessageNotificationListener</code></p></div></div></td></tr></tbody></table>

The listener interfaces all have a single method:

```java
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 `ManagementNotificationListener`, only notifications of type
`ManagementNotification` will be received. Objects can implement more than one listener to receive
more types of notifications.

## Registering Listeners Programmatically

You can register listeners as follows:

notificationListenerRegistry.registerListener(listener);

or:

notificationListenerRegistry.registerListener(listener, selector);

where `listener` is a `NotificationListener<N>` instance and `selector` is a `Predicate<N>` that
works as a filter to apply on a fired notification before calling the listener with it.

## Notification Action Codes

Each notification has an action code that determines the notification type. You can query the action
code to determine its type. For example:

**MyObject.java**

```java
public class MyObject implements ConnectionNotificationListener<ConnectionNotification> {

    (...)

    public void onNotification(ConnectionNotification notification) {

        if (valueOf(ConnectionNotification.CONNECTION_FAILED).equals(notification.getAction().getIdentifier())) {

            // write here the logic to handle the connection failed notification
        }
     }
}
```

## Notification Payloads

All notifications extend `java.util.EventObject`, and you can use the `getSource()` method to access
the payload of the object. The following table describes the payloads for each type of notification.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Notification</th><th>Payload Type</th><th>Resource ID</th><th>Description</th></tr></thead><tbody><tr><td><p>Connection Notification</p></td><td><p>String</p></td><td><p><code>&lt;connector-name&gt;.receiver(&lt;endpoint-uri&gt;)</code></p></td><td><p>The message receiver or message dispatcher that was connected.</p></td></tr><tr><td><p>Custom Notification</p></td><td><p>Any object</p></td><td><p>Any String</p></td><td><p>The object type is custom to the object firing the notification.</p></td></tr><tr><td><p>Exception Notification</p></td><td><p>ComponentLocation</p></td><td><p>Component name</p></td><td><p>The flow component that triggered this notification.</p></td></tr><tr><td><p>Management Notification</p></td><td><p>Object</p></td><td><p>The object ID</p></td><td><p>The monitored object that triggered this notification.</p></td></tr><tr><td><p>Mule Context Notification</p></td><td><p>MuleContext</p></td><td><p>Mule context ID</p></td><td><p>The Mule context instance. Equivalent to calling getMuleContext().</p></td></tr><tr><td><p>Routing Notification</p></td><td><p>Message</p></td><td><p>Message ID</p></td><td><p>The message sent or received.</p></td></tr><tr><td><p>Security Notification</p></td><td><p>SecurityException</p></td><td><p>The exception message</p></td><td><p>The security exception that occurred.</p></td></tr><tr><td><p>Transaction Notification</p></td><td><p>String</p></td><td><p>Transaction ID</p></td><td><p>The transaction that have triggered this notification.</p></td></tr><tr><td><p>Async-Message Notification</p></td><td><p>ComponentLocation</p></td><td><p>Component name</p></td><td><p>Component that has scheduled the async work.</p></td></tr><tr><td><p>Pipeline-Message Notification</p></td><td><p>String</p></td><td><p>Name</p></td><td><p>Pipeline name.</p></td></tr><tr><td><p>Message-Processor Notification</p></td><td><p>ComponentLocation</p></td><td><p>Component name</p></td><td><p>The flow component that triggered this notification.</p></td></tr><tr><td><p>Exception Strategy Notification</p></td><td><p>ComponentLocation</p></td><td><p>Component name</p></td><td><p>The flow component that triggered this notification.</p></td></tr><tr><td><p>Extension Notification</p></td><td><p>Object</p></td><td><p>Extension name</p></td><td><p>The payload can change from one extension to another.</p></td></tr><tr><td><p>Connector-Message Notification</p></td><td><p>ComponentLocation</p></td><td><p>Component name</p></td><td><p>The flow component that triggered this notification.</p></td></tr></tbody></table>