Overview

From the platform point of view an unhandled message is a message that is received but not processed by a message handler. This section discusses how such receipt is handled. 

Unhandled messages fall into 3 categories:

1. SMA Undeserializable Messages - Messages that are received from an underlying SMA MessageBusBinding that cannot be deserialized into a message. 
2. SMA Unsolicited Messages -These are messages that can be successfully deserialized into a message but are on a MessageChannel that is not joined or not known to the receiving application. 
3. AEP Unhandled Messages - These are messages valid messages intentionally attracted to the application on a joined MessageChannel, but for which the application has no declared EventHandler. 

The first two situation are trapped by SMA and are reported via an UnhandledMessageEvent, the latter situation is trapped by the AepEngine and reported to the application as an AepUnhandledMessageEvent. These events are discussed below. 

SMA Undeserializable & Unsolicited Messages

Undeserializable and unsolicited messages are trapped by SMA and are reported to the AepEngine via an UnhandledMessageEvent which the AepEngine will pass through to any application EventHandlers.

Causes

Below are some typical causes for UnhandledMessageEvents

• Receiving a message a channel that has not been joined: this usually indicates a configuration or design error in topics or subscriptions. The intent behind the SMA's message channel abstraction is define named logical conduits between peers. When a message is received on an unjoined channel it means that messages are being received by the application on a channel that the application designer wasn't expecting to receive traffic on.
• Receiving a message on an unknown channel: This typically usually indicates that there is a problem with topic subscriptions in which two channels are overlapping and causing an application to attract messages from a sender on another channel. 
• Receiving a message that has no channel or metadata: Messages sent to X applications are typically expected to have SMA MessageMetadata that can be used identify the message's transmission channel, type and factory. Receipt of a message without metadata for a bus that expects will thus result in an error. 
• Deserialization Errors: The SMA contract is to pass the message in deserialized MessageView (POJO) form to the AepEngine. If the message's view factory cannot be found or the data is corrupted, it will result in an error. 

UnhandledMessageEvent Fields

The following fields are available on a the UnhandledMessageEvent.

Acknowledgement

For unhandled Guaranteed messages determining whether or not to acnowledge unhandled message is an important consideration:

If the message is not acknowledged:

• The message will be redelivered if the application is restarted or fails over to a backup which can be undesirable.
• If there are a large number of unacknowledged message it puts a burden on the messaging provider which could hit resource limits. 
• If the SMA provider doesn't support individual message acknowledgements then failing to acknowledge the unhandled message can block subsequent acknowledgements.

But acknowledging the message:

• Is dangerous because the message will be discarded without being processed by the application. 

Prior to the 3.2 release, whether or not the triggering message was acknowledged was left to the SMA bus binding which in most cases would not acknowledge the message. 

As of the 3.2 release of the platform an application that declares an EventHandler for the UnhandledMessageEvent can control whether or not the triggering message is acknowledged. By default the platform leans towards ensuring that the message is not discarded and will not acknowledge the message unless instructed to do so by the application. An application can control acknowledgement as follows:

Default Acknowledgement Behavior. 

Auto acknowledgement for unhandled messages can be globally set to enabled by setting the configuration environment property:

nv.sma.unhandledmessageevent.autoAck=true

As of 3.2, setting the above property will cause UnhandledMessageEvents to be acknowledged regardless of whether or not there is a handler for the messages unless a handler specifically calls setAutoAck(false) on the event. Acknowledgement is done after the event is dispatched in the Aep Engine transaction thread. 

Auto Acknowledge

An application can explicitly override the default acknowledgement behavior of unhandled messages by declaring an EventHandler for UnhandledMessageEvent  and setting the event's autoAck behavior:

@EventHandler
public void onUnhandledMessage(UnhandledMessageEvent event) {
  byte [] toQuarantine = event.getBackingMessage().serializeToByteArray();
  // ... quarantine the above message in some fashion. 
  
  // Mark the event for auto acknowledgement, the 
  // engine will acknowledge it. 
  event.setAutoAck(true);
}

Explicit Acknowledgement

It is also possible to acknowledge the event asynchronously outside of the event handler. This advanced usage is useful for an application that might perform a blocking operation processing the UnhandledMessageEvent.

@EventHandler
public void onUnhandledMessage(UnhandledMessageEvent event) {
  // Disable auto acknowledgement:
  event.setAutoAck(false);
  
  // Acquire the event so the platform doesn't return it
  // to a pool: 
  event.acquire();

  // Asynchronously handle the event:
  Thread thread = new Thread(new Runnable() {
    public void run() {
      byte [] toQuarantine = event.getBackingMessage().serializeToByteArray();
      // ... quarantine the above message in some fashion that might block. 
      try {
        event.acknowledge();
      }
      catch (SmaException e) {
        e.printStackTrace();
      }
      finally {
        event.dispose();
      }
    }
  }
}

Aep Unhandled Message Events

An AepUnhandledMessageEvent is emitted when a message is successfully dispatched to an AepEngine from an SMA binding but no application EventHandler is found by the AepEngine.

Causes

• The application is incorrectly configured to join a Message Channel that it shouldn't have joined, 
• The application's channel filter is not narrow enough and some message types are coming though that shouldn't be. 
• A publisher is publishing messages to the channel that it shouldn't be. 

An AepUnhandledMessageEvent doesn't necessarily indicate a serious problem, but the presence of such events at the very least indicates inefficiencies in the type of messages that are being attraced by the applications subscriptions. 

Acknowledgement

AEP unhandled messages are acknowledged like a normally handled message except they result in an empty transaction with external effects. The message is acknowledged when the transaction is stabilized. For an application using EventSourcing that is using a disk based persister such messages will end up in the application's recovery transaction log, and consequently will not be lost in the event of acknowledgement. For a StateReplication application or an EventSourcing application without a Store persister, an application should ensure that the message is appropriately quarantined prior to returning from the AepUnhandledMessageEvent event handler and acknowledged.