org.mbassy

Interface IMessageBus<T,P extends IMessageBus.IPostCommand>

All Known Implementing Classes:

AbstractMessageBus, MBassador

public interface IMessageBus<T,P extends IMessageBus.IPostCommand>

A message bus offers facilities for publishing messages to registered listeners. Messages can be dispatched synchronously or asynchronously and may be of any type that is a valid sub type of the type parameter T. The dispatch mechanism can by controlled for per message handler and message publication. A message publication is the publication of any message using one of the bus' publication methods.

Each message publication is isolated from all other running publications such that it does not interfere with them. Hence, the bus expects message handlers to be stateless as it may invoke them concurrently if multiple messages get published asynchronously.

A listener is any object that defines at least one message handler and that has been subscribed to at least one message bus. A message handler can be any method that accepts exactly one parameter (the message) and is marked as a message handler using the @Listener annotation.

The bus uses weak references to all listeners such that registered listeners do not need to be explicitly unregistered to be eligible for garbage collection. Dead (garbage collected) listeners are removed on-the-fly as messages get dispatched.

Generally message handlers will be invoked in inverse sequence of subscription but any client using this bus should not rely on this assumption. The basic contract of the bus is that it will deliver a specific message exactly once to each of the subscribed message handlers.

Messages are dispatched to all listeners that accept the type or supertype of the dispatched message. Additionally a message handler may define filters to narrow the set of messages that it accepts.

Subscribed message handlers are available to all pending message publications that have not yet started processing. Any message listener may only be subscribed once -> subsequent subscriptions of an already subscribed message listener will be silently ignored)

Removing a listener (unsubscribing) means removing all subscribed message handlers of that listener. This remove operation immediately takes effect and on all running dispatch processes -> A removed listener (a listener is considered removed after the remove(Object) call returned) will under no circumstances receive any message publications. Any running message publication that has not yet delivered the message to the removed listener will not see the listener after the remove operation completed. NOTE: Generic type parameters of messages will not be taken into account, e.g. a List will get dispatched to all message handlers that take an instance of List as their parameter

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	IMessageBus.IPostCommand<T> A post command is used as an intermediate object created by a call to the message bus' post method.

Method Summary

Methods

Modifier and Type	Method and Description
void	addErrorHandler(IPublicationErrorHandler errorHandler) Publication errors may occur at various points of time during message delivery.
Executor	getExecutor() Get the executor service that is used to asynchronous message publication.
Collection<IPublicationErrorHandler>	getRegisteredErrorHandlers() Returns an immutable collection containing all the registered error handlers
boolean	hasPendingMessages() Check whether any asynchronous message publications are pending for being processed
P	post(T message)
void	subscribe(Object listener) Subscribe all listeners of the given message to receive message publications.
boolean	unsubscribe(Object listener) Immediately remove all registered message handlers (if any) of the given listener.

Method Detail

subscribe

void subscribe(Object listener)

Subscribe all listeners of the given message to receive message publications. Any message may only be subscribed once (subsequent subscriptions of an already subscribed message will be silently ignored)

Parameters:

listener -

unsubscribe

boolean unsubscribe(Object listener)

Immediately remove all registered message handlers (if any) of the given listener. When this call returns all handlers have effectively been removed and will not receive any message publications (including asynchronously scheduled publications that have been published when the message listener was still subscribed). A call to this method passing null, an already unsubscribed listener or any object that does not define any message handlers will not have any effect and is silently ignored.

Parameters:

listener -

Returns:

true, if the listener was found and successfully removed false otherwise

post

P post(T message)

Parameters:

message -

Returns:

addErrorHandler

void addErrorHandler(IPublicationErrorHandler errorHandler)

Publication errors may occur at various points of time during message delivery. A handler may throw an exception, may not be accessible due to security constraints or is not annotated properly. In any of all possible cases a publication error is created and passed to each of the registered error handlers. A call to this method will add the given error handler to the chain

Parameters:

errorHandler -

getRegisteredErrorHandlers

Collection<IPublicationErrorHandler> getRegisteredErrorHandlers()

Returns an immutable collection containing all the registered error handlers

Returns:

getExecutor

Executor getExecutor()

Get the executor service that is used to asynchronous message publication. The executor is passed to the message bus at creation time.

Returns:

hasPendingMessages

boolean hasPendingMessages()

Check whether any asynchronous message publications are pending for being processed

Returns: