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.iquery
Class IQuery

    java.lang.Object
      ix.icore.IXAgent
          ix.iquery.IQuery

Direct Known Subclasses:
  SimpleIQuery

    public abstract class IQuery

extends IXAgent

Generic base for simple information source I-X agents. Such an agent is typically defined by subclassing both this class and `LookupHandler` and defining the three methods those classes leave abstract:

- `isLookupActivity(Activity)` - identifies activities that should be given to a `LookupHandler`.
- `makeLookupHandler(IQuery, Activity)` - creates a `LookupHandler` suitable for handling the activity.
- `LookupHandler.handleLookup()` - handles the activity that was supplied when the `LookupHandler` was created.

Here is an outline example in which an inner class is used for the `LookupHandler` subclass:

     public class Example extends IQuery {

         public Example() {
             super();
         }

         public static void main(String[] argv) {
             Util.printGreeting("I-Q Example");
             new Example().mainStartup(argv);
         }

         protected boolean isLookupActivity(Activity activity) {
             return activity.getPattern().get(0) == ...;
         }

         protected LookupHandler
                   makeLookupHandler(IQuery queryAgent,
                                     Activity lookupActivity) {
             return new ExampleLookupHandler(queryAgent, lookupActivity);
         }

         static class ExampleLookupHandler extends LookupHandler {

             ExampleLookupHandler(IQuery queryAgent, Activity lookupActivity) {
                 super(queryAgent, lookupActivity);
             }

             protected void handleLookup() {
                 try {
                     ...
                     sendReport(ReportType.SUCCESS, "Finished -- ...");
                 }
                 catch (Exception e) {
                     Debug.displayException(e);
                     sendReport(ReportType.FAILURE,
                                "Problem: " + Debug.describeException(e));
                 }
             }

         }

     }

By default, IQuery provides only a simple GUI: a frame containing an "Exit" button and a text area used to display a transcript of the messages sent and received. A different GUI could be created by overriding the `startup()` or `setupGUI()` methods.

When the agent receives a message, a description of the message is added to the transcript text area. Then, if the message is an `Activity` and `isLookupActivity(Activity)` returns true, the `handleLookupActivity(Activity)` method is called.

That method arranges for each request to be handled in a separate `IQuery.LookupThread`. The thread creates a new `LookupHandler` by calling `makeLookupHandler(IQuery, Activity)` and then calls the handler's `LookupHandler.handleLookup()` method.

Most activities of an I-X agent take place in the AWT event-handling thread, and operations on Swing GUI components should take place there as well, so `LookupHandler.handleLookup()` has to take care to do things in the right thread. The `LookupHandler` class provides some utility methods that deal with the most common cases: adding text to the transcript, and sending a report back to the agent that sent the lookup activity. In other cases, `Util.swingAndWait(Runnable)` might be used. `Debug.displayException(Throwable)` can be used in any thread to put up a dialog window that tells the user of an exception.

If for some reason you don't want a separate thread for each request, override `handleLookupActivity(Activity)`.

Nested Class Summary
`protected class` | `IQuery.LookupThread` A thread that invokes a `LookupHandler`.

Field Summary

Fields inherited from class ix.icore.IXAgent
`contactManager, displayName, eventLogger, exitHooks, initialDisplayName, ipcName, ipcStrategyName, iSimTimer, mainAgent, nameListeners, startupDate, startupHooks, symbolName, textFrame`

Constructor Summary
`IQuery()`

Method Summary
`void` | `addTool(ToolController tc)` Adds a tool, usually by adding an entry to a "Tools" menu in the GUI.
`void` | `do_transcript(java.lang.String line)` A utility that adds a line to this agent's transcript text area.
`void` | `exit()` Called when the agent should cease execution.
`protected void` | `handleLookupActivity(Activity activity)` Handles the activity be creating and starting a new `IQuery.LookupThread`.
`void` | `handleNewActivity(Activity activity)` Handles new activities from external sources.
`protected abstract boolean` | `isLookupActivity(Activity activity)` Determines whether the activity is one that should be handled by a `LookupHandler`.
`protected abstract LookupHandler` | `makeLookupHandler(IQuery queryAgent, Activity lookupActivity)` Return a `LookupHandler` for an activity that was approved by `isLookupActivity(Activity)`.
`protected void` | `processCommandLineArguments()` Command-line argument processing.
`protected void` | `setupGUI()` Creates a "transcript" frame for this agent, including an "Exit" button.
`protected void` | `startup()` Agent setup and initialization.

Methods inherited from class ix.icore.IXAgent
`addAgentNameListener, addExitHook, addStartupHook, adjustLookAndFeel, displayMessage, do_mainStartup, ensureTool, fireSymbolNameChanged, getAgent, getAgentDisplayName, getAgentIPCName, getAgentStartupDate, getAgentSymbolName, getContactManager, getEventLogger, getISimTimer, getKnownAgents, handleInput, handleNewChatMessage, handleNewConstraint, handleNewIssue, handleNewReport, handleReceivedReport, installAgentExtensions, installAgentExtensions, isMainAgent, log, mainStartup, notePossibleNewContact, pre_handleInput, preprocessInput, reportInputException, setAgentSymbolName, setEventLogger, setupISimTimer, startServer`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### IQuery

    public IQuery()

Method Detail

### processCommandLineArguments

    protected void processCommandLineArguments()

  Command-line argument processing.

  Overrides:
    `processCommandLineArguments` in class `IXAgent`
  See Also:
    `IFUtil.adjustLookAndFeel()`, `IPC.makeCommunicationStrategy(String methodName)`, `ContactManager.processCommandLineArguments()`, `Debug.on`, `Parameters`

### startup

    protected void startup()

  Agent setup and initialization. The method supplied by the IQuery class just calls `setupGUI()` in the AWT event thread.

  Overrides:
    `startup` in class `IXAgent`
  See Also:
    `IXAgent.startup()`

### setupGUI

    protected void setupGUI()

  Creates a "transcript" frame for this agent, including an "Exit" button.

### exit

    public void exit()

  Called when the agent should cease execution.

  Overrides:
    `exit` in class `IXAgent`

### addTool

    public void addTool(ToolController tc)

  Description copied from class: `IXAgent`
  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.

  Overrides:
    `addTool` in class `IXAgent`

### do_transcript

    public void do_transcript(java.lang.String line)

  A utility that adds a line to this agent's transcript text area. This method is normally called by other utility methods, including ones in the `LookupHandler` class, rather than being called directly.

### handleNewActivity

    public void handleNewActivity(Activity activity)

  Handles new activities from external sources. A description of the activity is added to the transcript text area. Then, if `isLookupActivity(Activity)` returns true, handleNewActivity calls `handleLookupActivity(Activity)`; otherwise, the activity is ignored.

  Overrides:
    `handleNewActivity` in class `IXAgent`

### handleLookupActivity

    protected void handleLookupActivity(Activity activity)

  Handles the activity be creating and starting a new `IQuery.LookupThread`.

### isLookupActivity

    protected abstract boolean isLookupActivity(Activity activity)

  Determines whether the activity is one that should be handled by a `LookupHandler`.

  See Also:
    `handleNewActivity(Activity)`

### makeLookupHandler

    protected abstract LookupHandler makeLookupHandler(IQuery queryAgent,
                                                       Activity lookupActivity)

  Return a `LookupHandler` for an activity that was approved by `isLookupActivity(Activity)`.

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