agent.java

SRI international 发布的OAA框架软件

/* $Id: Agent.java,v 1.1 2004/02/05 23:02:21 giuli Exp $
 * @(#)Agent.java  02/2004
 *
 * The contents of this file are subject to the OAA Community Research
 * License Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License
 * at http://www.ai.sri.com/~oaa/.  Software distributed under the License
 * is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
 * express or implied. See the License for the specific language governing
 * rights and limitations under the License.  Portions of the software are
 * Copyright (c) SRI International, 1999.  All rights reserved.
 * "OAA" is a registered trademark, and "Open Agent Architecture" is a
 * trademark, of SRI International, a California nonprofit public benefit
 * corporation.
*
*/

package com.sri.oaa2.agentlib;

import com.sri.oaa2.icl.IclList;
import com.sri.oaa2.icl.IclTerm;
import com.sri.oaa2.icl.IclStruct;
import com.sri.oaa2.icl.IclStr;
import com.sri.oaa2.lib.LibOaa;

import org.apache.log4j.Logger;

/**
 * This interface describes the requirements for OAA Agents built using
 * this library.
 *
 * <h3>Usage</h3>
 * <p>
 * To use this Agent interface, first call the <code>facilitatorConnect</code>
 * method with the agent's command line parameters. Then, call the
 * <code>start</code> method to start the agent. When the agent is no longer
 * being used, the method <code>facilitatorDisconnect</code> is used to
 * disconnect the agent.
 * </p>
 * <p>
 * This agent interface contains convenience methods for performing oaa solves
 * and interpreting oaa requests. In particular, this interface automatically
 * handles blocking and direct_connect parameters for the user. By default,
 * the agent is set to block and not to use direct_connect. These parameters
 * can be overidden in one of two ways:
 * <ol>
 *      <li>The methods <code>setUseDirectConnect</code> and
 *          <code>setBlocking</code> are used to change the default values.</li>
 *      <li>If the "block" or "direct_connect" parameters are passed to
 *          the <code>solve</code> and <code>interpret</code> methods, this
 *          automatically overides the default values.</li>
 * </ol>
 * </p>
 * <p>
 * When using direct_connect, an exception is thrown if the direct_connect
 * attempt fails. However, the call was still successsfully handled by the
 * facilitator and the exception will contain the answers that were
 * received from the faciliator. For example:
 * <code><pre>
 *     Agent agent = ...;
 *
 *     agent.facilitatorConnect(new String[] {});
 *     agent.start();
 *
 *     agent.setUseDirectConnect(true);
 *
 *     try {
 *         IclList answers = agent.solve("add(10,20,Sum)", "[]");
 *         System.out.println("direct_connect succeeded, answers = " + answers);
 *     } catch (DirectConnectFailedException ex) {
 *         IclList answers = ex.getAnswers();
 *         System.out.println("direct_connect failed but solve succeeded, answers = " + answers);
 *     } catch (AgentException ex) {
 *         System.err.println("Failed to solve");
 *         ex.printStackTrace();
 *     }
 * </pre></code>
 * </p>
 * <p>
 * For convenience, you can direct your <code>solve</code> or
 * <code>interpret</code> request to a specific agent by using
 * the method <code>setSolvingAgent</code>. This is available whether
 * or not direct_connect has been selected.
 * </p>
 *
 * <h3>Logging</h3>
 * <p>
 * By default logging is logged to the log4j category specified in the
 * <code>DEFAULT_AGENT_LOGGER</code> variable. The logger can be changed through
 * the <code>setLogger</code> method. All setup messages are logged to the info
 * category, and any errors are logged to the fatal category.
 * </p>
 * <p>
 * Note that log4j logging is automatically initialized by the OAA library.
 * </p>
 *
 * @see #facilitatorConnect facilitatorConnect()
 * @see #start start()
 * @see #setBlocking setBlocking()
 * @see #setUseDirectConnect setUseDirectConnect()
 * @see #setSolvingAgent setSolvingAgent()
 * @see #DEFAULT_AGENT_LOGGER DEFAULT_AGENT_LOGGER
 * @see com.sri.oaa2.agentlib.example
 */
public interface Agent {

    /**
     *  The name of the default agent logger.
     */
    public static final String DEFAULT_AGENT_LOGGER
                                                = "oaa.default.agent.log";

    /** Name of the address parameter */
    public final static String ADDRESS_PARAM_NAME = "address";
    /** Name of block parameter */
    public final static String BLOCK_PARAM_NAME = "block";
    /** Name of direct_connect parameter */
    public final static String DC_PARAM_NAME = "direct_connect";

