com.neeve.sma
Interface MessageChannel

All Superinterfaces:

com.neeve.event.IEventSource

All Known Implementing Classes:

LoopbackMessageChannel, com.neeve.sma.impl.MessageChannelBase

public interface MessageChannel
extends com.neeve.event.IEventSource

Represents a SMA channel for message exchange.

An SMA message channel is a named conduit for message exchange between SMA messaging participants. User's open and close channels using their message bus bindings. Channel export primitives using which users can send messages to and receive messages from other messaging participants.

Each message channel maintains an outbound message queue. This queue is used to send messages through the channel. When a user wishes to send one or more messages through a channel, the user enqueues the message(s) in the outbound queue of the channel and then flushes the queue. A successful return from the flush operation guarantees that the SMA runtime has stabilized the message for delivery as per the channel's configured QOS.

Threading:

The channel class is not safe for concurrent access by multiple threads

Nested Class Summary

static class	MessageChannel.Qos Enumerates the different supported Qualities of Service
static interface	MessageChannel.RawKeyResolutionTable A MessageChannel.RawKeyResolutionTable is used to build a message key from a given channel key, by providing substitution values for variable components in the key.
static class	MessageChannel.State Enumerates the different channel states.

Field Summary

static int	ALREADY_SYNCD Indicates that a message view has already been sync'd and need not be done so again.
static int	FLUSH_FORCE Forces a flush of outbound messages buffered by a channel's binding.
static int	KEY_ALREADY_RESOLVED Indicates that a message's key has already been resolved.
static int	SENDER_ALREADY_RESOLVED Indicates that a message's sender has already been resolved.
static int	SNO_ALREADY_RESOLVED Indicates that a message's sequence number has already been resolved.

Method Summary

void	close() Close a message channel.
Object	getAttachment() This method is reserved for internal use.
MessageChannelDescriptor	getDescriptor() Get a channel's descriptor.
short	getId() Get the id of a message channel.
Properties	getKeyResolutionTable() Get a channel's key resolution table.
MessageBusBinding	getMessageBusBinding() Get the message bus binding to which a message channel belongs.
String	getName() Get the name of a message channel.
com.neeve.raw.RawString	getNameAsRaw() Get the name of a message channel as a RawString.
MessageChannel.Qos	getQos() Get a channel's Qos.
MessageChannel.RawKeyResolutionTable	getRawKeyResolutionTable() Get a channel's key resolution table.
MessageChannel.State	getState() Get a channel's state.
String	getType() Get a message channel's type.
boolean	isJoined() Get whether the channel is joined.
void	join(int flags) Join a message channel's inbound stream.
void	leave(int flags) Leave a message channel's inbound stream.
String	resolveMessageKey(MessageView view, Properties keyResolutionTable) Resolve a message's key using the channel key.
com.neeve.raw.RawString	resolveMessageKeyToRaw(com.neeve.raw.RawString target, MessageView view, MessageChannel.RawKeyResolutionTable keyResolutionTable) Resolve a message's key using the channel key, into the provided RawString.
boolean	sendMessage(MessageView view, MessageBusBinding.FlushContext flushContext, int flags) Send a message.
boolean	sendMessage(MessageView view, Properties keyResolutionTable, MessageBusBinding.FlushContext flushContext, int flags) Send a message.
boolean	sendMessageWithRawKRT(MessageView view, MessageChannel.RawKeyResolutionTable rawKeyResolutionTable, MessageBusBinding.FlushContext flushContext, int flags) This method is identical to sendMessage(MessageView, Properties, com.neeve.sma.MessageBusBinding.FlushContext, int), except that it accepts a MessageChannel.RawKeyResolutionTable allow the message key to be resolved without producing garbage.
void	setAttachment(Object object) This method is reserved for internal use.
void	setKeyResolutionTable(Properties table) Set a channel's key resolution table.
void	setRawKeyResolutionTable(MessageChannel.RawKeyResolutionTable table) Set a channel's key resolution table.

Field Detail

FLUSH_FORCE

static final int FLUSH_FORCE

Forces a flush of outbound messages buffered by a channel's binding.

