com.neeve.sma.event
Class UnhandledMessageEvent

java.lang.Object
  com.neeve.util.UtlListElement
      com.neeve.event.Event
          com.neeve.event.alert.AlertEvent
              com.neeve.sma.event.UnhandledMessageEvent

All Implemented Interfaces:

IAlertEvent, IEvent, UtlPool.Item<Event>, UtlReferenceTracker.HasReferenceTracker

public final class UnhandledMessageEvent
extends AlertEvent

Event notifying that a received message was unhandled

Threading:

This class is safe for concurrent access by multiple threads.

Field Summary

static String	PROP_AUTOACK Property controlling whether unhandled messages are automatically acknowledged.
static boolean	PROP_AUTOACK_DEFAULT The default value for PROP_AUTOACK

Fields inherited from class com.neeve.util.UtlListElement

count, head, next, prev

Method Summary

void	acknowledge() If the message is Guaranteed, this method acknowledges the message.
static UnhandledMessageEvent	create(MessageBusBinding binding, MessageChannel channel, MessageMetadata messageMetadata, String messageKey, String smaTransportMessageId, Object unwrappedMessage, byte[] serializedMetadataBlob, byte[] serializedPayloadBlob, IEventAcknowledger acknowledger, Throwable reason) Create a new (initialized) unhandled message event.
static Event	create(Properties props) Create a new (uninitialized) unhandled message event.
boolean	getAutoAck() Get whether the message associated with this event should be auto acknowledged upon return from the event handler.
MessageBusBinding	getMessageBusBinding() Get the message bus binding that UnhandledMessageEvent originated from or null if not available.
MessageChannel	getMessageChannel() Get the message channel that UnhandledMessageEvent originated from or null if not available.
String	getMessageKey() Get the unhandled message's key
MessageMetadata	getMessageMetadata() Get the unhandled message's metadata
String	getMessageSMATransportMessageId() Get the unhandled message's SMA transport specific message id (if available).
Throwable	getReason() Get a Throwable object describing the reason why the message was unhandled
byte[]	getSerializedMetadataBlob() The serialized metadata blob representing the metadata as received in serialized form.
byte[]	getSerializedPayloadBlob() The serialized payload blob representing the received serialized message that was unhandled.
Object	getUnwrappedMessage() Get the unwrapped (un-deserialized) message
void	setAutoAck(boolean val) Set whether the message associated with this event should be auto acknowledged upon return from the event handler.
String	toString() Get a string representation of a message event

Methods inherited from class com.neeve.event.alert.AlertEvent

getBackingMessage, getEventTime, getTriggeringMessage, setBackingMessage

Methods inherited from class com.neeve.event.Event

acquire, dispose, getAcknowledger, getAttachment, getDelay, getDispatchTime, getInstanceNumber, getOfferTs, getPollTs, getPool, getRemainingTime, getScheduledTime, getSource, getType, init, isEndOfBatch, isHandled, owners, referenceTracker, setAcknowledger, setAttachment, setDelay, setDispatchTime, setEndOfBatch, setHandled, setPool, setScheduledTime, setSource

Methods inherited from class com.neeve.util.UtlListElement

count, insertAfter, insertBefore, isLinked, next, previous, unlink, wipe

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.neeve.event.IEvent

acquire, dispose, getAcknowledger, getAttachment, getDelay, getDispatchTime, getInstanceNumber, getRemainingTime, getScheduledTime, getSource, getType, isEndOfBatch, isHandled, owners, setAcknowledger, setAttachment, setDelay, setEndOfBatch, setHandled, setSource

Methods inherited from interface com.neeve.util.UtlReferenceTracker.HasReferenceTracker

referenceTracker

Field Detail

PROP_AUTOACK

public static final String PROP_AUTOACK

Property controlling whether unhandled messages are automatically acknowledged. Default value: false

See Also:

Constant Field Values

PROP_AUTOACK_DEFAULT

public static final boolean PROP_AUTOACK_DEFAULT

The default value for PROP_AUTOACK

See Also:

Constant Field Values

Method Detail

create

public static Event create(Properties props)

Create a new (uninitialized) unhandled message event.

This method instantiates a new unhandled message event object. The method is for use by the event factory to instantiate new reconnected events. The method should not be used directly by the user since the method bypasses any event pooling i.e. it creates a new reconnected event object even if there are eligible event objects available in the event type's pool.

create

public static UnhandledMessageEvent create(MessageBusBinding binding,
                                           MessageChannel channel,
                                           MessageMetadata messageMetadata,
                                           String messageKey,
                                           String smaTransportMessageId,
                                           Object unwrappedMessage,
                                           byte[] serializedMetadataBlob,
                                           byte[] serializedPayloadBlob,
                                           IEventAcknowledger acknowledger,
                                           Throwable reason)

Create a new (initialized) unhandled message event.

Parameters:

binding - The binding from where the event originated.

messageMetadata - The received message's metadata.

messageKey - The received message's key (may be null).

