Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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` | `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 java.util.Map<IXAgent,java.lang.Boolean>` | `knownAgents`
`protected java.util.List` | `nameListeners`
`protected java.util.Date` | `startupDate`
`protected java.util.List` | `startupHooks`
`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.
`protected` | `IXAgent(boolean setAgent)` Constructor for subclasses that need to create a second agent.

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` | `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` | `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.
`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
`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

### thisAgent

    protected static IXAgent thisAgent

### knownAgents

    protected static java.util.Map<IXAgent,java.lang.Boolean> knownAgents

### 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 startupHooks

### exitHooks

    protected java.util.List exitHooks

### nameListeners

    protected java.util.List 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.

### IXAgent

    protected IXAgent(boolean setAgent)

  Constructor for subclasses that need to create a second agent.

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.

### 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)

### 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 `AgentExtension#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.

### getAgent

    public static IXAgent getAgent()

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

### 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)`

### 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 `ItemVar`s 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD