# Package PIRL.Messenger

The Messenger package provides an interprocess messaging service.

See: Description

Interface Summary
Interface | Description
--- | ---
Message_Delivered_Listener | A Message_Delivered_Listener defines the interface used to deliver a Message_Delivered_Event.

Class Summary
Class | Description
--- | ---
Dispatcher | A Dispatcher is a Messenger manager for communication between client processes.
Message | A Message contains a message and its routing information.
Message_Delivered_Event | A Message_Delivered_Event is used to notify a Messenger employer that a message was delivered needing attention.
Messenger | A Messenger sends and receives Messages over a communication channel and routes received messages to their destination.
Messenger_Styled_Writer | A Messenger_Styled_Writer is a Writer that encapsulates what is written, along with Styled_Writer information, into a Message that is sent via a Messenger.

## Package PIRL.Messenger Description

The Messenger package provides an interprocess messaging service.

A Message contains routing information for the message content. The content is defined in terms of an Aggregate of `Parameters` having names and `Values` suitable for the protocol being employed. A set of basic parameter names and corresponding Message generators is provided for use by a typical protocol. In addition to the base Parameter class methods for manipulating the content, a set of methods to simplify Message routing and content management and access are provided. The content can be represented in transmittable standard PVL syntax packet form in a ByteBuffer. The packet will contain a label with the message routing information and message start synchronization pattern that provides for message stream unit recovery in an unreliable transmission medium. The routing information is route-from and route-to address String lists (Array Values) which may be used as desired by the transmission agent.

A Messenger is a transmission agent for Message objects. A Messenger provides Message transmission and synchronous or asynchronous Message receiving capabilities over a blocking SocketChannel. The SocketChannel may be provided when the Messenger is constructed or by the Messenger if an InetSocketAddress or hostname (or IP address) and network port number is provided. Messengers are expected (but not required) to work in pairs with the "client" side Messenger being constructed on a new SocketChannel connected to a SocketAddress representing the server side address (typically this is done by just constructing a Messenger using a hostname and port number), and the "server" side Messenger being constructed on a SocketChannel accepted from a network connection of a client to a ServerSocketChannel. A Messenger manages Message packetization and transmission on the SocketChannel and reading the SocketChannel for message packets (including synchronization and optional timeout) and Message reconstruction. Asynchronous Message receiving is done in a Message listener Thread, provided by the Messenger, that is started and stopped by the user. The Message listener Thread handles reading the Message stream - using the same mechanism employed by synchronous Message receipt - and routing.

Each Messenger has a unique address - composed of its host system IP address, port number and start time (milliseconds) - that is used in the Message routing address lists. When a Message is sent the address of the Messenger is added to the route-from list. When a Message packet is received the Messenger's address is removed from the end of the route-to list. During asynchronous packet receipt processing if another address remains on the route-to list and it matches the address of one of the forwarding Messengers registered with the Messenger the packet that was read is given to the forwarding Messenger to be sent on to the next Messenger (an incorrectly addressed Message is returned to sender). Otherwise the Message is depacketized and delivered to the Messenger Employer in a Message_Delivered_Event via its Message_Delivered_Listener interface. Each Messenger will be bound to an identity Message that will contain at least an "Address" parameter with the Messenger's address, but is typically supplemented by the Employer with other parameters that identify the Employer or perhaps the Employer of the client Messenger for a server side Messanger.

A Dispatcher is a server-side Employer of Messengers. A Dispatcher can be used as a stand-alone application or as a Thread Runnable by some other application. It can be provided with a Configuration or allowed to read a default configuration file based on a name assigned to the Dispatcher or its default name. When a Dispatcher is started it broadcasts its presence to the local host on a configured multicast address (230.1.2.3 by default) and port number (4170 by default) to let potential clients on the same host know that they can initiate their connections. It then binds to a ServerSocketChannel on a configured port (4144 by default) and listens for client connections. When a client connects a Messenger is provided for it. This Messenger is used to to send the client a Message requesting that it identify itself. The client must respond with an identification Message, which is then bound to the Messenger as its identity, or it will be disconnected. This exchange also includes (unless disabled) and authentication process in which the Dispatcher provides an encoded public key object which the client must use to encode a password (of any length) that is sent back to the Dispatcher that uses its private key to decode and compare against its configured password. If the authentication does not succeed the client is disconnected. The Dispatcher maintains a list of all authenticated Messengers and sends the identity Message for each Messenger on the list to all new clients as well as all existing clients that have requested notification of changes to the connected Messengers list. The Dispatcher implements a simple Message content protocol that recognizes Messages with several "Action" parameters. This includes requests for all or named connected Messenger identifications, or to be added or removed from the list of Messengers to receive automatic notification of changes to the connected Messengers list; to be direct communication linked or unlinked with another Messenger by having it added or removed from the forwarding Messenger registration, and vice versa for the other Messenger; to obtain a status report including the memory usage of the Dispatcher and transmissions statistics of each Messenger; and to indicate that it is done and is to be cleanly disconnected and removed from the connected Messengers list. A Dispatcher includes a facility for optionally logging all of its activities to a configured file.

A Messenger_Styled_Writer is included in the package that extends the standard Writer class with a `Styled_Writer` interface implemented with Messages sent via a specified Messenger. This enables a Writer stream to be multiplexed along with other protocol Messages over an established Messenger connection.