smaTransportMessageId - The received message's provider specific transport id.

unwrappedMessage - The unwrapped (un-deserialized) message.

serializedMetadataBlob - The received message metadata in byte array form.

serializedPayloadBlob - The received message payload in byte array form.

reason - The reason why the message was unhandled.

This method instantiates and initializes a unhandled message event. The method uses the packet factory to instantiate a new reconnected event (the factory recycles objects through the event type's object pool is configured for the type) and then initializes it with the supplied parameters.

acknowledge

public void acknowledge()
                 throws SmaException

If the message is Guaranteed, this method acknowledges the message.

If the message has already been acknowledged via this event, this call will have no effect.

Throws:

SmaException

Threading:

This method is safe for concurrent access by multiple threads.

setAutoAck

public final void setAutoAck(boolean val)

Set whether the message associated with this event should be auto acknowledged upon return from the event handler.

Setting the auto-ack behavior to true will cause the SMA runtime to automatically acknowledge a message upon successful return from the user event handler. This behavior is only applicable to guaranteed messages. The default value for this behavior is true i.e. if not explicitly set to false, guaranteed messages that are successfully processed (i.e. no exception thrown by the user eventhandler) are automatically acknowledged by the binding.

An application may set this to false to leave the message unacknowledged. One such usecase for doing so would be when the application will archive or quarantine the message asynchnously on another thread. The following important caveats must be observed in this case:

• If the message bus binding from which this message originated does not support individual acknowledgements, leaving an unhandled message unacknowledged could cause subsequent acks to back up behind the unacked message.
• If the handler intends to acknowledge the message at a later time, it must:
  • Call setAutoAck(boolean) with false.
  • Event.acquire() a reference to this UnhandledMessageEvent.
  • It can then later call acknowledge() (possibly in another thread).
  • followed by Event.dispose() when done with the event.

Threading:

This method is safe for concurrent access by multiple threads.

getAutoAck

public final boolean getAutoAck()

Get whether the message associated with this event should be auto acknowledged upon return from the event handler.

Threading:

This method is safe for concurrent access by multiple threads.

getMessageMetadata

public final MessageMetadata getMessageMetadata()

Get the unhandled message's metadata

getMessageKey

public final String getMessageKey()

Get the unhandled message's key

getMessageSMATransportMessageId

public final String getMessageSMATransportMessageId()

Get the unhandled message's SMA transport specific message id (if available).

The SMA transport specific message ID may be supplied by bindings for which there is a notion of a unique identifier for a message. A null value means that either the binding doesn't support the notion of such an id or that that the id wasn't available.

Returns:

The unhandled message's SMA transport specific message id (if available).

getSerializedPayloadBlob

public final byte[] getSerializedPayloadBlob()

The serialized payload blob representing the received serialized message that was unhandled.

The serialized payload is provided with the UnhandledMessageEvent to allow handlers to quarantine (save) the message for subsequent handling by administrators or tools which allow the unhandled message to acknowledged upstream. Note, however, that UnhandledMessageEvents are emitted in exceptional cases, and even if the serialized payload is provided there is not guaranteed that it was not corrupted during receipt.

This field is not guaranteed to be available. Reasons why it may not be available include:

• The payload content was missing from SMA transport level message (poison/corrupt message)
• The SMA binding doesn't serialize messages, and consequently can provide a serialized form.
• A bug in the binding around handling the message.

The encoding type of these bytes is determined by the corresponding metadata, so it is also generally necessary to ensure that that metadata is persisted along with the serialized payload to allow this serialized form to be deserialized.

Returns:

The serialized payload blob.

getSerializedMetadataBlob

public final byte[] getSerializedMetadataBlob()

The serialized metadata blob representing the metadata as received in serialized form.

The serialized metadata is provided with the UnhandledMessageEvent to allow handlers to quarantine (save) the message for subsequent diagnostic handling in cases where received metadata was corrupted on the wire or during receipt in the binding.

This field is not guaranteed to be available. Reasons why it may not be available include:

• The payload content was missing from SMA transport level message (poison/corrupt message)
• The SMA binding doesn't serialize messages, and consequently can provide a serialized form.
• A bug in the binding around handling the message.

The encoding type of these bytes is determined by the corresponding metadata, so it is also generally necessary to ensure that that metadata is persisted along with the serialized payload to allow this serialized form to be deserialized.

Returns:

The serialized payload blob.

getUnwrappedMessage

public final Object getUnwrappedMessage()

Get the unwrapped (un-deserialized) message

getMessageBusBinding

public final MessageBusBinding getMessageBusBinding()

Get the message bus binding that UnhandledMessageEvent originated from or null if not available.

getMessageChannel

public final MessageChannel getMessageChannel()

Get the message channel that UnhandledMessageEvent originated from or null if not available.

getReason

public final Throwable getReason()

Get a Throwable object describing the reason why the message was unhandled

toString

public final String toString()

Get a string representation of a message event

Overrides:

toString in class AlertEvent