ix.icore
Class IXAgent

java.lang.Object
  |
  +--ix.icore.IXAgent
Direct Known Subclasses:
IChat, Ip2, Itest, SimpleIXAgent, XMLTreeEditor

public abstract class IXAgent
extends java.lang.Object

Common class for I-X agents.

An agent is usually created by instantiating a subclass of IXAgent and then calling its mainStartup(String[] argv) method. That method will usually be inherited from IXAgent; it processes any command line arguments and then calls startup(). Thus, from the subclass's point of view, startup and initialization has the following steps:

  1. One of the subclass's constructurs, which will call superclass constructors.
  2. mainStartup(String[] argv), which calls
    1. processCommandLineArguments()
    2. startup()
A subclass that redefines processCommandLineArguments() or startup() should normally have them call the corresponding super method to ensure that any common processing is performed. For example, the IXAgent processCommandLineArguments() method will set up interprocess communication as specified by the argument -ipc=className.

To support IPC, a subclass of IXAgent must assign a value to the ipcNamefield, to be returned by the getAgentIPCName() method, and will typically want to define

or, to intervene at an earlier stage, the method that calls the ones above,

See Also:
SimpleIXAgent, SimpleIXAgent.java source code

Field Summary
protected  ContactManager contactManager
           
protected  java.lang.String displayName
           
protected  java.lang.String ipcName
          Name used for IPC purposes and returned by the getAgentIPCName() method.
protected  java.lang.String symbolName
           
protected  TextAreaFrame textFrame
          A text area in a separate frame used to display information about incoming messages.
protected static IXAgent thisAgent
           
 
Constructor Summary
IXAgent()
          Standard constructor.
 
Method Summary
protected  void displayMessage(java.lang.String message)
          Adds the specified string to the default message display.
static IXAgent getAgent()
          Returns an object that represents the agent.
 java.lang.String getAgentDisplayName()
          Returns this agent's display name.
 java.lang.Object getAgentIPCName()
          Returns the object used to represent the agent as an IPC "destination".
 java.lang.String getAgentSymbolName()
          Returns this agent's symbol name.
 ContactManager getContactManager()
          Returns this agent's contact manager.
 void handleInput(IPC.InputMessage message)
          Handles external input in the form of an IPC.InputMessage that contains an Issue or Report object.
 void handleNewActivity(Activity activity)
          Handles new activities from external sources.
 void handleNewChatMessage(ChatMessage message)
          Handles new chat messages from external sources.
 void handleNewConstraint(Constraint constraint)
          Handles new constraints from external sources.
 void handleNewIssue(Issue issue)
          Handles new issues from external sources.
 void handleNewReport(Report report)
          Handles new reports from external sources.
 void mainStartup(java.lang.String[] argv)
          Method called by main(String[] argv) to do initialization common to all I-X agents.
 void notePossibleNewContact(IPC.InputMessage message)
          Tells this agent's contact manager about the sender-id of the message (if the id can be determined) in case it represents a new contact.
protected  void pre_handleInput(IPC.InputMessage message)
          Gets the message before the handleInput method and ensures that handleInput is called in the AWT event dispatching thread.
protected  void processCommandLineArguments()
          Handles command-line arguments common to all I-X agents.
protected  void startServer(java.lang.Object agentName, java.lang.String strategyName)
          Set the default IPC communication strategy and set up to receive messages.
protected  void startup()
          Method called by the mainStartup(String[] argv) method to perform any setup and initialization that should take place after this agent's constructor has been called and command-line arguments have been processed.
protected  void tellUserOfException(IPC.InputMessage message, java.lang.Throwable t)
          Called by the pre_handleInput method to put up a dialog describing an Error or Exception and the message that caused it to be thrown.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

thisAgent

protected static IXAgent thisAgent

ipcName

protected java.lang.String ipcName
Name used for IPC purposes and returned by the getAgentIPCName() method.

displayName

protected java.lang.String displayName

symbolName

protected java.lang.String symbolName

contactManager

protected ContactManager contactManager

textFrame

protected TextAreaFrame textFrame
A text area in a separate frame used to display information about incoming messages.
Constructor Detail

IXAgent

public IXAgent()
Standard constructor.

Method Detail

mainStartup

public void mainStartup(java.lang.String[] argv)
Method called by main(String[] argv) to do initialization common to all I-X agents.

startup

protected void startup()
Method called by the mainStartup(String[] argv) method to perform any setup and initialization that should take place after this agent's constructor has been called and command-line arguments have been processed.

At present, this method does nothing, and all the work is done in subclasses.


processCommandLineArguments

protected void processCommandLineArguments()
Handles command-line arguments common to all I-X agents. At present, this method also makes any standard I-X changes to the look and feel.

The following are handled directly my this method:

    -debug=boolean
    -ipc=name
    -ipc-name=name
    -symbol-name=name
    -display-name=name
 
debug is used to set Debug.on.

The name in -ipc=name argument will be interpreted by the IPC.getCommunicationStrategy(String) method.

The name in the -icp-name=name argument sets the name that this agent calls itself for IPC and that is returned by the getAgentIPCName() method.

Needs further explanation of ipc-name, and of symbol-name and display-name. ...

The processCommandLineArguments method of this agent's contact manager is called to handle arguments that list relationships with other agents.

See Also:
IfaceUtil.adjustLookAndFeel(), IPC.getCommunicationStrategy(String methodName), ContactManager.processCommandLineArguments(), Debug.on, Parameters

getAgent

public static IXAgent getAgent()
Returns an object that represents the agent. At present, there can be only one IXAgent per VM.

getAgentIPCName

public java.lang.Object getAgentIPCName()
Returns the object used to represent the agent as an IPC "destination". This object is usually, but not necessarily, a string containing the agent's name. The details will depend on the set of communication strategies that might be used.
See Also:
IPC, IPC.CommunicationStrategy

getAgentSymbolName

public java.lang.String getAgentSymbolName()
Returns this agent's symbol name.

getAgentDisplayName

public java.lang.String getAgentDisplayName()
Returns this agent's display name.

getContactManager

public ContactManager getContactManager()
Returns this agent's contact manager.

startServer

protected void startServer(java.lang.Object agentName,
                           java.lang.String strategyName)
Set the default IPC communication strategy and set up to receive messages.
See Also:
IPC

pre_handleInput

protected void pre_handleInput(IPC.InputMessage message)
Gets the message before the handleInput method and ensures that handleInput is called in the AWT event dispatching thread. This is perhaps a temporary measure. It also (once in the event dispatching thread) catches any Errors or Exceptions thrown out of input handling and reports them to the user.

tellUserOfException

protected void tellUserOfException(IPC.InputMessage message,
                                   java.lang.Throwable t)
Called by the pre_handleInput method to put up a dialog describing an Error or Exception and the message that caused it to be thrown.

notePossibleNewContact

public void notePossibleNewContact(IPC.InputMessage message)
Tells this agent's contact manager about the sender-id of the message (if the id can be determined) in case it represents a new contact.

handleInput

public void handleInput(IPC.InputMessage message)
Handles external input in the form of an IPC.InputMessage that contains an Issue or Report object. It calls one of handleNewIssue, handleNewReport, etc as appropriate.

handleNewIssue

public void handleNewIssue(Issue issue)
Handles new issues from external sources. Subclasses will usually redefine this method.

handleNewActivity

public void handleNewActivity(Activity activity)
Handles new activities from external sources. Subclasses will usually redefine this method.

handleNewConstraint

public void handleNewConstraint(Constraint constraint)
Handles new constraints from external sources. Subclasses will usually redefine this method.

handleNewReport

public void handleNewReport(Report report)
Handles new reports from external sources. Subclasses will usually redefine this method.

handleNewChatMessage

public void handleNewChatMessage(ChatMessage message)
Handles new chat messages from external sources. Subclasses will usually redefine this method.

displayMessage

protected void displayMessage(java.lang.String message)
Adds the specified string to the default message display.