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.

Version:

1.37

Author:

Bradford Castalia - UA/PIRL

See Also:

Messenger

Field Summary

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

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

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.

: 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.

: 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.

: 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.

: 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.

: 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.

: 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()