com.neeve.sma

Interface MessageChannelKeyResolver

public interface MessageChannelKeyResolver

Resolves a message key from a channel key.

MessageChannels can be configured with a channel key that is used to resolve the message key on which a message is sent through the channel. In most cases a message key can be thought of as being synonymous with a topic or queue (depending on the message bus binding), SMA uses the term message key as more general abstraction to cover a broader arrange of messaging provider types. This abstraction is an important one in SMA, as it allows the channel's physical destination to be configured rather than hard coded into an application which in turn allows changing of the destination or messaging provider at runtime without application code changes.

A MessageChannel may be configured with a dynamic key, a key that has variable components that are resolved dynamically at run time based on the contents of:

• the message being sent (to facilitate content based routing).
• ... a key resolution table provided by the caller (to facilitate send context based routing)
• ... and/or configured for the message channel (to facilitate application environment based routing)

When there are no variable components in a channel key, then the channel key is referred to as a static key and the resolved message key and the channel key are one and the same. A special case of this is when the channel is not configured with a channel key at all, and its binding is configured to use the channel name as the channel and message key.

As an example, a channel key of 'ORDERS/${salesRegion:US}/${productId}/Purchases' is a dynamic key having variable key components of 'salesRegion' and '${productId}', with 'salesRegion' specifying a default value of 'US' in cases where it is unspecified. When a message is sent over a MessageChannel, all variable key components have to be resolved or an SmaException will be thrown.

A MessageChannelKeyResolver handles this dynamic key resolution by building the key on which the message is sent.

Most application working with SMA won't use the MessageChannelKeyResolver directly, but will instead call MessageChannel.sendMessage(MessageView, RawKeyResolutionTable, com.neeve.sma.MessageBusBinding.FlushContext, int) which will invoke the MessageChannel's MessageChannelKeyResolver automatically when the MessageView's key has not been set.

Applications that resolve the channel key prior to calling send on the channel may use a MessageChannelKeyResolver directly and set the resolved key on the MessageView or, preferably, call MessageView#resolveMessageKeyWith(MessageChannelKeyResolver, RawKeyResolutionTable) instead which can resolve a MessageKey directly into backing buffer for the message without making an intermediate copy.

Method Summary

Methods

Modifier and Type	Method and Description
Properties	getKeyResolutionTable() Gets the preconfigured properties based key resolution table associated with this resolver.
MessageChannel.RawKeyResolutionTable	getRawKeyResolutionTable() Gets the preconfigured 'raw' key resolution table associated with this resolver.
String	resolveMessageKey(MessageView view, Properties callerSuppliedKRT) Resolve a message's key using a channel key.
XString	resolveMessageKey(XString target, MessageView view, MessageChannel.RawKeyResolutionTable callerSuppliedKRT) Resolve a message's key using the channel key, into the provided XString.

Method Detail

getKeyResolutionTable

Properties getKeyResolutionTable()

Gets the preconfigured properties based key resolution table associated with this resolver.

When non null, it is illegal to call #resolveMessageKey(XString, MessageView, RawKeyResolutionTable).

Returns:

The resolver's raw key resolution table.

getRawKeyResolutionTable

MessageChannel.RawKeyResolutionTable getRawKeyResolutionTable()

Gets the preconfigured 'raw' key resolution table associated with this resolver.

When non null, it is illegal to call resolveMessageKey(MessageView, Properties).

Returns:

The resolver's raw key resolution table.

resolveMessageKey

String resolveMessageKey(MessageView view,
                       Properties callerSuppliedKRT)
                         throws SmaException

Resolve a message's key using a channel key.

This method is resolves a message's key by substituting variable key elements in the associated channel key. Unless otherwise specified by a particular channel key implementation, a channel key consists of static and variable portions with the variable portions consisting identified in the form of ${propName[:defaultValue]}. For example, a channel key of 'ORDERS/${salesRegion:US}/${productId}/Purchases' is interpreted as having variable key components of 'salesRegion' and '${productId}', with 'salesRegion' specifying a default value of 'US' in cases where it is unspecified. When a message is sent over a MessageChannel, all variable key components have to be resolved or an SmaException will be thrown. Variable key components are resolved from the following sources in this order:

• The message contents. The channel will look for a field accessor matching the variable key component (e.g. a getSalesRegion() method) if the message supports message reflection.
• The channel's key resolution table (if non null), which is a table that can be set on the channel programmatically for key resolution.
• The key resolution table supplied to this method (if non null)
• default values encoded into the channel key itself. In the above example this would be 'US' for 'salesRegion'

The method returns null if no channel key has been set for the channel and throws an exception if the message key could not be resolved because one or more variable channel key elements could not be resolved from the above listed sources.

Parameters:

view - The message view whose key is to be resolved.

callerSuppliedKRT - A table to be used during the key resolution process.

Throws:

SmaException - If there is an error in key resolution.

IllegalArgumentException - if the resolver is configured with a MessageChannel.RawKeyResolutionTable

Threading:

This method is safe for concurrent access by multiple threads providing that there are no other threads are accessing or the modifying the values in the keyResolutionTable or the message contents.

resolveMessageKey

XString resolveMessageKey(XString target,
                        MessageView view,
                        MessageChannel.RawKeyResolutionTable callerSuppliedKRT)
                          throws SmaException

Resolve a message's key using the channel key, into the provided XString. This method produces the same key as resolveMessageKey(MessageView, Properties), but does not produce garbage if the provided target XString is mutable.

This method is resolves a message's key by substituting variable key elements in the channel's key. Unless otherwise specified by the a particular channel key implementation, a channel key consists of static and variable portions with the variable portions consisting identified in the form of ${propName[::defaultValue]}. For example a channel key of 'ORDERS/${salesRegion::US}/${productId}/Purchases' is interpreted as having variable key components of 'salesRegion' and '${productId}', with 'salesRegion' specifying a default value of 'US' in cases where it is unspecified. When a message is sent over a MessageChannel, all variable key components have to be resolved or an SmaException will be thrown. Variable key components are resolved from the following sources in this order:

• The message contents. The channel will look for a field accessor matching the variable key component (e.g. a getSalesRegion() method) if the message supports message reflection.
• The channel's key resolution table (if non null), which is a table that can be set on the channel programmatically for key resolution.
• The key resolution table supplied to this method (if non null)
• default values encoded into the channel key itself. In the above example this would be 'US' for 'salesRegion'

Parameters:

target - The message view whose key is to be resolved.

view - The message view whose key is to be resolved.

callerSuppliedKRT - A table to be used during the key resolution process.

Returns:

The XString containing the resolved key. If not null the returned XString will be the same as that passed into the method unless the passed in XString is immutable in which case a new XString will be allocated.

Throws:

SmaException - If there is an error in key resolution.

IllegalArgumentException - if the resolver is configured with a Properties based KRT.

Threading:

This method is safe for concurrent access by multiple threads providing that there are no other threads are accessing the target XString or the modifying the values in the keyResolutionTable, or the message contents.