src/main/webapp/users-guide/nmr/nmr-event-listeners.conf

h2. Event listeners

The NMR has a rich event API that can be used to receive all sort of notifications about what's happening in the NMR.
Currently, two types of listeners are defined:
- {{org.apache.servicemix.nmr.api.event.EndpointListener}}
- {{org.apache.servicemix.nmr.api.event.ExchangeListener}}

h3. Endpoint Listener

h4. API
The {{EndpointListener}} defined two methods:
- {{endpointRegistered}} is called whenever a new endpoint is registered with the NMR
- {{endpointUnregistered}} is called whenever an existing endpoint is unregistered

{pygmentize:lang=java}
public interface EndpointListener {
    void endpointRegistered(InternalEndpoint endpoint);
    void endpointUnregistered(InternalEndpoint endpoint);
}
{pygmentize}

h4. Registering {{EndpointListener}}
An {{EndpointListener}} can be registered directly with the NMR:
{pygmentize:lang=java}
nmr.getListenerRegistry().register(listener, null);
{pygmentize}

The recommended way of registering an {{EndpointListener}} is by adding it to the OSGi Service Registry, e.g. using a Blueprint XML file:
{pygmentize:lang=xml}
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0">

    <bean id="myListener" class="..."/>

    <service ref="myListener">
      <interfaces>
        <value>org.apache.servicemix.nmr.api.event.EndpointListener</value>
        <value>org.apache.servicemix.nmr.api.event.Listener</value>
      </interfaces>
    </service>

</blueprint>
{pygmentize}

h4. Example
An example of using an endpoint listener is shipped as part of the ServiceMix distribution.  It can be found in the {{examples/interceptors/endpoint}} directory.

h3. ExchangeListener

h4. API
The {{ExchangeListener}} defined two methods:
- {{exchangeSent}} is called whenever an exchange is sent to the NMR for delivery
- {{exchangeDelivered}} is called whenever an exchange is being delivered to an endpoint
- {{exchangeFailed}} is called when a failure occurs while handling an exchange


{pygmentize:lang=java}
public interface ExchangeListener {
    void exchangeSent(Exchange exchange);
    void exchangeDelivered(Exchange exchange);
    void exchangeFailed(Exchange exchange);
}
{pygmentize}

h4. Registering {{ExchangeListener}}
An {{ExchangeListener}} can be registered directly with the NMR:
{pygmentize:lang=java}
nmr.getListenerRegistry().register(listener, null);
{pygmentize}

The recommended way of registering an {{ExchangeListener}} is by adding it to the OSGi Service Registry, e.g. using a Blueprint XML file:
{pygmentize:lang=xml}
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0">

    <bean id="myListener" class="..."/>

    <service ref="myListener">
      <interfaces>
        <value>org.apache.servicemix.nmr.api.event.ExchangeListener</value>
        <value>org.apache.servicemix.nmr.api.event.Listener</value>
      </interfaces>
    </service>

</blueprint>
{pygmentize}

h4. Example
An example of using an exchange listener is shipped as part of the ServiceMix distribution.  It can be found in the {{examples/interceptors/exchange}} directory.