com.neeve.sma
Interface MessageChannel

All Superinterfaces:

IEventSource

All Known Implementing Classes:

LoopbackMessageChannel, com.neeve.sma.impl.MessageChannelBase

public interface MessageChannel
extends 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	KEY_ALREADY_VALIDATED Indicates that a message's key has already been validated.
static int	PRESERVE_CHANNEL_JOINS A flag used with close(int) to indicate that channels that leave(int) should not be called for channels that were joined.
static String	PROP_ALLOW_EMPTY_KEY_FIELD The XRuntime property controlling whether or not variable key parts in channel keys may be substituted with an empty String value.
static boolean	PROP_ALLOW_EMPTY_KEY_FIELD_DEFAULT The default value for PROP_ALLOW_EMPTY_KEY_FIELD.
static String	PROP_ALLOW_EMPTY_KEY_FIELD_DEPRECATED
static String	PROP_CLEAN_CHANNEL_FILTER The XRuntime property controlling whether or not channel filters are sanitized in the same way we sanitize message keys (see "nv.sma.cleanmessagekey").
static String	PROP_CLEAN_MESSAGE_KEY The XRuntime property controlling whether or not variable key parts in channel keys are sanitized by replacing any non letter or digit character with an '_' when resolving a variable key.
static boolean	PROP_CLEAN_MESSAGE_KEY_DEFAULT The default value for PROP_CLEAN_MESSAGE_KEY.
static String	PROP_CLEAN_MESSAGE_KEY_DEPRECATED
static String	PROP_MAX_RESOLVED_KEY_LENGTH The XRuntime environment property controlling the maximum resolved key length for resolved and static message keys.
static int	PROP_MAX_RESOLVED_KEY_LENGTH_DEFAULT The default value for "nv.sma.maxresolvedkeylength" (0)
static String	PROP_MAX_RESOLVED_KEY_LENGTH_DEPRECATED
static String	PROP_VALIDATE_MESSAGE_KEY The XRuntime property controlling whether or not message key validation is done prior to sending a message.
static boolean	PROP_VALIDATE_MESSAGE_KEY_DEFAULT
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.
void	close(int flags) 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.
XString	getNameAsRaw() Get the name of a message channel as a XString.
MessageChannel.Qos	getQos() Get a channel's Qos.
MessageChannel.RawKeyResolutionTable	getRawKeyResolutionTable() Get a channel's XString based 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.
XString	resolveMessageKeyToRaw(XString target, MessageView view, MessageChannel.RawKeyResolutionTable keyResolutionTable) Resolve a message's key using the channel key, into the provided XString.
boolean	sendMessage(MessageView view, MessageBusBinding.FlushContext flushContext, int flags) Send a message.
boolean	sendMessage(MessageView view, MessageChannel.RawKeyResolutionTable keyResolutionTable, 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.
boolean	sendMessage(MessageView view, Properties keyResolutionTable, MessageBusBinding.FlushContext flushContext, int flags) Send a message.
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.
void	validateResolvedMessageKey(MessageView view) Validates that a MessageView's message key is valid.

Field Detail

PROP_MAX_RESOLVED_KEY_LENGTH

static final String PROP_MAX_RESOLVED_KEY_LENGTH

The XRuntime environment property controlling the maximum resolved key length for resolved and static message keys.

When set to a length greater than 0 the length of the message key is checked to ensure that the length is not greater this value.

For maximum portability between bindings this property can be set to the lowest value for destination lengths supported amongst the bindings that will be used.

If this property is not set and PROP_VALIDATE_MESSAGE_KEY is set a binding should still validate that a resolved message key is not too long.

Property Name: "nv.sma.maxresolvedkeylength"
Default Value: 0

See Also:

Constant Field Values

PROP_MAX_RESOLVED_KEY_LENGTH_DEPRECATED

static final String PROP_MAX_RESOLVED_KEY_LENGTH_DEPRECATED

See Also:

Constant Field Values

PROP_MAX_RESOLVED_KEY_LENGTH_DEFAULT

static final int PROP_MAX_RESOLVED_KEY_LENGTH_DEFAULT

The default value for "nv.sma.maxresolvedkeylength" (0)

See Also:

Constant Field Values

PROP_CLEAN_MESSAGE_KEY

static final String PROP_CLEAN_MESSAGE_KEY

The XRuntime property controlling whether or not variable key parts in channel keys are sanitized by replacing any non letter or digit character with an '_' when resolving a variable key.

For example: if the channel key is specified as "/Orders/${Region}" and key resolution is performed using a message that returns a value of "Asia/Pac" for getRegion(), then the resolved key value will be "/Orders/Asia_Pac" rather than "/Orders/Asia/Pac" when this property is set to true.

Note that this property applies to values coming from a key resolution table or via message reflection.

Property Name: "nv.sma.cleanmessagekey"
Default Value: false

See Also:

Constant Field Values

PROP_CLEAN_MESSAGE_KEY_DEPRECATED

static final String PROP_CLEAN_MESSAGE_KEY_DEPRECATED

See Also:

Constant Field Values

PROP_CLEAN_MESSAGE_KEY_DEFAULT

static final boolean PROP_CLEAN_MESSAGE_KEY_DEFAULT

The default value for PROP_CLEAN_MESSAGE_KEY.

See Also:

Constant Field Values

PROP_CLEAN_CHANNEL_FILTER

static final String PROP_CLEAN_CHANNEL_FILTER

The XRuntime property controlling whether or not channel filters are sanitized in the same way we sanitize message keys (see "nv.sma.cleanmessagekey").

Property Name: "nv.sma.cleanchannelfilter"
Default Value: the configured value of nv.sma.cleanmessagekey

See Also:

Constant Field Values

PROP_ALLOW_EMPTY_KEY_FIELD

static final String PROP_ALLOW_EMPTY_KEY_FIELD

The XRuntime property controlling whether or not variable key parts in channel keys may be substituted with an empty String value.

For example: if the channel key is specified as "/Orders/${Region}/${Department}" and key resolution is performed using a message that returns a value of "" for getRegion(), then this property specifies that key resolution should fail when set to false.

Note that this property applies to values coming from a key resolution table or via message reflection.

Property Name: "nv.sma.allowemptykeyfield"
Default Value: false

See Also:

Constant Field Values

PROP_ALLOW_EMPTY_KEY_FIELD_DEPRECATED

static final String PROP_ALLOW_EMPTY_KEY_FIELD_DEPRECATED

See Also:

Constant Field Values

PROP_ALLOW_EMPTY_KEY_FIELD_DEFAULT

static final boolean PROP_ALLOW_EMPTY_KEY_FIELD_DEFAULT

The default value for PROP_ALLOW_EMPTY_KEY_FIELD.

See Also:

Constant Field Values

PROP_VALIDATE_MESSAGE_KEY

static final String PROP_VALIDATE_MESSAGE_KEY

The XRuntime property controlling whether or not message key validation is done prior to sending a message.

When this property is false calls to validateResolvedMessageKey(MessageView) will be a no-op.

Property Name: "nv.sma.validatemessagekey"
Default Value: false

See Also:

Constant Field Values

PROP_VALIDATE_MESSAGE_KEY_DEFAULT

static final boolean PROP_VALIDATE_MESSAGE_KEY_DEFAULT

See Also:

Constant Field Values

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

KEY_ALREADY_VALIDATED

static final int KEY_ALREADY_VALIDATED

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

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 not do do message key validation (if message key validation is enabled).

This flag is useful in cases where the message key has already been validated by the validateResolvedMessageKey(MessageView) method prior to calling sendMessage(com.neeve.sma.MessageView, java.util.Properties, com.neeve.sma.MessageBusBinding.FlushContext, int).

See Also:

Constant Field Values

PRESERVE_CHANNEL_JOINS

static final int PRESERVE_CHANNEL_JOINS

A flag used with close(int) to indicate that channels that leave(int) should not be called for channels that were joined.

The normal behavior for channel close is to leave the channel if it were joined. Specifying this flag preseves any subscriptions or interests registered for the channel.

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.

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

Specified by:

getName in interface IEventSource

Threading:

This method is safe for concurrent access by multiple threads.

getNameAsRaw

XString getNameAsRaw()

Get the name of a message channel as a XString.

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

Threading:

This method is safe for concurrent access by multiple threads.

getId

short getId()

Get the id of a message channel.

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.

Threading:

This method is safe for concurrent access by multiple threads.

getType

String getType()

Get a message channel's type.

This method returns a string describing the channel type.

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

Threading:

This method is safe for concurrent access by multiple threads.

getDescriptor

MessageChannelDescriptor getDescriptor()

Get a channel's descriptor.

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

Threading:

This method is safe for concurrent access by multiple threads.

getMessageBusBinding

MessageBusBinding getMessageBusBinding()

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

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

Threading:

This method is safe for concurrent access by multiple threads.

getState

MessageChannel.State getState()

Get a channel's state.

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

Threading:

This method is safe for concurrent access by multiple threads.

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.

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

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.

getKeyResolutionTable

Properties getKeyResolutionTable()

Get a channel's key resolution table.

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

Threading:

This method is safe for concurrent access by multiple threads.

setRawKeyResolutionTable

void setRawKeyResolutionTable(MessageChannel.RawKeyResolutionTable table)
                              throws IllegalStateException

Set a channel's key resolution table.

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

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.

getRawKeyResolutionTable

MessageChannel.RawKeyResolutionTable getRawKeyResolutionTable()

Get a channel's XString based key resolution table.

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

Threading:

This method is safe for concurrent access by multiple threads.

resolveMessageKey

String resolveMessageKey(MessageView view,
                         Properties keyResolutionTable)
                         throws SmaException

Resolve a message's key using the channel key.

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'

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.

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

Throws:

SmaException

Threading:

This method is safe for concurrent access by multiple threads

resolveMessageKeyToRaw

XString resolveMessageKeyToRaw(XString target,
                               MessageView view,
                               MessageChannel.RawKeyResolutionTable keyResolutionTable)
                               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.

keyResolutionTable - 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

Threading:

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

validateResolvedMessageKey

void validateResolvedMessageKey(MessageView view)
                                throws SmaException

Validates that a MessageView's message key is valid.

When called and PROP_VALIDATE_MESSAGE_KEY is not false this method checks whether the message key is well formed. Checks for a well formed message key may include:

• The length of the message key does not exceed the configured value for PROP_MAX_RESOLVED_KEY_LENGTH (or that supported by a binding implementation.
• That the resolved message key does not contain empty levels.
• ... And any other validation specific to the bus binding.

The validate method is called by the sendMessage(com.neeve.sma.MessageView, java.util.Properties, com.neeve.sma.MessageBusBinding.FlushContext, int) method unless the the the 32 flag is set to indicate that the caller has already validated the key.

Parameters:

view - the view for which

Throws:

SmaException - If the key is invalid.

sendMessage

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

Send a message.

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.

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
• - KEY_ALREADY_VALIDATED

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,
                    MessageChannel.RawKeyResolutionTable keyResolutionTable,
                    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.

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 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.

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

Threading:

This method is safe for concurrent access by multiple threads.

join

void join(int flags)
          throws SmaException

Join a message channel's inbound stream.

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.

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.

leave

void leave(int flags)
           throws SmaException

Leave a message channel's inbound stream.

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 or Closing channels. An exception will be thrown if invoked on channels in any other state.

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.

close

void close()
           throws SmaException

Close a message channel.

This call is equivalent to calling close(int)

Throws:

SmaException

close

void close(int flags)
           throws SmaException

Close a message channel.

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, Closing, Closed, or Failed channels. An exception will be thrown if invoked on channels in any other state.

Parameters:

flags - Flags that qualify the close operation. Currently allowed flags for this method are:

• PRESERVE_CHANNEL_JOINS

Throws:

SmaException - Thrown in case an error is encountered during this method, in which case the caller should inspect the channel state to determine the effective outcome of the call.

Threading:

This method is not safe for concurrent access by multiple threads or any method on the MessageBusBinding associated to the channel.