gumbo.net.msg
Class MessageAgent

java.lang.Object
  |
  +--gumbo.util.AbstractDisposable
        |
        +--gumbo.net.msg.MessageAgent
All Implemented Interfaces:
Disposable
Direct Known Subclasses:
TestClientAgent, TestServerAgent

public abstract class MessageAgent
extends AbstractDisposable

Base class for an agent that conveniently facilitates network messaging for a network node (client, server). This class combines the sending of request messages, via sendMessage(), and the handling of response messages, via addHandler(), although use of both functions is not required. Note that message sending (requests) and message handling (responses) are stateless (responses are not checked against requests).

Includes support for standard reporting of status to the application "root" window and/or a "target" child window, and for showing an error dialog.

Version:
$Revision: 1.1 $
Author:
Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Nested Class Summary
protected  class MessageAgent.Handler
          Used by subclasses to handle messages received from this agent's message router (see addHandler()).
 
Constructor Summary
MessageAgent(MessageThread thread, MainWindow root, MainWindow target)
          Creates an instance.
 
Method Summary
 void addHandler(MessageAgent.Handler handler)
          Used by subclasses to add a message handler to this agent's message router.
 NetThread getMessageThread()
          Returns the message thread, which is used to send and receive messages.
 MainWindow getRootWindow()
          Returns the root window, for status and error reporting.
 MainWindow getTargetWindow()
          Returns the target window, for status and error reporting.
protected  void implDispose()
          Removes all handlers from message router, disposes self.
 java.lang.String reportProblem(java.lang.String msg, java.lang.Throwable th)
          Used by the system and subclasses to show a dialog with a message and the throwable's stack trace.
 java.lang.String reportStatus(java.lang.String msg)
          Used by the system and subclasses to report a status message to the window status bar, such as during message send, receive, and handling.
 boolean sendMessage(java.lang.String action, Message msg)
          Used by subclasses to send a message using this agent's message writer.
 
Methods inherited from class gumbo.util.AbstractDisposable
dispose, isDisposed
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MessageAgent

public MessageAgent(MessageThread thread,
                    MainWindow root,
                    MainWindow target)
Creates an instance.

Parameters:
thread - The message thread, for sending and receiving messages. Never null.
root - The root window, for status and error reporting. None if null.
target - The target window, for status and error reporting. None if null.
Method Detail

getMessageThread

public final NetThread getMessageThread()
Returns the message thread, which is used to send and receive messages. Never null.


getRootWindow

public final MainWindow getRootWindow()
Returns the root window, for status and error reporting. Null if none.


getTargetWindow

public final MainWindow getTargetWindow()
Returns the target window, for status and error reporting. Null if none.


reportProblem

public java.lang.String reportProblem(java.lang.String msg,
                                      java.lang.Throwable th)
Used by the system and subclasses to show a dialog with a message and the throwable's stack trace. In order of precedence, the dialog parent is the target window, the root window, and then no window (the screen).

Returns:
The full text of the displayed message. Never null.

reportStatus

public java.lang.String reportStatus(java.lang.String msg)
Used by the system and subclasses to report a status message to the window status bar, such as during message send, receive, and handling. The message is reported to the root and target windows. If the root and target windows are null nothing happens.

Returns:
The full text of the displayed message. Never null.

sendMessage

public final boolean sendMessage(java.lang.String action,
                                 Message msg)
Used by subclasses to send a message using this agent's message writer. Includes status and problem reporting, with all message related exceptions (Exception) being caught. Will throw a caught exception if the thread has no writer.

Parameters:
action - The name of the action performed by the message (such as "open source window"), which is used for status and error reporting. Never null.
msg - The message to be sent. Never null.
Returns:
True if successful; false if a message exception occured.

addHandler

public final void addHandler(MessageAgent.Handler handler)
Used by subclasses to add a message handler to this agent's message router. Can be safely used during subclass initialization (the thread's router is static, not dynamic).

Parameters:
handler - The message handler. Never null.

implDispose

protected void implDispose()
Removes all handlers from message router, disposes self.

Specified by:
implDispose in class AbstractDisposable