com.neeve.sma

Interface MessageBusBinding

All Superinterfaces:

IEventSource

All Known Implementing Classes:

LoopbackMessageBusBinding, com.neeve.sma.impl.MessageBusBindingBase

public interface MessageBusBinding
extends IEventSource

Represents a binding to an SMA message bus.

A message bus binding serves as an interface to a message bus. It provides the facilities by which messages can be exchanged with other messaging participants.

A message bus contains message channels. Message channels are the entities through which users send and receive messages. Before a user can send and receive messages through a channel, the user needs to get a handle to the channel. This is done via the getMessageChannel(java.lang.String) method. The user can send messages through a channel immediately after getting the handle to the channel. In order to receive messages from a channel, the user needs to explicitly join the channel via MessageChannel.join(int). Once joined, messages sent to the channel by other messaging participants will flow to the joining perticipant's binding. Received messages are dispatched to the user as message events.

A user creates message bus bindings using MessageBusBindingFactory.

Threading:

A message bus binding is not safe for concurrent access by multiple thread.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	MessageBusBinding.PostMessagePrepProcessor Interface used by caller to perform post message preparation processing
static interface	MessageBusBinding.SequenceNumberGenerator Interface used by caller to generate sequence numbers
static class	MessageBusBinding.State Enumerates the different binding states
static interface	MessageBusBinding.StatsListener Listener used to allow binding statistics to be collected.

Field Summary

Fields

Modifier and Type	Field and Description
static int	PRESERVE_CHANNEL_JOINS Flag that can be used on close(flags) to indicate that the binding that should not leave channels that were joined, but instead preserve any interests or subscriptions that have been established.
static XString	TRANSPORT_HEADER_RECEIVED_CHANNEL Defines the transport header name for the received channel name.

Method Summary

Modifier and Type	Method and Description
boolean	acksRequireFlush() Get whether a binding requires a flush for acks to be sent.
boolean	canFail() Get whether a binding can fail.
void	close() Close a message bus binding.
void	close(int closeFlags) Close a message bus binding.
void	fail(Exception e, boolean dispatchFailureEvent) Fail a message bus binding.
void	flush() Flush all outbound messages buffered by a binding.
Object	getAttachment() This method is reserved for internal use.
MessageBusDescriptor	getDescriptor() Get the bus descriptor used to created a binding.
IEventHandler	getEventHandler() Get a binding's event handler.
int	getId() Get the system-wide unique binding id.
MessageLatencyManager	getLatencyManager() Get a binding's latency manager This method can be invoked on a binding in any state.
MessageChannel	getMessageChannel(String channelName) Get a handle to a message channel.
XString	getNameAsRaw() Get this MessageBusBinding's name as an XString
MessageBusBinding.State	getState() Get a binding's state.
void	getStats(StringBuilder sb) Get a binding's provider specific stats.
String	getType() Get this MessageBusBinding's type.
XString	getTypeAsRaw() Get this MessageBusBinding's type as an XString Returns the provider name for this bus.
String	getUserName() Get the name of the user that created a binding.
void	setAttachment(Object object) This method is reserved for internal use.
void	setPostMessagePrepProcessor(MessageBusBinding.PostMessagePrepProcessor processor) Set the post message prep processor
void	setSequenceNumberGenerator(MessageBusBinding.SequenceNumberGenerator generator) Set the sequence number generator
void	setStatsListener(MessageBusBinding.StatsListener callback) This method is reserved for internal use.
void	start() Start a binding.

Methods inherited from interface com.neeve.event.IEventSource

getName

Field Detail

PRESERVE_CHANNEL_JOINS

static final int PRESERVE_CHANNEL_JOINS

Flag that can be used on close(flags) to indicate that the binding that should not leave channels that were joined, but instead preserve any interests or subscriptions that have been established.

See Also:

Constant Field Values

TRANSPORT_HEADER_RECEIVED_CHANNEL

static final XString TRANSPORT_HEADER_RECEIVED_CHANNEL

Defines the transport header name for the received channel name.

When a received messsage is dispatched using a catch all channel, and message transport headers are enabled, this header is used to record the name or id of the channel on which the message was received. If the received message included metadata with the channel name this

Header Name: rcvdChannel
Header Name: String if channel name known, short if id is known

Method Detail

setAttachment

void setAttachment(Object object)

This method is reserved for internal use.

getAttachment

Object getAttachment()

This method is reserved for internal use.

setStatsListener

void setStatsListener(MessageBusBinding.StatsListener callback)

This method is reserved for internal use.

A StatsListener must be set prior to the bus being opened, and once set cannot be changed.

setSequenceNumberGenerator

void setSequenceNumberGenerator(MessageBusBinding.SequenceNumberGenerator generator)

Set the sequence number generator

Parameters:

generator - The generator to set

Throws:

IllegalStateException - thrown if this method is invoked in any state other than MessageBusBinding.State.Open

This method installs an external sequence number generator on a message bus binding. The generator must be installed prior to starting the binding.

setPostMessagePrepProcessor

void setPostMessagePrepProcessor(MessageBusBinding.PostMessagePrepProcessor processor)

Set the post message prep processor

Parameters:

processor - The processor to set

Throws:

IllegalStateException - thrown if this method is invoked in any state other than MessageBusBinding.State.Open

This method installs a post message prep processor on a message bus binding. The generator must be installed prior to starting the binding.

getId

int getId()

Get the system-wide unique binding id.

Each binding generates a system-wide unique identifier to uniquely identify itself across all bus bindings in the system. This method returns a binding's unique id.

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

Threading:

This method is safe for concurrent access by multiple threads.

getType

String getType()

Get this MessageBusBinding's type.

Returns the provider name for this bus.

Threading:

This method is safe for concurrent access by multiple threads.

getTypeAsRaw

XString getTypeAsRaw()

Get this MessageBusBinding's type as an XString

Returns the provider name for this bus.

Threading:

This method is safe for concurrent access by multiple threads.

getNameAsRaw

XString getNameAsRaw()

Get this MessageBusBinding's name as an XString

Threading:

This method is safe for concurrent access by multiple threads.

getUserName

String getUserName()

Get the name of the user that created a binding.

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

Threading:

This method is safe for concurrent access by multiple threads.

getDescriptor

MessageBusDescriptor getDescriptor()

Get the bus descriptor used to created a binding.

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

Threading:

This method is safe for concurrent access by multiple threads.

getLatencyManager

MessageLatencyManager getLatencyManager()

Get a binding's latency manager

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

Threading:

This method is safe for concurrent access by multiple threads.

getStats

void getStats(StringBuilder sb)

Get a binding's provider specific stats.

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

Parameters:

sb - The string builder into which to write stats.

Threading:

This method is safe for concurrent access by multiple threads.

getEventHandler

IEventHandler getEventHandler()

Get a binding's event handler.

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

Threading:

This method is safe for concurrent access by multiple threads.

getState

MessageBusBinding.State getState()

Get a binding's state.

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

Threading:

This method is safe for concurrent access by multiple threads.

getMessageChannel

MessageChannel getMessageChannel(String channelName)
                          throws SmaException

Get a handle to a message channel.

This method returns a user private handle to a message channel. The returned handle is ready to send messages through the channel. The user needs to MessageChannel.join(int) the channel to receive messages from the channel.

It is safe to call this method repeatedly. A call to get a channel that has already been previously gotten (and not released) will return the same handle that was returned by the previous get.

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

Parameters:

channelName - The name of the channel to get.

Throws:

SmaException - Thrown in case an error is encountered during this method.

Threading:

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

start

void start()
    throws SmaException

Start a binding.

A message bus binding is ready for outbound traffic as soon as it is opened. However, it needs to be started before inbound messages triggered by channel joins are received and dispatched to the user. Although a channel join can succeed the starting of a binding, if the user joins a channel after starting the binding, there is a chance of message loss for guaranteed channels since the received messages will be discarded by the SMA runtime till the channel is joined. Therefore, it is recommended that the user create the binding, join desired channels and then start the binding.

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

Throws:

SmaException

Threading:

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

flush

void flush()
    throws SmaException

Flush all outbound messages buffered by a binding.

This method transmits all outbound messages and/or acks buffered by a binding. The call does not return until all buffered messages are transmitted or an error is encountered.

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

Throws:

SmaException - Thrown in case an error is encountered while flushing the queue.

Threading:

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

canFail

boolean canFail()

Get whether a binding can fail.

This method queries the binding as to whether it can fail. Only bindings that can fail dispatch the 'binding failed' event when they fail. See com.neeve.sma.event for the various SMA events.

This method can be invoked on bindings in any state.

Threading:

This method is safe for concurrent access by multiple threads.

acksRequireFlush

boolean acksRequireFlush()

Get whether a binding requires a flush for acks to be sent.

This method returns whether a binding immediately sends acknowledgments through the underlying provider or enques the ACK for later send through either an explicit flush by the user or an implicit flush by the provider. The caller should use this method to determine whether a flush is needed to ensure that the ACKs are indeed dispatched onto the wire.

This method can be invoked on bindings in any state.

Threading:

This method is safe for concurrent access by multiple threads.

fail

void fail(Exception e,
          boolean dispatchFailureEvent)
   throws SmaException

Fail a message bus binding.

This method 'fails' a binding. It is only supported for bindings that can fail i.e. those bindings whose canFail() method return true. For such bindings, this method triggers the machinery that puts the binding in the same state as if the binding had actually failed. This includes dispatching the 'binding failure' event containing the exception supplied to this method. An exception is thrown by this method if invoked on a binding that does not support failures.

This method can only be invoked on Open or Closing bindings. An exception will be thrown if invoked on bindings in any other state.

Parameters:

e - The exception to be associated with the 'binding failed' event that will be triggered by this method.

dispatchFailureEvent - Indicates whether a failure event should be dispatched to the user or not.

Throws:

SmaException - Thrown in case an error is encountered during this method.

Threading:

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

close

void close()
    throws SmaException

Close a message bus binding.

This method is used to close a bus binding. This method will also close all message channels managed by the bindings. It is safe to invoke this method multiple times.

This method can be invoked on Open, Closing, Failed or Closed bindings. An exception will be thrown if invoked on bindings in any other state. Calling this method on a Closing or Closed channel has no effect and results in the call returning immediately.

Throws:

SmaException - Thrown in case an error is encountered during the closing of the binding, in which case the caller should inspect the state of the binding and its channels to determine the effective outcome of the call.

Threading:

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

close

void close(int closeFlags)
    throws SmaException

Close a message bus binding.

This method is used to close a bus binding. This method will also close all message channels managed by the bindings. It is safe to invoke this method multiple times.

This method can be invoked on Open, Closing, Failed or Closed bindings. An exception will be thrown if invoked on bindings in any other state. Calling this method on a Closing or Closed channel has no effect and results in the call returning immediately.

Parameters:

closeFlags - Indicates whether or not to leave channels that were previously joined. Specifying a value of false causes subscriptions and interests for this buses channels in tact. Permissible flags are:

• PRESERVE_CHANNEL_JOINS

Throws:

SmaException - Thrown in case an error is encountered during the closing of the binding, in which case the caller should inspect the state of the binding and its channels to determine the effective outcome of the call.

Threading:

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