ix.icore
Class IXAgent

java.lang.Object
  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

• handleNewIssue(Issue issue)
• handleNewActivity(Activity activity)
• handleNewConstraint(Constraint constraint)
• handleNewReport(Report report)
• handleNewChatMessage(ChatMessage message)

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

• handleInput(IPC.InputMessage message)

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.