    /** block(true) */
    public final static IclTerm BLOCK_TRUE_PARAM = new IclStruct(BLOCK_PARAM_NAME,
            new IclStr("true"));
    /** block(false) */
    public final static IclTerm BLOCK_FALSE_PARAM = new IclStruct(BLOCK_PARAM_NAME,
            new IclStr("false"));
    /** direct_connect(true) */
    public final static IclTerm DC_TRUE_PARAM = new IclStruct(DC_PARAM_NAME,
            new IclStr("true"));
    /** direct_connect(false) */
    public final static IclTerm DC_FALSE_PARAM = new IclStruct(DC_PARAM_NAME,
            new IclStr("false"));

    /** "get_direct_connect_used" */
    public final static String USED_DC_NAME = "get_direct_connect_used";
    /** "get_direct_connect_used(_)" */
    public final static IclTerm USED_DC_PARAM = IclTerm.fromString(true,
            USED_DC_NAME + "(_)");

    /** Empty ICL list. */
    public final static IclList iclEmptyList = new IclList();

    /**
     * Connects to the OAA facilitator. Registers the name of the agent
     * and the solvables for this agent.
     *
     * @param oaaArgs arguments for OAA
     * @throws AgentException if an error occurred when trying to connect
     */
    void facilitatorConnect(String[] oaaArgs) throws AgentException;

    /**
     * Disconnect this agent from the facilitator. All connections will be
     * closed, including any direct connections to server agents.
     */
    void facilitatorDisconnect();

    /**
     * Return a String describing the capabilities (solvables) of this agent.
     * The String should be of this form:
     * <code>[functor1(...), functor2(...), ...]</code>. For example,
     * <pre>
     * [executeQuery(SQLQuery, ResultSetID, Status),
     * columnCount(ResultSetID, NumberOfColumns, Status),
     * columnNames(ResultSetID, ColumnNames, Status),
     * columnTypes(ResultSetID, ColumnTypes, Status),
     * next(ResultSetID, Row, Status),
     * nextN(ResultSetID, NumberOfRows, Rows, Status),
     * all(ResultSetID, AllRemainingRows, Status),
     * close(ResultSetIDToClose, Status),
     * lastException(ResultSetID, ExceptionMessage, Status]
     * </pre>
     * @return a String describing the capabilities of this agent. A pure client
     * agent has no capabilities and should return <code>[]</code>.
     */
    String getAgentCapabilities();


    /**
     * Return the name of this agent. The OAA facilitator will use this name.
     * @return the name of the agent
     */
    String getAgentName();

    /**
     * Determines if the agent is blocking or non-blocking.
     *
     * @return <code>true</code> if the agent is set to block when solving
     *  and <code>false</code> if the <code>solve</code> method is non-blocking.
     * @see #setBlocking setBlocking()
     */
    boolean getBlocking();

    /**
     * Return the <code>LibOaa</code> instance used to connect to
     * the facilitator.
     *
     * @return the <code>LibOaa</code> instance used to connect to
     * the facilitator
     */
    LibOaa getLibOaa();

    /**
     * Answer the name of the agent that will handle subsequent
     * <code>solve</code> or <code>interpret</code> requests.
     * This may be <code>null</code>, in which case the facilitator
     * will find all agents capable of handling the request.
     *
     * @return the name of the agent that will handle subsequent
     * <code>solve</code> or <code>interpret</code> requests; may
     * be <code>null</code>.
     *
     * @see #setSolvingAgent setSolvingAgent()
     */
    String getSolvingAgent();

    /**
     * Determines if the agent is set to use direct_connect.
     *
     * @return <code>true</code> if the agent is set to use direct_connect when
     *  solving and <code>false</code> if the <code>solve</code> method does
     * not use direct_connect.
     * @see #setUseDirectConnect setUseDirectConnect()
     */
    boolean getUseDirectConnect();

    /**
     * Return a log4j <code>Logger</code>. So that logging is always available,
     * even during the earliest phases of program/agent start-up, this should
     * never return <code>null</code>.
     *
     * @return a log4j <code>Logger</code>; never null.
     * @see #setLogger setLogger()
     */
    Logger getLogger();

    /**
     * Interprets an ICL term. If the input term is an oaa_Solve request,
     * the blocking and direct_connect parameters are added to the solve
     * request if they are not already present.
     * <p>
     * When the agent is set to use direct_connect, or an input solve request
     * specifies that direct_connect should be used, a
     * <code>DirectConnectFailedException</code> will be thrown if the
     * direct connection attempt fails. Note that although this exception
     * is thrown, the request will still be passed through the facilitator
     * and the exception will contain the answers which were received from
     * the facilitator.
     * </p>
     *
     * @param toBeInterpreted the ICL term to be interpreted.
     * @param localParams local parameters for the interpretation.
     * @return the list of answers. Note that this will be an empty list if
     *  the request is sent non-blocking.
     * @throws DirectConnectFailedException if the input term is a solve
     *  request, direct_connect is requested and the direct_connect attempt
     *  failed.
     * @throws AgentException if an error occurs that prevents the term from
     *  being interpreted.
     */
    IclList interpret(IclTerm toBeInterpreted, IclList localParams)
            throws AgentException, DirectConnectFailedException;

    /**
     * The callback that the facilitator will invoke to handle OAA events.
     * The agent must be able to handle all the solvables described by
     * {@link #getAgentCapabilities()}.
     * @param goal a description of the service requested
     * @param params a list of zero or more <code>oaaSolve()</code> parameters
     * @param answers the answers returned; this agent will
     * add an answer to this list
     * @return true if the goal was handled succesfully, false otherwise.
     * @see com.sri.oaa2.lib.LibOaa#oaaSolve oaaSolve()
     */
    boolean oaaDoEventCallback(IclTerm goal,
                               IclList params,
                               IclList answers);

    /**
     * Set the log4j <code>Logger</code> to use.
     * @param logger log4j <code>Logger</code>
     */
    void setLogger(Logger logger);

    /**
     * Sets whether or not the agent is blocking or non-blocking. By default the
     * agent is blocking. This method can be used to change the default setting.
     * <p>
     * Optionally, the "block" parameter can be specified when calling the
     * <code>solve</code> or <code>interpret</code> methods to overide this
     * setting.
     * </p>
     * <p>
     * Note that this setting only applies when the <code>interpret</code>
     * and <code>solve</code> methods of this agent interface are used. These
     * settings do not apply if the <code>LibOaa</code> library is accessed
     * directly.
     * </p>
     *
     * @param blocking <code>true</code> if the agent is set to block when solving
     *  and <code>false</code> if the <code>solve</code> method is non-blocking.
     * @see #getBlocking getBlocking()
     * @see #interpret interpret()
     */
    void setBlocking(boolean blocking);

    /**
     * Set the name of the agent that should handle subsequent solve
     * requests. This is optional. When using direct_connect, this causes
     * the facilitator to be completely bypassed and leads to
     * the highest OAA performance.
     *
     * @param agentName the name of the agent to which subsequent
     * <code>solve</code> or <code>interpret</code> requests will be directed.
     * This can be <code>null</code> to clear a previously set agent name.
     *
     * @see #getSolvingAgent getSolvingAgent()
     */
    void setSolvingAgent(String agentName);

    /**
     * Sets whether or not the agent should use direct_connect. By default the
     * agent does not attempt to use direct_connect. This method can be used to
     * change the default setting.
     * <p>
     * Optionally, the "direct_connect" parameter can be specified when calling
     * the <code>solve</code> or <code>interpret</code> methods to overide this
     * setting.
     * </p>
     * <p>
     * Note that this setting only applies when the <code>interpret</code>
     * and <code>solve</code> methods of this agent interface are used. These
     * settings do not apply if the <code>LibOaa</code> library is accessed
     * directly.
     * </p>
     *
     * @param directConnect <code>true</code> if the agent is set to use
     *  direct_connect whe solving and <code>false</code> if the
     *  <code>solve</code> method does not use direct_connect.
     * @see #getUseDirectConnect getUseDirectConnect()
     * @see #interpret interpret()
     */
    void setUseDirectConnect(boolean directConnect);

    /**
     * Solves an OAA goal. See the <code>interpret</code> method for details
     * on how the goal is solved.
     *
     * @param goal the ICL goal in string form.
     * @param params the ICL parameters in string form.
     * @return the list of answers.
     * @throws AgentException if the goal cannot be solved
     * @see #interpret interpret()
     */
    IclList solve(String goal, String params) throws AgentException;

    /**
     * Solves an OAA goal. See the <code>interpret</code> method for details
     * on how the goal is solved.
     *
     * @param goal the ICL goal to solve.
     * @param params the ICL parameters for the goal.
     * @return the list of answers.
     * @throws AgentException if the goal cannot be solved
     * @see #interpret interpret()
     */
    IclList solve(IclTerm goal, IclTerm params) throws AgentException;

    /**
     * Start the agent after all preliminaries are completed. This is intended
     * to at least invoke <code>oaaReady()</code> but it may certainly
     * do more.
     * @see com.sri.oaa2.lib.LibOaa#oaaReady(boolean shouldPrint) oaaReady()
     */
    void start();
}