com.neeve.sma
Interface MessageBusBinding

All Superinterfaces:

com.neeve.event.IEventSource

All Known Implementing Classes:

LoopbackMessageBusBinding, com.neeve.sma.impl.MessageBusBindingBase

public interface MessageBusBinding
extends com.neeve.event.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

static class	MessageBusBinding.AsynchronousFlushContext Context for flushing using asychnronous semantics.
static class	MessageBusBinding.FlushContext Base class for all flushing contexts.
static class	MessageBusBinding.State Enumerates the different binding states
static class	MessageBusBinding.SynchronousBlockingFlushContext Context for flushing using synchronous blocking semantics.
static class	MessageBusBinding.SynchronousNonBlockingFlushContext Context for flushing using synchronous non-blocking semantics.

Method Summary

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	fail(Exception e, boolean dispatchFailureEvent) Fail a message bus binding.
void	flush(MessageBusBinding.FlushContext flushContext) 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.
com.neeve.event.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
MessageChannel	getMessageChannel(String channelName) Get a handle to a message channel.
com.neeve.raw.RawString	getNameAsRaw() Get this MessageBusBinding's name as a RawString
MessageBusBinding.State	getState() Get a binding's state.
String	getStats() Get a binding's stats
String	getUserName() Get the name of the user that created a binding.
void	setAttachment(Object object) This method is reserved for internal use.
void	start() Start a binding.

Methods inherited from interface com.neeve.event.IEventSource

getName

Method Detail

setAttachment

void setAttachment(Object object)

This method is reserved for internal use.

getAttachment

Object getAttachment()

This method is reserved for internal use.

getId

int getId()

Get the system-wide unique binding id.

Threading:

This method is safe for concurrent access by multiple threads.

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.

getNameAsRaw

com.neeve.raw.RawString getNameAsRaw()

Get this MessageBusBinding's name as a RawString

getUserName

String getUserName()

Get the name of the user that created a binding.

Threading:

This method is safe for concurrent access by multiple threads.

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

getDescriptor

MessageBusDescriptor getDescriptor()

Get the bus descriptor used to created a binding.

Threading:

This method is safe for concurrent access by multiple threads.

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

getLatencyManager

MessageLatencyManager getLatencyManager()

Get a binding's latency manager

Threading:

This method is safe for concurrent access by multiple threads.

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

getStats

String getStats()

Get a binding's stats

Threading:

This method is safe for concurrent access by multiple threads.

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

getEventHandler

com.neeve.event.IEventHandler getEventHandler()

Get a binding's event handler.

Threading:

This method is safe for concurrent access by multiple threads.

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

getState

MessageBusBinding.State getState()

Get a binding's state.

Threading:

This method is safe for concurrent access by multiple threads.

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

getMessageChannel

MessageChannel getMessageChannel(String channelName)
                                 throws SmaException

Get a handle to a message channel.

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.

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.

start

void start()
           throws SmaException

Start a binding.

Throws:

SmaException

Threading:

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

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.

flush

void flush(MessageBusBinding.FlushContext flushContext)
           throws SmaException

Flush all outbound messages buffered by a binding.

Parameters:

flushContext - A context object indicating the IO semantics and runtime context information related to the flush. A value of null is interpeted as a request for synchronous flush.

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.

This method transmits all outbound messages 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.

canFail

boolean canFail()

Get whether a binding can fail.

Threading:

This method is safe for concurrent access by multiple threads.

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.

acksRequireFlush

boolean acksRequireFlush()

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

Threading:

This method is safe for concurrent access by multiple threads.

This method returns whether a binding immediately sends acknowledgments through the underlying provider or enques the ACK for later send hrough 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.

fail

void fail(Exception e,
          boolean dispatchFailureEvent)
          throws SmaException

Fail a message bus binding.

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.

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

Threading:

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

close

void close()
           throws SmaException

Close a message bus binding.

Throws:

SmaException - Thrown in case an error is encountered during the closing of the binding. The user should assume that the binding is still open in case the exception is thrown.

Threading:

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

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