public final class MessageChannel
extends java.lang.Object
MessageChannel
is a channel in which you can send Message
s.
But that's not all there is to it. Once you obtain a reference to a MessageChannel
instance, you have a few different options available at your disposal.
A MessageChannel
has methods by which you can add one or more of the following:
MessageChannelObserver
to observe Message
s sent to it.MessageFilter
to filter out which Message
s you want to handle.MessageHandler
to handle a given Message
. If a MessageHandler
cannot handle a Message
, the next MessageHandler
can give it a try.MessageTranslator
to potentially translate a given Message
into a completely different Message
.Constructor and Description |
---|
MessageChannel()
Constructs a new empty
MessageChannel instance. |
MessageChannel(java.util.concurrent.atomic.AtomicBoolean isActive)
Constructs a new empty
MessageChannel instance. |
Modifier and Type | Method and Description |
---|---|
boolean |
addMessageChannelObserver(MessageChannelObserver messageChannelObserver)
Adds
messageChannelObserver to this MessageChannel , if absent. |
boolean |
addMessageFilter(MessageFilter messageFilter)
Adds
messageFilter to this MessageChannel , if absent. |
boolean |
addMessageHandler(MessageHandler messageHandler)
Adds
messageHandler to this MessageChannel , if absent. |
boolean |
addMessageTranslator(MessageTranslator messageTranslator)
Adds
messageTranslator to this MessageChannel , if absent. |
java.util.List<MessageChannelObserver> |
getMessageChannelObservers()
|
java.util.List<MessageFilter> |
getMessageFilters()
|
java.util.List<MessageHandler> |
getMessageHandlers()
|
java.util.List<MessageTranslator> |
getMessageTranslators()
|
boolean |
isActive()
Returns
true if, and only if, this MessageChannel is active, false otherwise. |
static MessageChannel |
newInstance()
Returns a new
MessageChannel instance. |
static MessageChannel |
newInstance(java.util.concurrent.atomic.AtomicBoolean isActive)
Returns a new
MessageChannel instance. |
void |
removeAllMessageChannelObservers()
Removes all currently added
MessageChannelObserver s from this MessageChannel . |
void |
removeAllMessageFilters()
Removes all currently added
MessageFilter s from this MessageChannel . |
void |
removeAllMessageHandlers()
Removes all currently added
MessageHandler s from this MessageChannel . |
void |
removeAllMessageTranslators()
Removes all currently added
MessageTranslator s from this MessageChannel . |
boolean |
removeMessageChannelObserver(MessageChannelObserver messageChannelObserver)
Removes
messageChannelObserver from this MessageChannel , if present. |
boolean |
removeMessageFilter(MessageFilter messageFilter)
Removes
messageFilter from this MessageChannel , if present. |
boolean |
removeMessageHandler(MessageHandler messageHandler)
Removes
messageHandler from this MessageChannel , if present. |
boolean |
removeMessageTranslator(MessageTranslator messageTranslator)
Removes
messageTranslator from this MessageChannel , if present. |
void |
sendMessage(Message message)
Sends a
Message . |
public MessageChannel()
MessageChannel
instance.
Calling this constructor is equivalent to calling new MessageChannel(new AtomicBoolean(true))
.
public MessageChannel(java.util.concurrent.atomic.AtomicBoolean isActive)
MessageChannel
instance.
If isActive
is null
, a NullPointerException
will be thrown.
isActive
- a facility that can be used to control whether a MessageChannel
is active or notjava.lang.NullPointerException
- thrown if, and only if, isActive
is null
public boolean addMessageChannelObserver(MessageChannelObserver messageChannelObserver)
messageChannelObserver
to this MessageChannel
, if absent.
Returns true
if, and only if, messageChannelObserver
was added, false
otherwise.
If messageChannelObserver
is null
, a NullPointerException
will be thrown.
messageChannelObserver
- the MessageChannelObserver
to addtrue
if, and only if, messageChannelObserver
was added, false
otherwisejava.lang.NullPointerException
- thrown if, and only if, messageChannelObserver
is null
public boolean addMessageFilter(MessageFilter messageFilter)
messageFilter
to this MessageChannel
, if absent.
Returns true
if, and only if, messageFilter
was added, false
otherwise.
If messageFilter
is null
, a NullPointerException
will be thrown.
messageFilter
- the MessageFilter
to addtrue
if, and only if, messageFilter
was added, false
otherwisejava.lang.NullPointerException
- thrown if, and only if, messageFilter
is null
public boolean addMessageHandler(MessageHandler messageHandler)
messageHandler
to this MessageChannel
, if absent.
Returns true
if, and only if, messageHandler
was added, false
otherwise.
If messageHandler
is null
, a NullPointerException
will be thrown.
messageHandler
- the MessageHandler
to addtrue
if, and only if, messageHandler
was added, false
otherwisejava.lang.NullPointerException
- thrown if, and only if, messageHandler
is null
public boolean addMessageTranslator(MessageTranslator messageTranslator)
messageTranslator
to this MessageChannel
, if absent.
Returns true
if, and only if, messageTranslator
was added, false
otherwise.
If messageTranslator
is null
, a NullPointerException
will be thrown.
messageTranslator
- the MessageTranslator
to addtrue
if, and only if, messageTranslator
was added, false
otherwisejava.lang.NullPointerException
- thrown if, and only if, messageTranslator
is null
public boolean isActive()
true
if, and only if, this MessageChannel
is active, false
otherwise.true
if, and only if, this MessageChannel
is active, false
otherwisepublic boolean removeMessageChannelObserver(MessageChannelObserver messageChannelObserver)
messageChannelObserver
from this MessageChannel
, if present.
Returns true
if, and only if, messageChannelObserver
was removed, false
otherwise.
If messageChannelObserver
is null
, a NullPointerException
will be thrown.
messageChannelObserver
- the MessageChannelObserver
to removetrue
if, and only if, messageChannelObserver
was removed, false
otherwisejava.lang.NullPointerException
- thrown if, and only if, messageChannelObserver
is null
public boolean removeMessageFilter(MessageFilter messageFilter)
messageFilter
from this MessageChannel
, if present.
Returns true
if, and only if, messageFilter
was removed, false
otherwise.
If messageFilter
is null
, a NullPointerException
will be thrown.
messageFilter
- the MessageFilter
to removetrue
if, and only if, messageFilter
was removed, false
otherwisejava.lang.NullPointerException
- thrown if, and only if, messageFilter
is null
public boolean removeMessageHandler(MessageHandler messageHandler)
messageHandler
from this MessageChannel
, if present.
Returns true
if, and only if, messageHandler
was removed, false
otherwise.
If messageHandler
is null
, a NullPointerException
will be thrown.
messageHandler
- the MessageHandler
to removetrue
if, and only if, messageHandler
was removed, false
otherwisejava.lang.NullPointerException
- thrown if, and only if, messageHandler
is null
public boolean removeMessageTranslator(MessageTranslator messageTranslator)
messageTranslator
from this MessageChannel
, if present.
Returns true
if, and only if, messageTranslator
was removed, false
otherwise.
If messageTranslator
is null
, a NullPointerException
will be thrown.
messageTranslator
- the MessageTranslator
to removetrue
if, and only if, messageTranslator
was removed, false
otherwisejava.lang.NullPointerException
- thrown if, and only if, messageTranslator
is null
public java.util.List<MessageChannelObserver> getMessageChannelObservers()
List
containing all MessageChannelObserver
s currently added to this MessageChannel
.
If no MessageChannelObserver
s have been added, an empty List
will be returned, not null
.
Modifying the returned List
will not affect this MessageChannel
instance.
List
containing all MessageChannelObserver
s currently added to this MessageChannel
public java.util.List<MessageFilter> getMessageFilters()
List
containing all MessageFilter
s currently added to this MessageChannel
.
If no MessageFilter
s have been added, an empty List
will be returned, not null
.
Modifying the returned List
will not affect this MessageChannel
instance.
List
containing all MessageFilter
s currently added to this MessageChannel
public java.util.List<MessageHandler> getMessageHandlers()
List
containing all MessageHandler
s currently added to this MessageChannel
.
If no MessageHandler
s have been added, an empty List
will be returned, not null
.
Modifying the returned List
will not affect this MessageChannel
instance.
List
containing all MessageHandler
s currently added to this MessageChannel
public java.util.List<MessageTranslator> getMessageTranslators()
List
containing all MessageTranslator
s currently added to this MessageChannel
.
If no MessageTranslator
s have been added, an empty List
will be returned, not null
.
Modifying the returned List
will not affect this MessageChannel
instance.
List
containing all MessageTranslator
s currently added to this MessageChannel
public void removeAllMessageChannelObservers()
MessageChannelObserver
s from this MessageChannel
.public void removeAllMessageFilters()
MessageFilter
s from this MessageChannel
.public void removeAllMessageHandlers()
MessageHandler
s from this MessageChannel
.public void removeAllMessageTranslators()
MessageTranslator
s from this MessageChannel
.public void sendMessage(Message message)
Message
.
If message
is null
, a NullPointerException
will be thrown.
As soon as a Message
is sent to a MessageChannel
, the following will essentially happen:
MessageChannel
is active will be made. If it isn't active, all subsequent steps will be discarded.
MessageFilter
s will be traversed, such that the Message
being sent can be verified to be valid. If it is valid, the next step will be performed.
MessageTranslator
s will be traversed, such that the Message
being sent can be translated. Each successive translation will operate on the previous version of the Message
,
starting with the original instance. If a MessageTranslator
returns null
, a NullPointerException
will be thrown.
MessageChannelObserver
s will be traversed and notified of the given Message
being sent.
MessageHandler
s will be traversed and given the opportunity to handle the Message
. Each MessageHandler
can decide to stop the chain by returning true
, in
which case the Message
is said to have been successfully handled. Stopping the chain means that no successive MessageHandler
will be able to handle it. This approach is a form of the Chain of
Responsibility (CoR) design pattern.
message
- the Message
to be sentjava.lang.NullPointerException
- thrown if, and only if, message
, or a translated version of it, is null
public static MessageChannel newInstance()
MessageChannel
instance.
Calling this method is equivalent to calling MessageChannel.newInstance(new AtomicBoolean(true))
.
MessageChannel
instancepublic static MessageChannel newInstance(java.util.concurrent.atomic.AtomicBoolean isActive)
MessageChannel
instance.
If isActive
is null
, a NullPointerException
will be thrown.
isActive
- a facility that can be used to control whether a MessageChannel
is active or notMessageChannel
instancejava.lang.NullPointerException
- thrown if, and only if, isActive
is null