PIRL.Messenger

## Class Dispatcher

- java.lang.Object
- - PIRL.Messenger.Dispatcher

All Implemented Interfaces:
  Runnable, EventListener, Message_Delivered_Listener

Direct Known Subclasses:
  Stage_Manager

    public class Dispatcher
    extends Object
    implements Message_Delivered_Listener, Runnable

A Dispatcher is a Messenger manager for communication between client processes.

A Dispatcher is typically used as a background daemon application process that accepts connections from clients on a designated communications ports, allocates a Messenger to each client, manages the Messengers, and handles a core set of Messenger management Messages. When a Distpatcher is started it will send a "Hello" broadcast on a designated multicast port to any clients listening on the local host system who might be interested in making a connection.

A Dispatcher may be subclassed to add a additional Message protocol support

A Configuration file is used to Configure a Dispatcher's operating variables before it begins running.

A log file may be specified where client connection/deconnection and other important events are reported.

Support is provided for authenticated client connections using a public key to exchange an encoded private password that is decoded by a private key paired with the public key.

See Also:
  `Messenger`

### Field Summary

Fields
`static String` `ACK_ACTION` Messenger management Message Actions and their parameters.
`static String` `ACTION_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `ADDRESS_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `CLASS_ID_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `CONFIGURATION_SOURCE_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static SimpleDateFormat` `DATE_FORMAT` Format for log message timestamps.
`static String` `DATE_FORMATTING` Formatting pattern for log message timestamps.
`static String` `DEFAULT_DISPATCHER_NAME` The default name of the Dispatcher: "Dispatcher".
`static String` `DEFAULT_HELLO_ADDRESS` The default private multicast address to use in the Hello datagram.
`static int` `DEFAULT_HELLO_PORT` The default port on which to send the Hello datagram.
`static int` `DEFAULT_IDENTIFY_TIMEOUT` The default maximum amount of time, in seconds, to wait for a new Messenger client to respond to an identify message.
`static int` `DEFAULT_PORT` The default communications port number.
`protected String` `Dispatcher_ID` The ID of of the Dispatcher.
`static String` `DONE_ACTION` Messenger management Message Actions and their parameters.
`static String` `EXCEPTION_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static int` `EXIT_COMMAND_LINE_SYNTAX` Command line syntax problem exit status.
`static int` `EXIT_CONFIG_FILE_PROBLEM` The log file could not be opened for writing exit status.
`static int` `EXIT_IO_ERROR` IOException failure exit status.
`static int` `EXIT_NO_LOG_FILE` The log file could not be opened for writing exit status.
`static int` `EXIT_SECURITY_VIOLATION` SecurityException exit status.
`static int` `EXIT_SUCCESS` Success exit status.
`static int` `EXIT_UNKNOWN_EXCEPTION` Unknown exception (possible programming flaw).
`static String` `EXPLANATION_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `HELLO_ADDRESS_PARAMETER_NAME` The configuration parameter name for the Hello multicast address.
`static String` `HELLO_MESSAGE` The content of the Hello broadcast datagram message.
`static String` `HELLO_PORT_PARAMETER_NAME` The configuration parameter name for the Hello port.
`static String` `HELLO_RATE_PARAMETER_NAME` The configuration parameter name for the Hello repeat rate (seconds).
`static String` `ID` Class identification name with source code version and date.
`static String` `IDENTIFY_ACTION` Messenger management Message Actions and their parameters.
`static String` `IDENTIFY_TIMEOUT_PARAMETER_NAME` The configuration parameter name for the maximum wait time, in seconds, for a new Messenger client connection to respond to the identify message.
`static String` `IDENTITY_ACTION` Messenger management Message Actions and their parameters.
`static String` `KEY_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `LINK_MESSENGER_ACTION` Messenger management Message Actions and their parameters.
`static String` `LOG_PATHNAME_PARAMETER_NAME` The configuration parameter name for the log file pathname.
`protected PrintStream` `Log_Stream` Log output stream.
`static String` `MEMORY_ALLOCATED_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MEMORY_AVAILABLE_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MEMORY_FREE_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MEMORY_STATUS_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MESSAGE_BYTES_RECEIVED_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MESSAGE_BYTES_SENT_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MESSAGES_RECEIVED_CORRUPTED_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MESSAGES_RECEIVED_DROPPED_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MESSAGES_RECEIVED_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MESSAGES_SENT_CORRUPTED_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MESSAGES_SENT_DROPPED_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MESSAGES_SENT_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MESSAGES_UNFORWARDABLE_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `MESSENGER_STATUS_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`protected Vector<Messenger>` `Messengers` List of connected Messenger clients.
`static String` `MESSENGERS_REPORT_ACTION` Messenger management Message Actions and their parameters.
`static int` `MINIMUM_IDENTIFY_TIMEOUT` The minimum Messenger client identify timeout in seconds.
`static String` `NACK_ACTION` Messenger management Message Actions and their parameters.
`static String` `NAME_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `NL` Text new-line sequence.
`static String` `ORIGINAL_MESSAGE_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `PASSWORD_PARAMETER_NAME` The configuration parameter name for the authentication password.
`static String` `PORT_PARAMETER_NAME` The configuration parameter name for the communicaitons port number value.
`protected boolean` `Report_Messenger_Connections` Automatically send connection notifications.
`protected Vector<Messenger>` `Report_to_Messengers` List of Messenger clients that have requested connection notifications.
`static String` `ROUTE_TO_PARAMETER_NAME` Messenger management Message Actions and their parameters.
`static String` `START_MESSENGER_REPORTING_ACTION` Messenger management Message Actions and their parameters.
`static String` `START_STOP_MARKER` Log file marker written when a Dispatcher is started and after it has shutdown.
`static String` `STATUS_REPORT_ACTION` Messenger management Message Actions and their parameters.
`static String` `STDOUT` Log "filename" for logging to stdout.
`static String` `STOP_MESSENGER_REPORTING_ACTION` Messenger management Message Actions and their parameters.
`protected Configuration` `The_Configuration` The Dispatcher Configuration.
`static boolean` `UNAUTHENTICATED_CONNECTIONS_ALLOWED` Controls whether or not annonymous connections are allowed.
`static String` `UNDELIVERABLE_ACTION` Messenger management Message Actions and their parameters.
`static String` `UNLINK_MESSENGER_ACTION` Messenger management Message Actions and their parameters.

### Constructor Summary

Constructors
Constructor and Description
`Dispatcher()` Construct a Dispatcher.
`Dispatcher(Configuration configuration)` Construct a Dispatcher with a configuration.
`Dispatcher(Configuration configuration, int port)` Construct a Dispatcher with a configuration and a specified communication port.
`Dispatcher(String name)` Construct a named Dispatcher.
`Dispatcher(String name, Configuration configuration)` Construct a named Dispatcher with a configuration.
`Dispatcher(String name, Configuration configuration, int port)` Construct a named Dispatcher with a configuration and a specified communication port.

### Method Summary

Methods
`protected boolean` `Authenticate(Message identity)` Authenticate a client identity.
`static Message` `Authentication(Message identify, Message identity)` Provide client identity authentication information.
`protected String` `Config_Pathname(String name)` Get an application specifiic configuration parameter pathname.
`protected void` `Configure(Configuration configuration)` Configures the Dispatcher.
`static String` `Default_Configuration_Source()` Get the default configuration source.
`static String` `Default_Dispatcher_Name()` Get the default Dispatcher name.
`static void` `Default_Dispatcher_Name(String name)` Set the default Dispatcher name.
`static String` `Default_Log_Filename()` Get the default log filename.
`String` `Dispatcher_Name()` Get the Dispatcher name.
`Dispatcher` `Dispatcher_Name(String name)` Set the Dispatcher name.
`String` `Hello_Address()` Get the Dispatcher Hello broadcast multicast address.
`int` `Hello_Port()` Get the Dispatcher Hello broadcast port number.
`int` `Identify_Timeout()` Get the maximum time to wait for a response to a new client identify request.
`Dispatcher` `Identify_Timeout(int seconds)` Set the maximum time to wait for a response to a new client identify request.
`Message` `Identity()` Get the Dispatcher identity.
`protected Dispatcher` `Identity(Message identity)` Set the Dispatcher identity.
`Message` `Listener_Identity()` Get the identity of this Dispatcher.
`String` `Location()` Get the Dispatcher location.
`String` `Log_Pathname()` Get the log file pathname.
`String` `Log_Pathname(String pathname)` Set the pathname to the log file.
`PrintStream` `Log_Stream()` Get the log stream.
`void` `Log_Time(String report)` Writes a log report with a timestamp.
`void` `Log()` Writes an empty log line.
`void` `Log(String report)` Writes a log report.
`boolean` `Logging()` Test if logging is enabled.
`boolean` `Logging(boolean enabled)` Enable or disable logging.
`protected Messenger` `Lookup_Messenger(String address)` Get a Messenger for an address.
`static void` `main(String[] args)`
`void` `Message_Delivered(Message_Delivered_Event event)` Receives delivery of a message.
`Message` `Messenger_Identities(Messenger source_messenger, String name)` Assemble a Message that includes the identities of selected connected Messengers.
`protected void` `Messenger_Link(Messenger source_messenger, Message message)` Link two Messengers for I/O forwarding.
`protected void` `Messenger_Quit(Messenger messenger, Message message)` Disconnect a Messenger.
`protected void` `Messenger_Quit(Messenger messenger, String report)` Disconnect a Messenger.
`protected void` `Messenger_Unlink(Messenger source_messenger, Message message)` Unlink two Messengers.
`protected void` `NACK(Messenger messenger, Message message)`
`int` `Port()` Get the Dispatcher communication port number.
`boolean` `Report_Messenger_Connections()` Test if automatic reporting of the current Messagers list is enabled.
`Dispatcher` `Report_Messenger_Connections(boolean enabled)` Enable or disable automatic reporting of the current Messagers list whenever it changes.
`protected void` `Report_Messengers()` Sends a report of all the `Messenger identities` to each of the Messengers that have `requested connection reports`.
`static Value` `Route_To(Messenger messenger)` Get the Message route-to values for a Messenger.
`protected static Value` `Route(Messenger source_messenger, Messenger client_messenger)`
`Exception` `Run_Exception()` Get any Exception that might have occured when the Dispatcher was used as a `Runnable`.
`void` `run()` Run the connection listener.
`protected boolean` `Send(Messenger messenger, Message message)` Send a Message via a Messenger.
`protected boolean` `Send(Messenger messenger, Message message, boolean report_failure)` Send a Message via a Messenger.
`protected void` `Shutdown()` Shutdown the Dispatcher.
`protected void` `Start_Messenger_Reporting(Messenger messenger)` Start automatic Messenger connection reporting for a Messenger.
`void` `Start()` Start the Dispatcher.
`boolean` `Started()` Tests if this Dispatcher has been started.
`protected void` `Status_Report(Messenger source_messenger, Message message)` Send a status report message.
`protected void` `Stop_Messenger_Reporting(Messenger messenger)` Stop automatic Messenger connection reporting for a Messenger.
`static void` `Usage()`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### ID

    public static final String ID

Class identification name with source code version and date.

See Also:
  Constant Field Values

#### Dispatcher_ID

    protected String Dispatcher_ID

The ID of of the Dispatcher.

It is initialized to the `ID`. Subclasses are expected to set this to their own ID.

#### DEFAULT_DISPATCHER_NAME

    public static final String DEFAULT_DISPATCHER_NAME

The default name of the Dispatcher: "Dispatcher".

See Also:
  Constant Field Values

#### The_Configuration

    protected Configuration The_Configuration

The Dispatcher Configuration.

#### PORT_PARAMETER_NAME

    public static final String PORT_PARAMETER_NAME

The configuration parameter name for the communicaitons port number value.

See Also:
  Constant Field Values

#### IDENTIFY_TIMEOUT_PARAMETER_NAME

    public static final String IDENTIFY_TIMEOUT_PARAMETER_NAME

The configuration parameter name for the maximum wait time, in seconds, for a new Messenger client connection to respond to the identify message.

See Also:
  Constant Field Values

#### PASSWORD_PARAMETER_NAME

    public static final String PASSWORD_PARAMETER_NAME

The configuration parameter name for the authentication password.

See Also:
  Constant Field Values

#### LOG_PATHNAME_PARAMETER_NAME

    public static final String LOG_PATHNAME_PARAMETER_NAME

The configuration parameter name for the log file pathname.

See Also:
  Constant Field Values

#### HELLO_PORT_PARAMETER_NAME

    public static final String HELLO_PORT_PARAMETER_NAME

The configuration parameter name for the Hello port.

See Also:
  Constant Field Values

#### HELLO_ADDRESS_PARAMETER_NAME

    public static final String HELLO_ADDRESS_PARAMETER_NAME

The configuration parameter name for the Hello multicast address.

See Also:
  Constant Field Values

#### HELLO_RATE_PARAMETER_NAME

    public static final String HELLO_RATE_PARAMETER_NAME

The configuration parameter name for the Hello repeat rate (seconds).

See Also:
  Constant Field Values

#### DEFAULT_PORT

    public static final int DEFAULT_PORT

The default communications port number.

See Also:
  Constant Field Values

#### DEFAULT_HELLO_PORT

    public static final int DEFAULT_HELLO_PORT

The default port on which to send the Hello datagram.

See Also:
  Constant Field Values

#### DEFAULT_HELLO_ADDRESS

    public static final String DEFAULT_HELLO_ADDRESS

The default private multicast address to use in the Hello datagram.

See Also:
  Constant Field Values

#### HELLO_MESSAGE

    public static final String HELLO_MESSAGE

The content of the Hello broadcast datagram message.

See Also:
  Constant Field Values

#### DEFAULT_IDENTIFY_TIMEOUT

    public static final int DEFAULT_IDENTIFY_TIMEOUT

The default maximum amount of time, in seconds, to wait for a new Messenger client to respond to an identify message.

See Also:
  Constant Field Values

#### MINIMUM_IDENTIFY_TIMEOUT

    public static final int MINIMUM_IDENTIFY_TIMEOUT

The minimum Messenger client identify timeout in seconds.

See Also:
  `DEFAULT_IDENTIFY_TIMEOUT`, Constant Field Values

#### UNAUTHENTICATED_CONNECTIONS_ALLOWED

    public static final boolean UNAUTHENTICATED_CONNECTIONS_ALLOWED

Controls whether or not annonymous connections are allowed.

See Also:
  Constant Field Values

#### Messengers

    protected Vector<Messenger> Messengers

List of connected Messenger clients.

#### Report_to_Messengers

    protected Vector<Messenger> Report_to_Messengers

List of Messenger clients that have requested connection notifications.

#### Report_Messenger_Connections

    protected volatile boolean Report_Messenger_Connections

Automatically send connection notifications.

#### ACTION_PARAMETER_NAME

    public static final String ACTION_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### IDENTIFY_ACTION

    public static final String IDENTIFY_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### KEY_PARAMETER_NAME

    public static final String KEY_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### IDENTITY_ACTION

    public static final String IDENTITY_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### NAME_PARAMETER_NAME

    public static final String NAME_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### ADDRESS_PARAMETER_NAME

    public static final String ADDRESS_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### ROUTE_TO_PARAMETER_NAME

    public static final String ROUTE_TO_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### CLASS_ID_PARAMETER_NAME

    public static final String CLASS_ID_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MESSENGERS_REPORT_ACTION

    public static final String MESSENGERS_REPORT_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### START_MESSENGER_REPORTING_ACTION

    public static final String START_MESSENGER_REPORTING_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### STOP_MESSENGER_REPORTING_ACTION

    public static final String STOP_MESSENGER_REPORTING_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### LINK_MESSENGER_ACTION

    public static final String LINK_MESSENGER_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### UNLINK_MESSENGER_ACTION

    public static final String UNLINK_MESSENGER_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### STATUS_REPORT_ACTION

    public static final String STATUS_REPORT_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### CONFIGURATION_SOURCE_PARAMETER_NAME

    public static final String CONFIGURATION_SOURCE_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MESSENGER_STATUS_PARAMETER_NAME

    public static final String MESSENGER_STATUS_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MESSAGES_SENT_PARAMETER_NAME

    public static final String MESSAGES_SENT_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MESSAGE_BYTES_SENT_PARAMETER_NAME

    public static final String MESSAGE_BYTES_SENT_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MESSAGES_SENT_DROPPED_PARAMETER_NAME

    public static final String MESSAGES_SENT_DROPPED_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MESSAGES_SENT_CORRUPTED_PARAMETER_NAME

    public static final String MESSAGES_SENT_CORRUPTED_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MESSAGES_RECEIVED_PARAMETER_NAME

    public static final String MESSAGES_RECEIVED_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MESSAGE_BYTES_RECEIVED_PARAMETER_NAME

    public static final String MESSAGE_BYTES_RECEIVED_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MESSAGES_RECEIVED_DROPPED_PARAMETER_NAME

    public static final String MESSAGES_RECEIVED_DROPPED_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MESSAGES_RECEIVED_CORRUPTED_PARAMETER_NAME

    public static final String MESSAGES_RECEIVED_CORRUPTED_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MESSAGES_UNFORWARDABLE_PARAMETER_NAME

    public static final String MESSAGES_UNFORWARDABLE_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MEMORY_STATUS_PARAMETER_NAME

    public static final String MEMORY_STATUS_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MEMORY_AVAILABLE_PARAMETER_NAME

    public static final String MEMORY_AVAILABLE_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MEMORY_ALLOCATED_PARAMETER_NAME

    public static final String MEMORY_ALLOCATED_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### MEMORY_FREE_PARAMETER_NAME

    public static final String MEMORY_FREE_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### UNDELIVERABLE_ACTION

    public static final String UNDELIVERABLE_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### ACK_ACTION

    public static final String ACK_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### NACK_ACTION

    public static final String NACK_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### ORIGINAL_MESSAGE_PARAMETER_NAME

    public static final String ORIGINAL_MESSAGE_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### DONE_ACTION

    public static final String DONE_ACTION

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### EXPLANATION_PARAMETER_NAME

    public static final String EXPLANATION_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### EXCEPTION_PARAMETER_NAME

    public static final String EXCEPTION_PARAMETER_NAME

Messenger management Message Actions and their parameters.

See Also:
  Constant Field Values

#### STDOUT

    public static final String STDOUT

Log "filename" for logging to stdout.

See Also:
  `Log_Pathname(String)`, Constant Field Values

#### Log_Stream

    protected PrintStream Log_Stream

Log output stream.

#### DATE_FORMATTING

    public static final String DATE_FORMATTING

Formatting pattern for log message timestamps.

See Also:
  `DATE_FORMAT`, Constant Field Values

#### DATE_FORMAT

    public static final SimpleDateFormat DATE_FORMAT

Format for log message timestamps.

See Also:
  `DATE_FORMATTING`

#### START_STOP_MARKER

    public static final String START_STOP_MARKER

Log file marker written when a Dispatcher is started and after it has shutdown.

See Also:
  Constant Field Values

#### NL

    public static final String NL

Text new-line sequence.

#### EXIT_SUCCESS

    public static final int EXIT_SUCCESS

Success exit status.

See Also:
  Constant Field Values

#### EXIT_COMMAND_LINE_SYNTAX

    public static final int EXIT_COMMAND_LINE_SYNTAX

Command line syntax problem exit status.

See Also:
  Constant Field Values

#### EXIT_CONFIG_FILE_PROBLEM

    public static final int EXIT_CONFIG_FILE_PROBLEM

The log file could not be opened for writing exit status.

See Also:
  Constant Field Values

#### EXIT_NO_LOG_FILE

    public static final int EXIT_NO_LOG_FILE

The log file could not be opened for writing exit status.

See Also:
  Constant Field Values

#### EXIT_IO_ERROR

    public static final int EXIT_IO_ERROR

IOException failure exit status.

See Also:
  Constant Field Values

#### EXIT_SECURITY_VIOLATION

    public static final int EXIT_SECURITY_VIOLATION

SecurityException exit status.

See Also:
  Constant Field Values

#### EXIT_UNKNOWN_EXCEPTION

    public static final int EXIT_UNKNOWN_EXCEPTION

Unknown exception (possible programming flaw).

See Also:
  Constant Field Values

### Constructor Detail

#### Dispatcher

    public Dispatcher(String name,
              Configuration configuration,
              int port)

Construct a named Dispatcher with a configuration and a specified communication port.

<b.N.B.: Constructing a Dispatcher does not `start` it operating.

Parameters:
  `name` - The `Dispatcher name`.
  `configuration` - The Configuration to use to `configure` the Dispatcher when it is `started`.
  `port` - The communications port number. If less than or equal to zero the value of the configuration `PORT_PARAMETER_NAME` parameter will be used, or the `DEFAULT_PORT` if no configuration parameter is found.

#### Dispatcher

    public Dispatcher(Configuration configuration,
              int port)

Construct a Dispatcher with a configuration and a specified communication port.

The `Dispatcher name` will be the `DEFAULT_DISPATCHER_NAME`.

<b.N.B.: Constructing a Dispatcher does not `start` it operating.

Parameters:
  `configuration` - The Configuration to use to `configure` the Dispatcher when it is `started`.
  `port` - The communications port number. If less than or equal to zero the value of the configuration `PORT_PARAMETER_NAME` parameter will be used, or the `DEFAULT_PORT` if no configuration parameter is found.

#### Dispatcher

    public Dispatcher(String name,
              Configuration configuration)

Construct a named Dispatcher with a configuration.

The communication port number will be obtained from the configuration `PORT_PARAMETER_NAME` parameter, or the `DEFAULT_PORT` will be used if no configuration parameter is found.

<b.N.B.: Constructing a Dispatcher does not `start` it operating.

Parameters:
  `name` - The `Dispatcher name`.
  `configuration` - The Configuration to use to `configure` the Dispatcher when it is `started`.

#### Dispatcher

    public Dispatcher(Configuration configuration)

Construct a Dispatcher with a configuration.

<b.N.B.: Constructing a Dispatcher does not `start` it operating.

The `Dispatcher name` will be the `DEFAULT_DISPATCHER_NAME`.

The communication port number will be obtained from the configuration `PORT_PARAMETER_NAME` parameter, or the `DEFAULT_PORT` will be used if no configuration parameter is found.

Parameters:
  `configuration` - The Configuration to use to `configure` the Dispatcher when it is `started`.

#### Dispatcher

    public Dispatcher(String name)

Construct a named Dispatcher.

<b.N.B.: Constructing a Dispatcher does not `start` it operating.

When the Dispatcher is `configured` a default configuration source will be sought.

The communication port number will be obtained from the configuration `PORT_PARAMETER_NAME` parameter, or the `DEFAULT_PORT` will be used if no configuration parameter is found.

Parameters:
  `name` - The `Dispatcher name`.

#### Dispatcher

    public Dispatcher()

Construct a Dispatcher.

<b.N.B.: Constructing a Dispatcher does not `start` it operating.

The `Dispatcher name` will be the `DEFAULT_DISPATCHER_NAME`.

When the Dispatcher is `configured` a default configuration source will be sought.

The communication port number will be obtained from the configuration `PORT_PARAMETER_NAME` parameter, or the `DEFAULT_PORT` will be used if no configuration parameter is found.

### Method Detail

#### Default_Dispatcher_Name

    public static String Default_Dispatcher_Name()

Get the default Dispatcher name.

Returns:
  The default Dispatcher name.
See Also:
  `Default_Dispatcher_Name(String)`

#### Default_Dispatcher_Name

    public static void Default_Dispatcher_Name(String name)

Set the default Dispatcher name.

Parameters:
  `name` - The default Dispatcher name. If null, the `DEFAULT_DISPATCHER_NAME` is used.

#### Dispatcher_Name

    public String Dispatcher_Name()

Get the Dispatcher name.

Returns:
  The Dispatcher name.
See Also:
  `Dispatcher_Name(String)`

#### Dispatcher_Name

    public Dispatcher Dispatcher_Name(String name)

Set the Dispatcher name.

The `NAME_PARAMETER_NAME` in the Dispatcher `identity` is set to the Dispatcher name.

Parameters:
  `name` - The Dispatcher name. If null, the `default Dispatcher name` is used.
Returns:
  This Dispatcher.

#### Port

    public int Port()

Get the Dispatcher communication port number.

Returns:
  The communication port number for this Dispatcher.

#### Hello_Port

    public int Hello_Port()

Get the Dispatcher Hello broadcast port number.

Returns:
  The Hello broadcast port number for this Dispatcher.

#### Hello_Address

    public String Hello_Address()

Get the Dispatcher Hello broadcast multicast address.

Returns:
  The Hello broadcast multicast address String for this Dispatcher.

#### Location

    public String Location()

Get the Dispatcher location.

The format of the location string is:

host[:port]

The host may be a hostname or IP address. The hostname is `fully qualified`. The communications `port number` is appended after a colon (':') delimiter.

Returns:
  A String specifying the location of this Dispatcher.

#### Identity

    public Message Identity()

Get the Dispatcher identity.

Returns:
  A Message containing the Dispatcher identification information. This will be null if, and only if, the identity Message could not be assembled.
See Also:
  `Identity(Message)`

#### Identity

    protected Dispatcher Identity(Message identity)
                           throws PVL_Exception

Set the Dispatcher identity.

The following parameters will always be set in the identity Message:

`ACTION_PARAMETER_NAME`
  Set to `IDENTITY_ACTION`.
`NAME_PARAMETER_NAME`
  Set to the `Dispatcher name`.
`CLASS_ID_PARAMETER_NAME`
  Set to the `Dispatcher_ID`.
`Configuration.HOST`
  Set to the `Host.FULL_HOSTNAME`.
`Configuration.USER`
  Set to the account name under which the Dispatcher is running.

Parameters:
  `identity` - A Message containing the Dispatcher identification information. If null an empty Message is provided before setting the required parameters.
Returns:
  This Dispatcher.
Throws:
  `PVL_Exception` - if the identity Message can not be assembled either because the specified identity Message can not be copied or the required parameters can not be set.

#### Identify_Timeout

    public int Identify_Timeout()

Get the maximum time to wait for a response to a new client identify request.

Returns:
  The identify reponse timeout (seconds).
See Also:
  `Identify_Timeout(int)`

#### Identify_Timeout

    public Dispatcher Identify_Timeout(int seconds)

Set the maximum time to wait for a response to a new client identify request.

If a new client connection does not respond to the identity request before the timeout expires the client connection is dropped.

Parameters:
  `seconds` - The identify reponse timeout (seconds). If less than or equal to zero the DEFAULT_IDENTIFY_TIMEOUT will be used.
Returns:
  This Dispatcher.
See Also:
  `Identify_Timeout(int)`

#### Report_Messenger_Connections

    public Dispatcher Report_Messenger_Connections(boolean enabled)

Enable or disable automatic reporting of the current Messagers list whenever it changes.

Whenever a client connects or disconnects a report is sent to all Messengers that have `requested connection reports` that provides the identities of all Messengers in the modified list of connected Messagers. For Message protocol operations that may generate a flurry of connection events it can be desirable to suspend automatic connection event reporting until after the protocol operation has been completed. This can significantly reduce the amount of connection list change processing that clients are required to manage.

Parameters:
  `enabled` - If true whenever the list of connected Messagers changes it will be reported to all Messengers that have requested connection reports; if false reports will only be provided on demand.
Returns:
  This Dispatcher.
See Also:
  `Report_Messengers()`

#### Report_Messenger_Connections

    public boolean Report_Messenger_Connections()

Test if automatic reporting of the current Messagers list is enabled.

Returns:
  true if automatic reporting of the current Messagers list is enabled; false otherwise.
See Also:
  `Report_Messenger_Connections(boolean)`

#### Run_Exception

    public Exception Run_Exception()

Get any Exception that might have occured when the Dispatcher was used as a `Runnable`.

When used as a Runnable the Dispatcher connection listener must first be `started`. If this throws an exception it is held since it can not be thrown from a Runnable.

Returns:
  The Exception that was thrown when the Dispatcher connection listener was `started` as a result of `running` the Dispatcher. This will be null if no exception was thrown.

#### Default_Configuration_Source

    public static String Default_Configuration_Source()

Get the default configuration source.

The default configuration source is tried if no Configuration is supplied to `configure` the Dispatcher and a configuration source based on the `Dispatcher name` can not be found.

Returns:
  The name of the default source file. This is the `default Dispatcher name` plus the ".conf" extension.

#### Configure

    protected void Configure(Configuration configuration)
                      throws Configuration_Exception,
                             SecurityException

Configures the Dispatcher.

If no Configuration is provided a search will be made for a default configuration source. The `Dispatcher name` plus the ".conf" extension will be tried first. If this fails, the `default configuration source` will be tried.

The Configuration is set to be `case insensitive` before parameters are sought.

Configuration parameters that may be used:

`PORT_PARAMETER_NAME`
  If the communications port number was not set when the Dispatcher was constructed the value of this parameter will be used. The default value is `DEFAULT_PORT`.
`IDENTIFY_TIMEOUT_PARAMETER_NAME`
  The number of seconds to wait for a Messenger client connection to respond to the identify message it is sent. The default value is `DEFAULT_IDENTIFY_TIMEOUT`; the minium value is `MINIMUM_IDENTIFY_TIMEOUT`.
`PASSWORD_PARAMETER_NAME`
  The Messenger client authentication password. N.B.: If no password is provided, or it is emtpy, and `UNAUTHENTICATED_CONNECTIONS_ALLOWED` is true unauthenticated connections will be allowed.
`LOG_PATHNAME_PARAMETER_NAME`
  If `logging` has not been enabled, and a log pathname is found, the pathname is used to set the `log file` and logging is then enabled. N.B.: A configuration log pathname will not override an application set log file if logging has been enabled by the application.
`HELLO_PORT_PARAMETER_NAME`
  After the Dispatcher starts and is ready to receive connections it will broadcast a `HELLO_MESSAGE` on this port to notify any clients that may listening that they may open a connection. If the port number is zero no Hello broadcast will be sent. `DEFAULT_HELLO_PORT` is the default port number. If the port number is not positive no broadcast will be done.
`HELLO_ADDRESS_PARAMETER_NAME`
  This address is expected to be a private multicast address suitable for use in broadcasting the Hello message. The time-to-live of datagrams that are sent is zero to keep them on the local system. `DEFAULT_HELLO_ADDRESS` is the default multicast address. If the address is empty no broadcast will be done.

N.B.: All parameters are sought in the `in the Configuration Group` with the `Dispatcher name`.

Parameters:
  `configuration` - The Configuration to use. If null and defatult configuration source will sought.
Throws:
  `Configuration_Exception` - If there was a problem parsing the configuration source, accessing its contents, or establishing a log file.
  `SecurityException` - If the connection authentication keys could not be generated, no `PASSWORD_PARAMETER_NAME` was found but `UNAUTHENTICATED_CONNECTIONS_ALLOWED` is false, or a log file could not be opened due to a security violation.

#### Config_Pathname

    protected String Config_Pathname(String name)

Get an application specifiic configuration parameter pathname.

If the specified name is null or an `absolute pathname` it is returned unmodified. Otherwise the name is added to the absolute pathname of the `Dispatcher name` Group.

Parameters:
  `name` - A parameter name. May be null.
Returns:
  An absolute Configuration parameter pathname (or null if the name is null).

#### Default_Log_Filename

    public static String Default_Log_Filename()

Get the default log filename.

Returns:
  The default log filename. This will be the `default Dispatcher name` plus the ".log" extension.

#### Log_Pathname

    public String Log_Pathname()

Get the log file pathname.

Returns:
  The log file pathname. This will be the last `log pathname` that was set, or the `default log filename` if a log pathname has not been set.

#### Log_Pathname

    public String Log_Pathname(String pathname)
                        throws FileNotFoundException

Set the pathname to the log file.

If a `log stream` is already open it is flushed. If it is not the stdout, it is closed.

If the pathname is `STDOUT` the log stream is set to the `stdout` stream. Otherwise the pathname is checked for an existing file. N.B.: An existing file is appended. If the file does not exist an attempt is made to create it. The `log stream` is put in auto-flush mode.

Parameters:
  `pathname` - The pathname to the log file. If null or the empty String the `default log filename` will be used.
Returns:
  A String that reports how the log file was established.
Throws:
  `FileNotFoundException` - If an existing file could not be appended, possibly because it is not a regular file, or the file could not be created for writing.
See Also:
  `Log_Stream()`

#### Log_Stream

    public PrintStream Log_Stream()

Get the log stream.

Returns:
  The PrintStream where logging will be written. This will be null if no `log file` has been established.
See Also:
  `Log_Pathname(String)`

#### Logging

    public boolean Logging()

Test if logging is enabled.

Returns:
  true if logging is enabled; false otherwise.
See Also:
  `Logging(boolean)`

#### Logging

    public boolean Logging(boolean enabled)

Enable or disable logging.

If logging is being enabled from a disabled state, and no `log stream` is open, the current `log pathname` is used to open a log stream.

If logging is being disabled from an enabled state the log stream is flushed but the log stream remains open.

N.B.: Logging may be enabled and disabled while the Dispatcher is in operation.

Parameters:
  `enabled` - true if logging is to be enabled; false otherwise.
Returns:
  true if logging was enabled; false otherwise.

#### Log_Time

    public void Log_Time(String report)

Writes a log report with a timestamp.

If logging is disabled nothing is done.

The current date and time is written using the `DATE_FORMAT` on a line by itself. This is followed by the report text. If the report text is null a single empty line is written.

Parameters:
  `report` - The report text to be logged. If null a single empty line is written.
See Also:
  `Logging(boolean)`, `Log_Pathname(String)`

#### Log

    public void Log(String report)

Writes a log report.

If logging is disabled nothing is done.

Parameters:
  `report` - The report text to be logged. If null a single empty line is written.
See Also:
  `Logging(boolean)`, `Log_Pathname(String)`

#### Log

    public void Log()

Writes an empty log line.

See Also:
  `Log(String)`

#### Start

    public void Start()
               throws Configuration_Exception,
                      SecurityException,
                      IOException

Start the Dispatcher.

If the Dispatcher has already been started nothing is done.

The Dispatcher is first `configured`.

If `logging` has been enabled a startup message is logged.

Then the communications socket is established.

The connection listener is then `run` which listens for and handles Messenger client connections.

N.B.: Once the Dispatcher is started it will continue to run until interrupted, a fatal exception occurs, or the JVM exits.

Throws:
  `Configuration_Exception` - If there was a problem configuring the Dispatcher.
  `SecurityException` - If, during configuration, the connection authentication keys could not be generated, no `PASSWORD_PARAMETER_NAME` was found but `UNAUTHENTICATED_CONNECTIONS_ALLOWED` is false, or a log file could not be opened due to a security violation. This exception will also be thrown if a security violation was encountered while establishing the communication channel.
  `IOException` - If there was a problem while establishing the communication channel.

#### Started

    public boolean Started()

Tests if this Dispatcher has been started.

Returns:
  true If this Dispatcher has started its connection listener; false otherwise.
See Also:
  `Start()`

#### run

    public void run()

Run the connection listener.

N.B.: A check is first made that the Dispatcher connection listener has been `started` and, if it has not, it is told to `start`. This enables the Dispatcher to be used a Thread Runnable. However, starting the connection listener causes an exception to be thrown the Runnable will not run. In this case the `() run exception` must be specifically retrieved.

While the listener socket that was bound when the Dispatcher was constructed is open the thread continually listens for new connections. Each connection is a potential new client. Each connection is allocated a new Messenger that uses the socket as its communication channel and this Dispatcher as its `employer`.

Each client must complete a protocol handshake:

`Identify`
  The handshake is intiated by the Dispatcher `sending` the client via the new Messenger an Identify request Message. This Message contains an `Action` parameter with the `Identify` value. If authentication is required or the Dispatcher has been configured with password a `Key` parameter will also be included that has an encoded public key value.
`Authentication`
  The client on receiving the Identify request Message must use the public key it provides to generate authentication information that will be included with its other Identity information. This is done by setting the `Key` parameter in a copy of its usual Identity Message to the required password value and then passing both the Identify and Identity Messages to the Authentication utility which will replace the password value of the Identity Key parameter with an encrypted and encoded value created using the public key from the Identify Message. If client authentication is not required no authentication information needs to be provided. The Identity Message is sent by the client in response to the Identify Message.
`Identity`
  The Dispatcher expects to `receive` an Identity Message in response to its Identify request within the `timeout` period or the Messenger will be told that it is `done` which will drop the connenction. The identity Message and its route-from addressing is `logged`.
`Authenticate`
  The client's Identity Message is used for authentication. If `UNAUTHENTICATED_CONNECTIONS_ALLOWED` is true and the Dispatcher has not been `configured` with a password then client Identity authentication always succeeds. When password authentication is required for the Identity authentication to succeed the Identity Message must include a `KEY_PARAMETER_NAME` parameter with a value that can be decoded and decrypted using the Dispatcher's private key to produce a password value that is identical to the one with which it has been configured.
Conclusion
  If authentication of the client's Identity Message succeeded the Dispatcher will conclude the handshake by sending its own `Identity` Message to the client. If authentication failed a `NACK` Message will be sent containing the client's Identity without any Key parameter plus an `Explanation` parameter saying that the Identity did not authenticate.

If any part of the handshake fails the Messenger is told that it is `done` which closes down the Messenger and closes its connection.

After conclusion of the protcol handshake the route-to address list of the identity Message is set to its route-from list and the Message is bound the Messenger as its (@link Messenger#Identity(Message) identity}. The Messenger is added to the list of connected Messengers and is told to asynchronously listen for Messages. Then the list of `Report_to_Messengers` are sent a Message that includes the `identities of the connected Messengers`.

Each connection step is logged.

Specified by:
  `run` in interface `Runnable`
See Also:
  `SocketChannel`

#### Messenger_Quit

    protected void Messenger_Quit(Messenger messenger,
                      String report)

Disconnect a Messenger.

The messenger is removed from the list of connected Messengers and the list of Messengers to receive reports of connected Messengers. If the Messenger was removed from the connected list, the disconnection is logged with the Messenger details and the report (if non-null), and the Messenger is told that it is `done` in case it has not already initiated its communication shutdown procedures.

When the Messengers list is empty the shutdown-in-progress flag, that may have been set in the `shutdown` procedure, is reset.

Parameters:
  `messenger` - The Messenger to be disconnected.
  `report` - A report to be logged. May be null.

#### Messenger_Quit

    protected void Messenger_Quit(Messenger messenger,
                      Message message)

Disconnect a Messenger.

If a message is specified and it contains an `EXPLANATION_PARAMETER_NAME` and/or an `EXCEPTION_PARAMETER_NAME` the values of those parameters are assembled into report to be included in the log. If there are any additional parameters, other than the `ACTION_PARAMETER_NAME`, a description of all remaining parameters are also included in the log report.

Parameters:
  `messenger` - The Messenger to be disconnected.
  `message` - A Message to be logged. May be null.
See Also:
  `Messenger_Quit(Messenger, String)`

#### Shutdown

    protected void Shutdown()

Shutdown the Dispatcher.

The communications channel is closed. If there are any registered Messengers they are told they are `Done` and a shutdown-in-progress flag is set. This flag is checked up to five times with a two second delay between checks until either the flag is found to be reset or the maximum number of checks have been done. Finally a shutdown notice is logged that indicates whether the shutdown of all the Messegers was completed.

#### Lookup_Messenger

    protected Messenger Lookup_Messenger(String address)

Get a Messenger for an address.

The list of connected Messengers is searched for one that has an `address` that matches the one that is specified.

Parameters:
  `address` - The address String associated with a Messenger. If null or the empty String null is returned.
Returns:
  The connected Messenger having the specified address, or null if no Messenger with that address was found.

#### Authentication

    public static Message Authentication(Message identify,
                         Message identity)

Provide client identity authentication information.

During the handshake protocol, while establishing a conneciton to a Dispatcher, authentication information will need to be exchanged unless `UNAUTHENTICATED_CONNECTIONS_ALLOWED`. In the `IDENTIFY_ACTION` Message that the Dispatcher sends to initiate the handshake for a new client connection a `KEY_PARAMETER_NAME` parameter will provide a public key value that must be used to produce an encoded password value returned in the `KEY_PARAMETER_NAME` parameter of the required `IDENTITY_ACTION` Message response.

The authentication key in the Identify Message is used with the authentication key in the Identity Message to produce an encoded authentication key in the Identity Message. If either the Identify or Identity Message do not have an authentication key then the returned Message will not have this parameter. The mechanism by which the Identify key is used to encode the Identity key is opaque.

N.B.: The Identity Message that is provided is modified, not copied.

Parameters:
  `identify` - A Message from which to obtain a `KEY_PARAMETER_NAME` parameter with a public key authentication value. If null the identity Message is returned with any `KEY_PARAMETER_NAME` parameter removed.
  `identity` - A Message from which to obtain a `KEY_PARAMETER_NAME` parameter with a private password authentication value. The value is replaced with encoded authentication information that combines the public key with the password. If null null is returned.
Returns:
  The possibly modified identity Message. This will have a modified `KEY_PARAMETER_NAME` parameter if, and only if, the original value was successfully encoded into the appropriate authentication response value.
See Also:
  `Authentication`

#### Authenticate

    protected boolean Authenticate(Message identity)

Authenticate a client identity.

If no password was obtained from the `configuration` and `UNAUTHENTICATED_CONNECTIONS_ALLOWED` is true, the identity is accepted without further authentication.

Authentication requires that the identity contain a `KEY_PARAMETER_NAME` parameter value that is used as the `encoded authentication password` to `authenticate` the client identity. The decoded authentication password from the identity, after being decrypted using the Dispatcher's private key, must match the Dispatcher password.

Returns:
  true if the identity is authenticated or unauthenticated connections are allowed. false if the Dispatcher does not have a password and unauthenticated connections are not allowed, the identity does not contain a Key parameter, or its decoded and decrypted value does not match the password.
See Also:
  `Authentication`

#### Listener_Identity

    public Message Listener_Identity()

Get the identity of this Dispatcher.

This method implements the `Message_Delivered_Listener` interface.

Specified by:
  `Listener_Identity` in interface `Message_Delivered_Listener`
Returns:
  A Message containing the Dispatcher `identity` information.
See Also:
  `Identity()`

#### Message_Delivered

    public void Message_Delivered(Message_Delivered_Event event)

Receives delivery of a message.

This method implements the `Message_Delivered_Listener` interface.

The following `message actions` are recognized:

`IDENTIFY_ACTION`
  Replies with the `identity Message`.
`MESSENGERS_REPORT_ACTION`
  Replies with a list of `currently connected messenger identities` that have been selected by the request message.
`START_MESSENGER_REPORTING_ACTION`
  `Starts connected Messenger reporting` for the requesting Messenger.
`STOP_MESSENGER_REPORTING_ACTION`
  `Stops connected Messenger reporting` for the requesting Messenger.
`LINK_MESSENGER_ACTION`
  Direct `Messenger_Link(Messenger, Message)` Messenger-to-Messenger communication} is established between the requesting Messenger and another Messenger for which an address is provided.
`UNLINK_MESSENGER_ACTION`
  Direct `Messenger_Unlink(Messenger, Message)` Messenger-to-Messenger communication} is removed between the requesting Messenger and another Messenger for which an address is provided.
`DONE_ACTION`
  The Messenger associated with this Message has `quit` and is to be disconnected.
`UNDELIVERABLE_ACTION`
  A Message that was `sent` could not be delivered. The undeliverable Message is logged.
`NACK_ACTION`
  A Message that was `sent` was rejected. The rejected Message is logged.

Any other messages are logged as unrecognized and a `NACK` is sent back to the Messenger from which the message was received.

Specified by:
  `Message_Delivered` in interface `Message_Delivered_Listener`
Parameters:
  `event` - The `Message_Delivered_Event` containing the Message that was delivered and a reference to the Messenger that sent it.

#### Send

    protected boolean Send(Messenger messenger,
               Message message,
               boolean report_failure)

Send a Message via a Messenger.

If failure reporting is enabled and the Messenger throws an exception while sending the Message this is logged with the Messenger description, the Message routing addresses, the Message description and the exception description. In any case if the exception is an IOException the Messenger is `quit`.

Parameters:
  `messenger` - The Messenger used to send the Message. If null nothing is done.
  `message` - The Message to be sent. If null nothing is done.
  `report_failure` - true if failure reporting is enabled; false otherwise.
Returns:
  true if the Message was successfully sent; false otherwise.

#### Send

    protected boolean Send(Messenger messenger,
               Message message)

Send a Message via a Messenger.

The Message is `sent` with failure reporting enabled.

Parameters:
  `messenger` - The Messenger used to send the Message. If null nothing is done.
  `message` - The Message to be sent. If null nothing is done.
Returns:
  true if the Message was successfully sent; false otherwise.
See Also:
  `Send(Messenger, Message, boolean)`

#### Messenger_Identities

    public Message Messenger_Identities(Messenger source_messenger,
                               String name)

Assemble a Message that includes the identities of selected connected Messengers.

A connected Messenger is the client Messenger that initiated a connection, completed the identification Message handshake with the Dispatcher Messenger allocated to the client, and that is currently active (in the Messengers). Connected Messengers may be selected by `NAME_PARAMETER_NAME` value. If no name is specified all connected Messengers are selected. However, the source Messenger to whom the Message will be sent is never selected.

The assembled Message includes an `IDENTITY_ACTION` group for each selected Messenger. The parameters in this group are the `identity` Message parameters bound to the Messenger. In addition, a `ROUTE_TO_PARAMETER_NAME` is added to each identity that is an array of Messenger `addresses` for each Messenger on the route from the source Messenger to the connected Messenger. The Value of this parameter can be used to set the `route-to list` of a Message to be sent from the source Messenger to the destination connected Messenger.

Since the route-to list of each connected Messenger `identity Message` is in Dispatcher-to-client order the route-to list of the source Messenger must be reversed to produce a correct route-to address list in source-to-client order. This reversed address list is then completed with the route-to list of the client Messenger being identified. N.B.: Message route-to address lists are in LIFO order: the last address of the list is for the first Messenger on the transmission route, and the first address is for the destination client Messenger.

Parameters:
  `source_messenger` - The Messenger to whom the returned Message is intended. Route-to address lists for each identified Messenger will be relative to this Messenger. If null, or the Messenger has no `identity`, or the identity has no `() route-to list` the returned Message will only contain an `EXPLANATION_PARAMETER_NAME` parameter with a brief message value describing the problem.
  `name` - The `NAME_PARAMETER_NAME` value used to select connected Messengers. If null, all Messengers will be selected. The source_messenger is never selected.
Returns:
  A Message containing the identity and route-to address list of each selected Messenger. However, if source_messenger is null, has no identity, or the identity has no route-to list the Message will only contain an `EXPLANATION_PARAMETER_NAME` parameter with a brief message value describing the problem.

#### Report_Messengers

    protected void Report_Messengers()

Sends a report of all the `Messenger identities` to each of the Messengers that have `requested connection reports`.

#### Start_Messenger_Reporting

    protected void Start_Messenger_Reporting(Messenger messenger)

Start automatic Messenger connection reporting for a Messenger.

The specified Messenger is added, if it is not already present, to the list of Messengers that will be sent the list of all connected `Messenger identities` whenever a new Messenger connects or disconnects.

The Messenger is sent the current connected Messengers list.

Parameters:
  `messenger` - The Messenger to receive automatic Messenger connection reporting. If null, nothing is done.
See Also:
  `Stop_Messenger_Reporting(Messenger)`

#### Stop_Messenger_Reporting

    protected void Stop_Messenger_Reporting(Messenger messenger)

Stop automatic Messenger connection reporting for a Messenger.

The specified Messenger is removed, if it is present, from the list of Messengers that will be sent the list of all connected `Messenger identities`.

Parameters:
  `messenger` - The Messenger to receive automatic Messenger connection reporting. If null, nothing is done.
See Also:
  `Start_Messenger_Reporting(Messenger)`

#### Messenger_Link

    protected void Messenger_Link(Messenger source_messenger,
                      Message message)

Link two Messengers for I/O forwarding.

The specified Message must contain an `ADDRESS_PARAMETER_NAME` value that specifies the address of `known Messenger` to which the source Messenger is to be linked. The linked Messenger is `added to the forwarding list` of the source Messenger and the source Messenger is added to the forwarding list of the linked Messenger.

The specified Message is returned to the source Messenger with the addition of an `ACK_ACTION` token and an `IDENTITY_ACTION` group containing the `identity` of the linked Messenger.

If a Messenger with the address to link to is not known the reply Message contains a `NACK_ACTION` token and an `EXPLANATION_PARAMETER_NAME`, instead of a Messenger identity, that describes the reason that the link could not be done.

N.B.: If the Message contains either an `ACK_ACTION` or `NACK_ACTION` token nothing is done.

Parameters:
  `source_messenger` - The source Messenger that is initiating the Messenger link. If null nothing is done.
  `message` - The Message contain the address of the Messenger to be linked. If null nothing is done.
See Also:
  `Messenger_Unlink(Messenger, Message)`

#### Messenger_Unlink

    protected void Messenger_Unlink(Messenger source_messenger,
                        Message message)

Unlink two Messengers.

The specified Message must contain an `ADDRESS_PARAMETER_NAME` value that specifies the address of `known Messenger` from which the source Messenger is to be unlinked. The linked Messenger is `removed from the forwarding list` of the source Messenger and the source Messenger is removed from the forwarding list of the linked Messenger.

N.B.: No reply is sent to the source Messenger.

Parameters:
  `source_messenger` - The source Messenger that is initiating the Messenger link. If null nothing is done.
  `message` - The Message contain the address of the Messenger to be linked. If null nothing is done.
See Also:
  `Messenger_Link(Messenger, Message)`

#### Route

    protected static Value Route(Messenger source_messenger,
              Messenger client_messenger)

#### Route_To

    public static Value Route_To(Messenger messenger)

Get the Message route-to values for a Messenger.

The route_to values specify the `Message routing addresses` used by a Messenger when a Message is `sent`.

Parameters:
  `messenger` - A Messenger for which to get the Message route-to address values
Returns:
  An Array Value containing the route-to address String Values.

#### Status_Report

    protected void Status_Report(Messenger source_messenger,
                     Message message)

Send a status report message.

The status report contains the Dispatcher `identity` plus its communications `IDENTIFY_TIMEOUT_PARAMETER_NAME`, `PORT_PARAMETER_NAME`, #HELLO_PORT_PARAMETER_NAME} and `HELLO_ADDRESS_PARAMETER_NAME` parameters.

The Dispatcher identification is followed by a `MESSENGER_STATUS_PARAMETER_NAME` group containing each connected Messenger's `identity` with the identities of each of its `forwarding Messengers` and its Message statistics:

- `MESSAGES_SENT_PARAMETER_NAME` from `Messenger.Messages_Sent()`
- `MESSAGE_BYTES_SENT_PARAMETER_NAME` from `Messenger.Message_Bytes_Sent()`
- `MESSAGES_SENT_DROPPED_PARAMETER_NAME` from `Messenger.Messages_Sent_Dropped()`
- `MESSAGES_SENT_CORRUPTED_PARAMETER_NAME` from `Messenger.Messages_Sent_Corrupted()`
- `MESSAGES_RECEIVED_PARAMETER_NAME` from `Messenger.Messages_Received()`
- `MESSAGE_BYTES_RECEIVED_PARAMETER_NAME` from `Messenger.Message_Bytes_Received()`
- `MESSAGES_RECEIVED_DROPPED_PARAMETER_NAME` from `Messenger.Messages_Received_Dropped()`
- `MESSAGES_RECEIVED_CORRUPTED_PARAMETER_NAME` from `Messenger.Messages_Received_Corrupted()`
- `MESSAGES_UNFORWARDABLE_PARAMETER_NAME` from `Messenger.Messages_Unforwardable()`

Each Messenger that registered an `error condition` will also have an `EXCEPTION_PARAMETER_NAME` describing the exception following the Message statistics.

Following the Messenger identities a `MEMORY_STATUS_PARAMETER_NAME` group contains memory use parameters:

- `MEMORY_AVAILABLE_PARAMETER_NAME` - the maximum amount of memory available to the Java Runtime Environment.
- `MEMORY_ALLOCATED_PARAMETER_NAME` - the amount of memory currently allocated by the application.
- `MEMORY_FREE_PARAMETER_NAME` - the amount of allocated memory currently unused.

Parameters:
  `source_messenger` - The Messagner to use to send the status report Message.
  `message` - The Message to `reply to`.

#### NACK

    protected void NACK(Messenger messenger,
            Message message)

#### main

    public static void main(String[] args)

#### Usage

    public static void Usage()