This flag is intended for use with the sendMessage(com.neeve.sma.MessageView, java.util.Properties, com.neeve.sma.MessageBusBinding.FlushContext, int) method. It causes the method to forcibly invoke {#link MessageBusBinding#flush}

See Also:

Constant Field Values

ALREADY_SYNCD

static final int ALREADY_SYNCD

Indicates that a message view has already been sync'd and need not be done so again.

This flag is intended for use with the sendMessage(com.neeve.sma.MessageView, java.util.Properties, com.neeve.sma.MessageBusBinding.FlushContext, int) method. It causes the method to not invoke {#link MessageView#sync}

See Also:

Constant Field Values

SENDER_ALREADY_RESOLVED

static final int SENDER_ALREADY_RESOLVED

Indicates that a message's sender has already been resolved.

This flag is intended for use with the sendMessage(com.neeve.sma.MessageView, java.util.Properties, com.neeve.sma.MessageBusBinding.FlushContext, int) method. It causes the method to not go through resolving the message sender.

See Also:

Constant Field Values

SNO_ALREADY_RESOLVED

static final int SNO_ALREADY_RESOLVED

Indicates that a message's sequence number has already been resolved.

This flag is intended for use with the sendMessage(com.neeve.sma.MessageView, java.util.Properties, com.neeve.sma.MessageBusBinding.FlushContext, int) method. It causes the method to not go through resolving the message sequence number.

See Also:

Constant Field Values

KEY_ALREADY_RESOLVED

static final int KEY_ALREADY_RESOLVED

Indicates that a message's key has already been resolved.

This flag is intended for use with the sendMessage(com.neeve.sma.MessageView, java.util.Properties, com.neeve.sma.MessageBusBinding.FlushContext, int) method. It causes the method to not go through the key resolution machinery.

See Also:

Constant Field Values

Method Detail

setAttachment

void setAttachment(Object object)

This method is reserved for internal use.

getAttachment

Object getAttachment()

This method is reserved for internal use.

getName

String getName()

Get the name of a message channel.

Specified by:

getName in interface com.neeve.event.IEventSource

Threading:

This method is safe for concurrent access by multiple threads.

This method can be invoked on a channel in any state.

getNameAsRaw

com.neeve.raw.RawString getNameAsRaw()

Get the name of a message channel as a RawString.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be invoked on a channel in any state.

getId

short getId()

Get the id of a message channel.

Threading:

This method is safe for concurrent access by multiple threads.

A message channel's id uniquely identifies a message channel within its message bus. A channel may or may not be assigned an ID. If assigned the SMA runtime will use the id to identify the channel in its bus. Otherwise it will be identified by name. The id value of a channel not assigned an id is -1.

This method can be invoked on a channel in any state.

getType

String getType()

Get a message channel's type.

Threading:

This method is safe for concurrent access by multiple threads.

This method returns a string describing the channel type.

This method can be invoked on a channel in any state.

getDescriptor

MessageChannelDescriptor getDescriptor()

Get a channel's descriptor.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be invoked on a channel in any state.

getMessageBusBinding

MessageBusBinding getMessageBusBinding()

Get the message bus binding to which a message channel belongs.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be invoked on a channel in any state.

getState

MessageChannel.State getState()

Get a channel's state.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be invoked on a channel in any state.

getQos

MessageChannel.Qos getQos()

Get a channel's Qos.

Threading:

This method is safe for concurrent access by multiple threads.

setKeyResolutionTable

void setKeyResolutionTable(Properties table)
                           throws IllegalStateException

Set a channel's key resolution table.

Parameters:

table - The resolution table. Can be null which effectively removes the channel's key resolution table.

Throws:

IllegalStateException - If a MessageChannel.RawKeyResolutionTable is already installed

Threading:

This method is safe for concurrent access by multiple threads.

This method installs the channels key resolution table. This table is consulted during send while resolving a message key if a variable channel key element could not be resolved from the message being sent (either because a field with the same name as the key was not present in the message, was present but was not reflectable or had a value of null) or from the key resolution table provided to the send method.

This method can be called on a channel in any state.

A MessageChannel cannot have both a MessageChannel.RawKeyResolutionTable and a Properties table. Calling setKeyResolutionTable(Properties) and setRawKeyResolutionTable(RawKeyResolutionTable) with non null values will result in an IllegalStateException

getKeyResolutionTable

Properties getKeyResolutionTable()

Get a channel's key resolution table.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be called on a channel in any state.

setRawKeyResolutionTable

void setRawKeyResolutionTable(MessageChannel.RawKeyResolutionTable table)
                              throws IllegalStateException

Set a channel's key resolution table.

Parameters:

table - The resolution table. Can be null which effectively removes the channel's key resolution table.

Throws:

IllegalStateException - If a MessageChannel.RawKeyResolutionTable is already installed

Threading:

This method is safe for concurrent access by multiple threads.

This method installs the channels key resolution table. This table is consulted during send while resolving a message key if a variable channel key element could not be resolved from the message being sent (either because a field with the same name as the key was not present in the message, was present but was not reflectable or had a value of null) or from the key resolution table provided to the send method.

This method can be called on a channel in any state.

A MessageChannel cannot have both a MessageChannel.RawKeyResolutionTable and a Properties table. Calling setKeyResolutionTable(Properties) and setRawKeyResolutionTable(RawKeyResolutionTable) with non null values will result in an IllegalStateException

getRawKeyResolutionTable

MessageChannel.RawKeyResolutionTable getRawKeyResolutionTable()

Get a channel's key resolution table.

Threading:

This method is safe for concurrent access by multiple threads.

This method can be called on a channel in any state.

resolveMessageKey

String resolveMessageKey(MessageView view,
                         Properties keyResolutionTable)
                         throws SmaException

Resolve a message's key using the channel key.

Parameters:

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

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

Throws:

SmaException

Threading:

This method is safe for concurrent access by multiple threads

This method is resolves a message's key by substituting variable key elements in the channel's key from the following sources in the specified order:
- The message contents
- The channel's key resolution table
- The key resolution table supplied to this method
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.

resolveMessageKeyToRaw

com.neeve.raw.RawString resolveMessageKeyToRaw(com.neeve.raw.RawString target,
                                               MessageView view,
                                               MessageChannel.RawKeyResolutionTable keyResolutionTable)
                                               throws SmaException

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

Parameters:

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

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

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

Returns:

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

Throws:

SmaException

Threading:

This method is safe for concurrent access by multiple threads providing that the the no other threads are accessing the target RawString or the modifying the values in the keyResolutionTable

This method is resolves a message's key by substituting variable key elements in the channel's key from the following sources in the specified order:
- The message contents
- The channel's key resolution table
- The key resolution table supplied to this method
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.

sendMessage

boolean sendMessage(MessageView view,
                    Properties keyResolutionTable,
                    MessageBusBinding.FlushContext flushContext,
                    int flags)
                    throws SmaException

Send a message.

Parameters:

view - A message view object containing the message to be sent.

keyResolutionTable - A table to use in resolving the message's key (from the channel key). This table only comes into play for channels that have a key associated with them. For such channels, this table is consulted by this method if a variable channel key element could not be resolved from the message being sent.

flushContext - A context object indicating the IO semantics to be used in case the channel's binding is automatically flushed from within this method alongwith runtime context information related to the flush. A value of null is interpreted as request for synchronous flush (in case triggered by the method).

flags - Flags that qualify the send operation. The following flags are permitted for use in this method:
- FLUSH_FORCE
- ALREADY_SYNCD
- SENDER_ALREADY_RESOLVED
- SNO_ALREADY_RESOLVED
- KEY_ALREADY_RESOLVED

Returns:

Returns true in case the method did attempt to automatically flush the channel's binding. Returns false in case the message was only enqueued and no flush was attempted.

Throws:

SmaException - Thrown in case an error is encountered while enqueuing the message.

Threading:

This method is not safe for concurrent access by multiple threads.

This method sends a message through a message channel. The completion of a send call does not guarantee that the message has been transmitted to the recipients. It is permissible for the channel's binding to buffer sent messages to optimize transmission throughput. To ensure the sent messages and all prior buffered messages are transmitted before the send call returns, specify the FLUSH_FORCE flag. The user can also invoke MessageBusBinding.flush(com.neeve.sma.MessageBusBinding.FlushContext) to flush all messages buffered by a binding.

This method may choose to implicitly transmit some or all of messages buffered by the channel's even if the FLUSH_FORCE flag is not specified. The caller can test the return value from this method to test whether the method attempted to flush buffered messages or not. However, unless the FLUSH_FORCE flag is specified, a return value of true does not guarantee that all buffered messages have been transmitted. The caller should either use the force flush flag or explicitly call MessageBusBinding.flush(com.neeve.sma.MessageBusBinding.FlushContext) to flush all buffered messages.

This method checks for the following fields set in a message during its processing:

key: The message key set using MessageView.setMessageKey(java.lang.String). A non-null value in this parameter will override dynamic introspection of the message and supplied key resolution tables for resolution of the message key.

flow: The message flow set using MessageView.setMessageFlow(int). Flows define order of processing. They are orthogonal to channels which define expression of interest. A single flow can be comprised of messages across channels. Since flows define order of processing, messages in the same flow must be sent and received by the same thread. On the sending side, it is the responsibility of the user to ensure that messages in the same flow are sent by the same thread. The SMA runtime will ensure that messages on the same flow are sent on the wire in correct sequence. On the receiving side, the SMA runtime determines whether and how to spin up multiple threads to process inbound traffic subject constrained by the requirement that messages in a single flow must be dispatched by the same thread.
sno: The message sequence number set using MessageView.setMessageSequenceNumber(long). A value of < 0 will cause the SMA runtime to use its internal sequence number space.

This method can only be invoked on open channels. An exception will be thrown if invoked on channels in any other state.

sendMessageWithRawKRT

boolean sendMessageWithRawKRT(MessageView view,
                              MessageChannel.RawKeyResolutionTable rawKeyResolutionTable,
                              MessageBusBinding.FlushContext flushContext,
                              int flags)
                              throws SmaException

This method is identical to sendMessage(MessageView, Properties, com.neeve.sma.MessageBusBinding.FlushContext, int), except that it accepts a MessageChannel.RawKeyResolutionTable allow the message key to be resolved without producing garbage.

Parameters:

view - A message view object containing the message to be sent.

rawKeyResolutionTable - A table to use in resolving the message's key (from the channel key). This table only comes into play for channels that have a key associated with them. For such channels, this table is consulted by this method if a variable channel key element could not be resolved from the message being sent.

flushContext - A context object indicating the IO semantics to be used in case the channel's binding is automatically flushed from within this method along with runtime context information related to the flush. A value of null is interpreted as request for synchronous flush (in case triggered by the method).

flags - Flags that qualify the send operation. The following flags are permitted for use in this method:
- FLUSH_FORCE
- ALREADY_SYNCD
- SENDER_ALREADY_RESOLVED
- SNO_ALREADY_RESOLVED
- KEY_ALREADY_RESOLVED

Returns:

Returns true in case the method did attempt to automatically flush the channel's binding. Returns false in case the message was only enqueued and no flush was attempted.

Throws:

SmaException - Thrown in case an error is encountered while enqueuing the message.

Threading:

This method is not safe for concurrent access by multiple threads.

sendMessage

boolean sendMessage(MessageView view,
                    MessageBusBinding.FlushContext flushContext,
                    int flags)
                    throws SmaException

Send a message.

Invoking this method is equivalent to invoking sendMessage(view, null, flushContext, flags)

Throws:

SmaException

isJoined

boolean isJoined()

Get whether the channel is joined.

Threading:

This method is safe for concurrent access by multiple threads.

This method can only be invoked on channels in any state.

join

void join(int flags)
          throws SmaException

Join a message channel's inbound stream.

Parameters:

flags - Flags that qualify the join operation. Currently, there are no flags defined. The user should specify 0 in this parameter.

Throws:

SmaException - Thrown in case an error is encountered while joining the channel's inbound stream.

Threading:

This method is not safe for concurrent access by multiple threads.

This method is used to join a message channel's inbound message stream. Upon successful return from this method, messages inbound from the channel will be dispatched to the event multiplexer associated with the channel's bus binding.

This method can be invoked multiple times. The method will do nothing and return without error in case invoked on an already joined channel.

This method can only be invoked on open channels. An exception will be thrown if invoked on channels in any other state.

leave

void leave(int flags)
           throws SmaException

Leave a message channel's inbound stream.

Parameters:

flags - Flags that qualify the leave operation. There are no flags currently defined for this method.

Throws:

SmaException - Thrown in case a runtime error is encountered while leaving the channel's inbound stream. The user should treat the channel's inbound stream as still joined in case an exception is thrown.

Threading:

This method is not safe for concurrent access by multiple threads.

This method is used to leave a message channel's inbound message stream. The method will do nothing in case invoked on a channel that has not been joined (or joined and subsequently left).

This method can only be invoked on open channels. An exception will be thrown if invoked on channels in any other state.

close

void close()
           throws SmaException

Close a message channel.

Throws:

SmaException - Thrown in case an error is encountered during this method. The caller should treat the channel as still open in case an exception is thrown.

Threading:

This method is not safe for concurrent access by multiple threads.

This method is called by a user when it is done using a message channel. This method will implicitly call leave(int) in case the channel is joined at the time this method is invoked (a failed channel is not considered to be joined). The user should release the channel for garbage collection after this method returns.

This method can only be invoked on open or failed channels. An exception will be thrown if invoked on channels in any other state.