ix.icore
Class IXAgent

java.lang.Object
  extended by ix.icore.IXAgent
Direct Known Subclasses:
IChat, Ip2, IQuery, Itest, SeparateStrategy.SeparateAgent, SimpleIXAgent, SimpleNameServer.MiniAgent, 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[]), which calls IXAgent methods
    1. processCommandLineArguments()
    2. startup()
    3. startServer(Object agentName, String strategyName)
A subclass that redefines processCommandLineArguments() or startup() should normally have them call the corresponding super method to ensure that any common processing is performed. To support IPC, a subclass of IXAgent must assign a value to the ipcName field, 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  EventLogger eventLogger
           
protected  java.util.List<java.lang.Runnable> exitHooks
           
protected  java.lang.String initialDisplayName
           
protected  java.lang.String ipcName
          Name used for IPC purposes and returned by the getAgentIPCName() method.
protected  java.lang.String ipcStrategyName
           
protected  ISimTimer iSimTimer
           
protected static IXAgent mainAgent
           
protected  java.util.List<AgentNameListener> nameListeners
           
protected  java.util.Date startupDate
           
protected  java.util.List<java.lang.Runnable> startupHooks
           
protected  java.lang.String symbolName
           
protected  TextAreaFrame textFrame
          A text area in a separate frame used to display information about incoming messages.
 
Constructor Summary
  IXAgent()
          Standard constructor.
protected IXAgent(boolean isMainAgent)
          Constructor that can be used to create IXAgents that aren't the main one.
 
Method Summary
 void addAgentNameListener(AgentNameListener listener)
           
 void addExitHook(java.lang.Runnable hook)
           
 void addStartupHook(java.lang.Runnable hook)
           
 void addTool(ToolController tc)
          Adds a tool, usually by adding an entry to a "Tools" menu in the GUI.
protected  void adjustLookAndFeel()
           
protected  void displayMessage(java.lang.String message)
          Adds the specified string to the default message display.
protected  void do_mainStartup(java.lang.String[] argv)
          The main body of mainStartup(String[]).
 java.lang.Object ensureTool(java.lang.String toolName)
          Returns the tool of the specified name, causing it to be created if it does not already exist.
 void exit()
          Called when the agent should cease execution.
 void fireSymbolNameChanged(java.lang.String oldName, java.lang.String newName)
           
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.util.Date getAgentStartupDate()
           
 java.lang.String getAgentSymbolName()
          Returns this agent's symbol name.
 ContactManager getContactManager()
          Returns this agent's contact manager.
 EventLogger getEventLogger()
          Returns this agents event-logger.
 ISimTimer getISimTimer()
          Returns this agent's ISimTimer;
static java.util.Set<IXAgent> getKnownAgents()
          Returns a set containing all IXAgents that have not been garbage-collected.
 void handleInput(IPC.InputMessage message)
          Handles external input in the form of an IPC.InputMessage that contains an object such as an Issue, Activity, or Report.
 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.
protected  void handleReceivedReport(TaskItem item)
          Utility for sending a "Received" report about an issue or activity.
 void installAgentExtensions()
          Installs any extensions specified by the "extension-classes" parameter.
protected  void installAgentExtensions(java.util.List classNames)
           
 boolean isMainAgent()
          Indicates whether this is the main (usually standalone) agent.
 void log(HistoryEvent event)
           
 void mainStartup(java.lang.String[] argv)
          Method called by main(String[] argv) to perform the initialization sequence 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  IPC.InputMessage preprocessInput(IPC.InputMessage message)
          A chance to modify or replace a message on its way in.
protected  void processCommandLineArguments()
          Handles command-line arguments common to all I-X agents.
