Package gumbo.net.msg

Provides special purpose building blocks for building, writing and reading application-specific network messages.

See:
Description

Interface Summary

MessageIO	Base interface for message transport (IO) classes (readers and writers).
MessageIOListener	Interface for listeners of message IO events.
MessageListener	Interface for sending a message to a message handler.
MessageReader	Interface for reading whole messages.
MessageWriter	Interface for writing whole messages.

Class Summary

AbstractMessageIO	Abstract base class for message transport (IO) classes (readers and writers).
Message	Abstract base class for messages conforming to the Gumbo client-server message protocol.
MessageAgent	Base class for an agent that conveniently facilitates network messaging for a network node (client, server).
MessageHandler	A message listener that can be queried for the type(s) of messages that it can listen for.
MessageHead	Class containing the message head, which is standard for all message types.
MessageIOPrinter	A message IO listener that prints all events to a writer.
MessageMonitorWriter	Writer filter that translates an ASCII message stream into a more readable form for monitoring message traffic.
MessageRelay	A message listener that relays all received messages to a target thread's message writer.
MessageRouter	DirectRouters messages to message listeners.
MessageRouterThread	A thread for asynchronously receiving messages and routing them to registered handlers.
MessageThread	Abstract base class for network threads intended for messaging using Gumbo's message protocol (see Message).
MsgPingCommand	A command message commanding the target, typically the system server, to respond with a MsgPingStatus message.
MsgPingStatus	A status message in response to a MsgPingCommand message, notifying the target that the source, typically the system server, is alive.
ObjectMessageEnd	Singleton object that serves as an end of message delimiter for messages transported using object serialization.
ObjectMessageReader	Reads a message as a Java object from an object stream.
ObjectMessageWriter	Writes a message as a Java object to an object stream.
PingTransponder	A Message listener that sends a MsgPingStatus message when it receives a MsgPingCommand message.

Exception Summary

MessageDataException	Base class for exceptions involving the message data format.
MessageException	Base class for exceptions involving messages.
MessageIOException	Base class for exceptions involving the message transport format.

Package gumbo.net.msg Description

Provides special purpose building blocks for building, writing and reading application-specific network messages.

Overview

This package support network messaging, using ASCII or Java object serialization and the transport protocol. A message consists of a standard message head and an application specific message body. Messages that support only object serialization subclass Message. Those that also support ASCII subclass AsciiMessage. Message IO occurs through message readers and writers, which support object serialization or ASCII transport. Message notification is supported through MessageRouter, which routes a received message to none or more listeners according to message type.

Message Types

As implemented in this package, messages are generic. By convention, however, messages can be categorized and named as follows, in terms of their intended action and result.

Command Message

A command message commands the message target to perform some operation or to change its state or perform some service. Depending on the application and command, a status response message (e.g. commanded action has completed) may or may not be sent to an "action target". Typically, the action target is the same as the request message source. If it is not, then the action target must be specified in the request message. If a response is expected then a "command ID" may be included in the command message. The message target treats the command ID as a cookie, returning it with the status message. The recipient of the command status can use the command ID to associate the status message with its originating command message.

Request Message

A request message is a request for the message target to send some data to an action target. Unlike a command message, this action simply requires the target to sample its current state, not to modify it. As with a command message, a "request ID" may be included in the request message so that the action target can associate the response data with its originating request message.

Watch Message

A watch message commands the message target to notify an action target when the state or some data maintained by the message target changes. This action is in support of the “observer” pattern, with the action target being the observer and the message target receiving the watch message being the observee containing the observed data. In some sense a watch message is a cross between a command message, to schedule status notification, and a request message, for data. As with a command message, a "watch ID" may be included in the watch message so that the action target can associate the response data or status with its originating watch message.

Response Message

A response message returns the data requested by a prior request or watch message, along with any "request ID" or "watch" ID cookie.

Status Message

A status message notifies the message target that the some significant event has occurred in the message source, and includes any "command ID" or "watch ID" cookie. Status messages can occur spontaneously (e.g. server is shutting down), as the result of a command (e.g. the commanded action is complete), or as the result of a watch (e.g. notification every 15 seconds that the server is alive).

To Do

• (nothing)