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