protected  void reportInputException(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.
 void setAgentSymbolName(java.lang.String name)
          Changes the agent's symbol name
 void setEventLogger(EventLogger logger)
           
protected  void setupISimTimer()
           
protected  void startServer(java.lang.Object agentName, java.lang.String strategyName)
          Set the main (global) IPC communication strategy and set up to receive messages by calling the strategy's setupServer method.
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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mainAgent

protected static IXAgent mainAgent

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

initialDisplayName

protected java.lang.String initialDisplayName

contactManager

protected ContactManager contactManager

eventLogger

protected EventLogger eventLogger

iSimTimer

protected ISimTimer iSimTimer

ipcStrategyName

protected java.lang.String ipcStrategyName

startupHooks

protected java.util.List<java.lang.Runnable> startupHooks

exitHooks

protected java.util.List<java.lang.Runnable> exitHooks

nameListeners

protected java.util.List<AgentNameListener> nameListeners

startupDate

protected java.util.Date startupDate

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. Equivalent to new IXAgent(true).


IXAgent

protected IXAgent(boolean isMainAgent)
Constructor that can be used to create IXAgents that aren't the main one.

See Also:
isMainAgent(), getAgent()
Method Detail

mainStartup

public void mainStartup(java.lang.String[] argv)
Method called by main(String[] argv) to perform the initialization sequence common to all I-X agents. However, all it does directly is to call do_mainStartup(String[]) inside a "catch" that reports any exception thrown.


do_mainStartup

protected void do_mainStartup(java.lang.String[] argv)
The main body of mainStartup(String[]). It is called inside a "catch" that reports any exception thrown.


setupISimTimer

protected void setupISimTimer()

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.


adjustLookAndFeel

protected void adjustLookAndFeel()

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.makeCommunicationStrategy(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:
IFUtil.adjustLookAndFeel(), IPC.makeCommunicationStrategy(String methodName), ContactManager.processCommandLineArguments(), Debug.on, Parameters

addStartupHook

public void addStartupHook(java.lang.Runnable hook)

addExitHook

public void addExitHook(java.lang.Runnable hook)

exit

public void exit()
Called when the agent should cease execution.


installAgentExtensions

public void installAgentExtensions()
Installs any extensions specified by the "extension-classes" parameter. The value of the paremeter must be a comma-separated list of class names. The class names are processed in the order given, which allows later extensions to modify the effects of earlier ones.

Each class must implement the IXAgentExtension interface and must have a public 1-argument constructor that declares its parameter as IXAgent or an IXAgent subclass. One instance of each class is constructed, passing this agent as the parameter, and then the instance's IXAgentExtension.installExtension() method is called.

installAgentExtensions is not called by methods in the IXAgent class. Instead, it should be called by instances of IXAgent subclasses at an appropriate point for the type of agent involved.


installAgentExtensions

protected void installAgentExtensions(java.util.List classNames)

getAgent

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


isMainAgent

public boolean isMainAgent()
Indicates whether this is the main (usually standalone) agent.


getKnownAgents

public static java.util.Set<IXAgent> getKnownAgents()
Returns a set containing all IXAgents that have not been garbage-collected.


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.


setAgentSymbolName

public void setAgentSymbolName(java.lang.String name)
Changes the agent's symbol name


addAgentNameListener

public void addAgentNameListener(AgentNameListener listener)

fireSymbolNameChanged

public void fireSymbolNameChanged(java.lang.String oldName,
                                  java.lang.String newName)

getAgentDisplayName

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


getAgentStartupDate

public java.util.Date getAgentStartupDate()

getContactManager

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


getEventLogger

public EventLogger getEventLogger()
Returns this agents event-logger.

See Also:
log(HistoryEvent)

setEventLogger

public void setEventLogger(EventLogger logger)

log

public void log(HistoryEvent event)

getISimTimer

public ISimTimer getISimTimer()
Returns this agent's ISimTimer;


addTool

public void addTool(ToolController tc)
Adds a tool, usually by adding an entry to a "Tools" menu in the GUI. This method throws an exception that says tool additions are not supported; it should be overridden in subclasses that do allow tools.

Throws:
java.lang.UnsupportedOperationException - if called.

ensureTool

public java.lang.Object ensureTool(java.lang.String toolName)
Returns the tool of the specified name, causing it to be created if it does not already exist. Note that it returns the tool, not its tool-controller, and that it does not change the tool's visibility.

The method supplied by the IXAgent class throws an exception; it should be overridden in subclasses that do allow tools.

Throws:
java.lang.UnsupportedOperationException - if called.

startServer

protected void startServer(java.lang.Object agentName,
                           java.lang.String strategyName)
Set the main (global) IPC communication strategy and set up to receive messages by calling the strategy's setupServer method. If the "enqueue-incoming-messages" parameter is true, it uses a BufferedMessageListener so that the thread that supplies a message need't wait for the message to be processed by the panel; otherwise, a plain MessageListener is used. In both cases, the listener delivers the message by calling pre_handleInput(IPC.InputMessage), but a buffered listener has its own thread that waits for that call to return before looking for the next message.

See Also:
IPC, IPC.setupServer(Object, IPC.MessageListener), IPC.BufferedMessageListener

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 marks the message as external and (once in the event dispatching thread) catches any Errors or Exceptions thrown out of input handling and reports them to the user.


preprocessInput

protected IPC.InputMessage preprocessInput(IPC.InputMessage message)
A chance to modify or replace a message on its way in. This method is called by pre_handleInput(IPC.InputMessage) before it calls handleInput(IPC.InputMessage).

The method in the IXAgent class currently renames ItemVars in issue and activity patterns.

See Also:
ItemVar.renameItemVars(Object)

reportInputException

protected void reportInputException(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 object such as an Issue, Activity, or Report. 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.


handleReceivedReport

protected void handleReceivedReport(TaskItem item)
Utility for sending a "Received" report about an issue or activity.


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.