MessageChannel (org.macroing.cit.messaging API)

java.lang.Object
- org.macroing.cit.messaging.MessageChannel

```
public final class MessageChannel
extends java.lang.Object
```
A MessageChannel is a channel in which you can send Messages.
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:
- A MessageChannelObserver to observe Messages sent to it.
- A MessageFilter to filter out which Messages you want to handle.
- A MessageHandler to handle a given Message. If a MessageHandler cannot handle a Message, the next MessageHandler can give it a try.
- A MessageTranslator to potentially translate a given Message into a completely different Message.
Since:

1.0.0

Author:

Jörgen Lundgren

Constructor Summary

Constructors
Constructor and Description
`MessageChannel()` Constructs a new empty `MessageChannel` instance.
`MessageChannel(java.util.concurrent.atomic.AtomicBoolean isActive)` Constructs a new empty `MessageChannel` instance.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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()` Returns a `List` containing all `MessageChannelObserver`s currently added to this `MessageChannel`.
`java.util.List<MessageFilter>`	`getMessageFilters()` Returns a `List` containing all `MessageFilter`s currently added to this `MessageChannel`.
`java.util.List<MessageHandler>`	`getMessageHandlers()` Returns a `List` containing all `MessageHandler`s currently added to this `MessageChannel`.
`java.util.List<MessageTranslator>`	`getMessageTranslators()` Returns a `List` containing all `MessageTranslator`s currently added to this `MessageChannel`.
`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`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - MessageChannel
```
public MessageChannel()
```
    Constructs a new empty MessageChannel instance.
    Calling this constructor is equivalent to calling new MessageChannel(new AtomicBoolean(true)).
  - MessageChannel
```
public MessageChannel(java.util.concurrent.atomic.AtomicBoolean isActive)
```
    Constructs a new empty MessageChannel instance.
    If isActive is null, a NullPointerException will be thrown.
    
    Parameters:
    
    isActive - a facility that can be used to control whether a MessageChannel is active or not
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, isActive is null
- Method Detail
  - addMessageChannelObserver
```
public boolean addMessageChannelObserver(MessageChannelObserver messageChannelObserver)
```
    Adds 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.
    
    Parameters:
    
    messageChannelObserver - the MessageChannelObserver to add
    
    Returns:
    
    true if, and only if, messageChannelObserver was added, false otherwise
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, messageChannelObserver is null
  - addMessageFilter
```
public boolean addMessageFilter(MessageFilter messageFilter)
```
    Adds 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.
    
    Parameters:
    
    messageFilter - the MessageFilter to add
    
    Returns:
    
    true if, and only if, messageFilter was added, false otherwise
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, messageFilter is null
  - addMessageHandler
```
public boolean addMessageHandler(MessageHandler messageHandler)
```
    Adds 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.
    
    Parameters:
    
    messageHandler - the MessageHandler to add
    
    Returns:
    
    true if, and only if, messageHandler was added, false otherwise
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, messageHandler is null
  - addMessageTranslator
```
public boolean addMessageTranslator(MessageTranslator messageTranslator)
```
    Adds 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.
    
    Parameters:
    
    messageTranslator - the MessageTranslator to add
    
    Returns:
    
    true if, and only if, messageTranslator was added, false otherwise
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, messageTranslator is null
  - isActive
```
public boolean isActive()
```
    Returns true if, and only if, this MessageChannel is active, false otherwise.
    
    Returns:
    
    true if, and only if, this MessageChannel is active, false otherwise
  - removeMessageChannelObserver
```
public boolean removeMessageChannelObserver(MessageChannelObserver messageChannelObserver)
```
    Removes 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.
    
    Parameters:
    
    messageChannelObserver - the MessageChannelObserver to remove
    
    Returns:
    
    true if, and only if, messageChannelObserver was removed, false otherwise
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, messageChannelObserver is null
  - removeMessageFilter
```
public boolean removeMessageFilter(MessageFilter messageFilter)
```
    Removes 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.
    
    Parameters:
    
    messageFilter - the MessageFilter to remove
    
    Returns:
    
    true if, and only if, messageFilter was removed, false otherwise
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, messageFilter is null
  - removeMessageHandler
```
public boolean removeMessageHandler(MessageHandler messageHandler)
```
    Removes 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.
    
    Parameters:
    
    messageHandler - the MessageHandler to remove
    
    Returns:
    
    true if, and only if, messageHandler was removed, false otherwise
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, messageHandler is null
  - removeMessageTranslator
```
public boolean removeMessageTranslator(MessageTranslator messageTranslator)
```
    Removes 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.
    
    Parameters:
    
    messageTranslator - the MessageTranslator to remove
    
    Returns:
    
    true if, and only if, messageTranslator was removed, false otherwise
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, messageTranslator is null
  - getMessageChannelObservers
```
public java.util.List<MessageChannelObserver> getMessageChannelObservers()
```
    Returns a List containing all MessageChannelObservers currently added to this MessageChannel.
    If no MessageChannelObservers have been added, an empty List will be returned, not null.
    Modifying the returned List will not affect this MessageChannel instance.
    
    Returns:
    
    a List containing all MessageChannelObservers currently added to this MessageChannel
  - getMessageFilters
```
public java.util.List<MessageFilter> getMessageFilters()
```
    Returns a List containing all MessageFilters currently added to this MessageChannel.
    If no MessageFilters have been added, an empty List will be returned, not null.
    Modifying the returned List will not affect this MessageChannel instance.
    
    Returns:
    
    a List containing all MessageFilters currently added to this MessageChannel
  - getMessageHandlers
```
public java.util.List<MessageHandler> getMessageHandlers()
```
    Returns a List containing all MessageHandlers currently added to this MessageChannel.
    If no MessageHandlers have been added, an empty List will be returned, not null.
    Modifying the returned List will not affect this MessageChannel instance.
    
    Returns:
    
    a List containing all MessageHandlers currently added to this MessageChannel
  - getMessageTranslators
```
public java.util.List<MessageTranslator> getMessageTranslators()
```
    Returns a List containing all MessageTranslators currently added to this MessageChannel.
    If no MessageTranslators have been added, an empty List will be returned, not null.
    Modifying the returned List will not affect this MessageChannel instance.
    
    Returns:
    
    a List containing all MessageTranslators currently added to this MessageChannel
  - removeAllMessageChannelObservers
```
public void removeAllMessageChannelObservers()
```
    Removes all currently added MessageChannelObservers from this MessageChannel.
  - removeAllMessageFilters
```
public void removeAllMessageFilters()
```
    Removes all currently added MessageFilters from this MessageChannel.
  - removeAllMessageHandlers
```
public void removeAllMessageHandlers()
```
    Removes all currently added MessageHandlers from this MessageChannel.
  - removeAllMessageTranslators
```
public void removeAllMessageTranslators()
```
    Removes all currently added MessageTranslators from this MessageChannel.
  - sendMessage
```
public void sendMessage(Message message)
```
    Sends a 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:
    1. A check that this MessageChannel is active will be made. If it isn't active, all subsequent steps will be discarded.
    2. All currently added MessageFilters 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.
    3. All currently added MessageTranslators 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.
    4. All currently added MessageChannelObservers will be traversed and notified of the given Message being sent.
    5. Some or all currently added MessageHandlers 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.
    Parameters:
    
    message - the Message to be sent
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, message, or a translated version of it, is null
  - newInstance
```
public static MessageChannel newInstance()
```
    Returns a new MessageChannel instance.
    Calling this method is equivalent to calling MessageChannel.newInstance(new AtomicBoolean(true)).
    
    Returns:
    
    a new MessageChannel instance
  - newInstance
```
public static MessageChannel newInstance(java.util.concurrent.atomic.AtomicBoolean isActive)
```
    Returns a new MessageChannel instance.
    If isActive is null, a NullPointerException will be thrown.
    
    Parameters:
    
    isActive - a facility that can be used to control whether a MessageChannel is active or not
    
    Returns:
    
    a new MessageChannel instance
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, isActive is null

Class MessageChannel

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MessageChannel

MessageChannel

Method Detail

addMessageChannelObserver

addMessageFilter

addMessageHandler

addMessageTranslator

isActive

removeMessageChannelObserver

removeMessageFilter

removeMessageHandler

removeMessageTranslator

getMessageChannelObservers

getMessageFilters

getMessageHandlers

getMessageTranslators

removeAllMessageChannelObservers

removeAllMessageFilters

removeAllMessageHandlers

removeAllMessageTranslators

sendMessage

newInstance

newInstance