com.sri.oaa2.lib
Class LibOaa

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--com.sri.oaa2.lib.LibOaa

All Implemented Interfaces:

java.lang.Runnable

public class LibOaa

extends java.lang.Thread

This class provides all the facilities to make an application become an agent in an Open Agent Architecture community.

Usage

Creating the OAA library

To create an agent, create a new instance of the OAA library, passing some communication protocol object to use as the transport layer:

 LibOaa myOaa = new LibOaa(new LibCom(new LibComTcpProtocol()));
 

Then, register any callbacks for agent events. Usually, you must at least define the callback app_do_event type to handle incoming oaaSolve() requests. In this example, we link the callback to a function myOAADoEvent, which we must later define to handle all capabilities our agent registers with the Facilitator. (see oaaRegister() below).

   myOaa.oaaRegisterCallback("app_do_event",
     new OAAEventListener() {
     public boolean doOAAEvent(IclTerm goal, IclList params, IclList answers) {
       return myOAADoEvent(goal, params, answers);
     }
     });
 

Connecting the agent to the facilitator

Early on in an agent's lifecycle, it must connect to a Facilitator agent who will manage it's communication with other agents. The agent must call the method oaaSetupCommunication. The name of the agent is supplied as the only argument to this method as follows:

     // First, connects to the facilitator
     if (!myOaa.oaaSetupCommunication("myAgent")) {
     printError("Could not setup");
     return;
     }
 

There are three ways to specify the facilitator address, listed here in order of preference:

1. Specify the default facilitator in the "setup.pl" file. This file is located in the home directory on unix and the root c:\ drive on windows. The default facilitator is specified using the "default_facilitator" struct. For example, the following entry specifies that the faciitator is located on "myhost.ai.sri.com" listening on port 4020:

 %%%% SETUP FILE FOR OAA %%%%%%%
 default_facilitator(tcp('myhost.ai.sri.com',4020)).
 

• 2. The "oaa_connect" command line parameter may be used. For example, " -oaa_connect "tcp('myhost.ai.sri.com',4020)"
• 3. The "OAA_CONNECT" System property may be set to the facilitator address. The syntax is the same as the "-oaa_connect" command line parameter.

"setup.pl" is always checked first, followed by the command line and then the system property.

Enabling direct_connect

When a client agent sends a request to the facilitator, the facilitator forwards the request to one or more agents, receives the responses and then forwards the responses back to the calling agent. This means any data passed in the communications must be passed through the facilitator. A better solution is to pass the data directly from the calling agent to an agent which can solve the request.

To allow this optimization it is possible to specify the parameter "direct_connect(true)" when calling oaaSolve. In order for direct_connect to be possible, the following conditions must hold:

• 1. There must be only one agent which can solve the request. direct_connect does not currently support mulitple solves from multiple agents.
• 2. The agent which has registered the solvable must be enabled for direct_connect. As described below, the "oaa_listen" command line variable is specified to enable an agent for direct_connect.

If these conditions hold and the "direct_connect(true)" parameter is specified, oaaSolve will attempt to make a direct connection to the appropriate agent in order to solve the request. Once a connection has been made it is cached for later use. The connection is terminated when the call to oaaDisconnect(IclList) is made.

Note that "oaaSetupCommunication" sets up an agent listener for direct_connect. It checks the command line variable "oaa_listen" to retrieve the address to listen for direct connections. For example, if the command line ' -oaa_listen "tcp('localhost',4012)" ' is supplied, the OAA library will open a listen socket on port 4012 used to accept direct connections. If the "oaa_listen" command line parameter is not found, then the System property "OAA_LISTEN" is checked.

Also supported is a binary protocol for efficient data transfer. In the current release, this requires another server port for a direct_connect enabled agent. The binary server port defaults to the direct_connect port with ten added to it. So, in the above example the agent will listen on ports 4012 and 4022. The need for a second listen port is temporary and may be removed in a future release of OAA. To set the second listen port manually, the command line variable "oaa_listen_binary" or system property "OAA_LISTEN_BINARY" may be used.

In addition to the direct_connect parameter, an address parameter may also be specified when calling oaaSolve. Specifying the direct_connect and address parameters provides the fastest performance OAA can give. The address parameter can be retrieved by invoking the agent_host solvable with the agent's name. For example, the following code retrieves the agent address for an agent by name, and then uses the address and direct_connect parameter to achieve maximum performance:

   public String getAgentAddress(LibOaa myOaa, String agentName) throws Exception {
       IclList res = new IclList();

       myOaa.oaaSolve(IclTerm.fromString(true,
               "agent_host(Addr,'" + agentName + "',Host)"), new IclList(), res);

       if (res.size() == 0) {
           throw new Exception("Unable to retrieve agent address using agent_host");
       }
       String agentAddr = res.getTerm(0).getTerm(0).toString();
       return agentAddr;
   }

   private IclList solveParams = null;
   public IclList callOaaMaximumPerformance(LibOaa myOaa, IclTerm goal) throws Exception {
       if (solveParams == null) {
           // Retrieves the name of the agent. Note: in order to use
           // this method the name of the agent must be known.
           String agentAddress = getAgentAddress(myOaa, "myServerAgent");
           solveParams = new IclList();
           solveParams.add(new IclStruct("direct_connect", new IclStr("true")));
           solveParams.add(new IclStruct("address", IclTerm.fromString(true,agentAddress)));
       }

       IclList res = new IclList();

       myOaa.oaaSolve(goal, solveParams, res);

       if (res.size() == 0) {
           throw new Exception("No answers found");
       }

       return res;
   }
 

Note that in the above example code the agent address is retrieved only once since this is an expensive operation. If the method callOaaMaximumPerformance is called repeatedly it will perform better than regular direct_connect without the address.

Finally, a method for detecting whether or not direct_connect was successful is possible specifying the "get_direct_connect_used" out parameter in oaaSolve. For example, if oaaSolve is called and one of the parameters is "get_direct_connect_used(_)", when the solve call returns this parameter is replaced with "get_direct_connect_used(true)" if direct_connect was successfull and "get_direct_connect_used(false)" if direct_connect was not used or was not successfull.

Registering the agent

Once a low-level communication connection has been established, an agent registers its name and published services across this connection. In this example, the agent named "fax_db" publishes that it can provide the service of finding a fax number given a person name. The default connection name for comConnect() and oaaRegister() should be "parent", which represents the Facilitator agent.

     // Then, once the connection is established, performs handshaking with the facilitator
     if (!myOaa.oaaRegister("parent", "fax_db", IclTerm.fromString("[fax_num(Person,Num)]"))) {
     printError("Could not register");
     return;
     }
  

When the agent has finished all initializations and is ready to receive requests from the agent community, it must let the Facilitator know that it is ready.

     myOaa.oaaReady(true);
  

That's it! Incoming requests will arrive in the function myOAADoEvent(goal, params, answers); where the agent will parse the goal, try to solve the request, and return 0 (failure), 1 (success), or more solutions in the answers list. To accomplish the goal, the agent may need to make use of communication requests to other members in the agent community using the oaaSolve() or other library functions.

Disconnecting the agent

The agent can disconnect all connections by invoking the oaaDisconnect method.

Event communication patterns for OAA primitives

Asynchronous communication events between client agents and a facilitator are at the heart of the agent library and facilitator implementations. Here we describe the communication message activity for the OAA primitives defined in an OAA library.

  
Handshaking between Client and Facilitator at startup time:

   oaaRegister(ConnectionId, AgentName, Solvables, Params) 
      client->Fac:  ev_connect(AgentInfoList)
      client<-Fac:  ev_connected(FacInfoList)
 

  
Notification to facilitator that client is ready to participate:
   oaaReady(ShouldPrint)              
      client->Fac:  ev_ready(SymbolicName)
 

  
Registration of client solvables and data declaractions with Facilitator:
   oaaDeclare(Solvs,CPerms,CParams,Params,-Declared),    
   oaaUndeclare(Solvs,Params,-Undeclared),      
   oaaRedeclare(Solvs,Params,-Redeclared),      
   oaaDeclareData(Solvs,CPerms,CParams,Params,-Declared)  
      client->Fac:  ev_post_declare(Mode,Solvs,P)  Mode = add,remove,replace
      if client agent is a NODE facilitator
        node->parent:    ev_register_solvables(Mode,Solvs,MyName,P)
      client<-Fac:  ev_reply_declared(Mode, Solvs, P, Declared)
 

  
Delegation of simple or compound goals across agent community:
   oaaSolve(G,P)                      
      client->Fac:  ev_solve(GoalId, G,P)
      If no clients can solve G
        Fac->Parent:    ev_post_solve_from_fac(Id, G, P)
        Fac<-Parent:    ev_reply_solved_by_fac(Id, S, G, P,Sols)
      else
        Fac->client:    ev_solve(GoalId, G, P)
        Fac<-client:    ev_solved(Id, Requestees, Solvers, G, P, Solutions)
        client<-Fac:   ev_solved(GoalId, Responders, S, G, P, Sols)
 

  
Delegation/manipulation of data across agent community:
   oaaAddData(D,P),      
   oaaRemoveData(D,P),  
   oaaReplaceData(D,P)  
      client->Fac:  ev_update_data(GoalId,Mode,D,P)  Mode = add,remove,replace
      Fac->client:    ev_update_data(GoalId, Mode, D, P),
      Fac<-client:    ev_data_updated(GoalId, Mode, D, P, Sols)
      client<-Fac:  ev_data_updated(GoalId, Mode, D, P, Responders, Sols)
 

  
Installation/removal of triggers delegated across agent community:
   oaaAddTrigger(D,P), oaaRemoveTrigger(D,P)    
      client->Fac:  ev_update_trigger(GoalId,Mode,T,C,A,P)  Mode = add,remove
      Fac->client:    ev_update_trigger(GId, Mode,T,C,A,P),
      Fac<-client:    ev_trigger_updated(Id,Mode,T,C,A,P,Requestees,Updaters)
      client<-Fac:  ev_trigger_updated(Id,Mode,T,C,A,P,Requestees,Updaters)
 

Field Summary

static java.lang.String	oaa_library_language Deprecated. Use LibOaa.getLibraryLanguage()
static IclTerm	oaa_library_release Deprecated. Use LibOaa.oaa_library_version
static IclTerm	oaa_library_version Deprecated. Use getLibraryVersion()
static java.lang.String	OAA_LOG_CONFIG_FILE Property name for the OAA library log4j configuration file.
static java.lang.String	OAA_LOG_CONFIG_FILE_DEFAULT Default property value for the OAA library log4j configuration file.
IclDb	prologDatabase To store the current agent's pieces of data.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

LibOaa(LibCom inLibCom)
LibOaa contains all functions necessary to create an agent for the Open Agent Architecture.

Method Summary

void	checkForExpiredEvents()
static void	configureLoggerFromXMLStream(java.io.InputStream inStream, boolean override) Allows the OAA logger to be configured from the specified stream.
static void	configureLoggerFromXMLStreamIfNecessary(java.io.InputStream inStream) Allows the OAA logger to be configured from the specified stream.
LibCom	getComLib() Returns the communications library defined at startup in the constructor.
static long	getCurrMilliTime()
static java.lang.String	getLibraryLanguage() Get the language in which this library was written
static IclTerm	getLibraryVersion() Return a copy of the library version IclTerm.
IclTerm	icl_minimally_instantiate_solvables(IclTerm shorthandSolvables) Loop to call minimally_instantiate_solvable
boolean	icl_name(IclTerm term) Is term is a valid address name.
IclTerm	icl_readable_solvable(IclTerm standardSolvable) Convert a single solvable into shorthand notation.
IclTerm	icl_readable_solvables(IclTerm standardSolvables) This is provided for use in "pretty-printing" solvables, in trace messages, etc.
IclTerm	icl_standardize_address(IclTerm addr) Standardizes an address or address list.
IclTerm	icl_standardize_solvable(IclTerm shorthand) From shorthand form into standard.
IclTerm	icl_standardize_solvables(IclTerm shorthandSolvables) From shorthand form into standard.
boolean	iclBasicGoal(IclTerm goal) Test whether an expression is an ICL basic (non-compound) goal; that is, just a functor with 0 or more arguments.
boolean	iclBuiltin(IclTerm goal) Test whether an expression is an ICL built-in goal.
boolean	iclCompoundGoal(IclTerm goal) Test whether an expression is an ICL compound goal.
IclTerm	iclConvertSolvables(boolean toStandard, IclTerm inSolvables) Convert between shorthand and standard forms of solvables list.
IclTerm	iclGetNestedParamValue(IclTerm subParam, IclTerm param, IclTerm paramList) icl_GetNestedParamValue(+SubParam, +Param, +ParamList).
IclTerm	iclGetParamValue(IclTerm param, IclTerm paramList) Extracts or tests the value of a parameter list, using defaults.
IclTerm	iclGetPermValue(IclTerm perm, IclTerm permList) To get or test the value of a parameter that has a default, it is best to call iclGetPermValue.
IclTerm[]	iclGoalComponents(IclTerm fullGoal) Assemble, disassemble, or match against the top-level components of an ICL goal.
static void	libInit() Initialize the OAA library.
static boolean	memberchk(IclTerm elt, IclTerm aList) Searches for elt in a list .
boolean	oaaAddData(IclTerm clause, IclList params) Add a new fact for a data solvable to a publicly writable or private data solvable of this agent, or to a publicly writable data solvable of another agent.
boolean	oaaAddDelayedContextParams(int Id, IclTerm Params, IclTerm NewParams) When a goal is delayed using oaaDelaySolution(), incoming context parameters from the original request can not be automatically concatenated to outgoing oaaSolve requests -- since an agent can manage multiple delayed goals at the same time, liboaa doesn't know the correct context for the outgoing oaaSolve without explicit direction from the programmer.
IclList	oaaAddress(java.lang.String connectionId, IclTerm Type) Returns (one of more) Addresses for this agent.
void	oaaAddToCache(IclTerm Goal, IclTerm Solutions) Add each solution to goal one at a time so we can retrieve solutions later using findall.
boolean	oaaAddTrigger(IclStr Type, IclTerm Condition, IclTerm Action, IclTerm InitialParams) Adds a trigger according to parameters.
IclTerm	oaaCanSolve(IclTerm goal) Asks the Facilitator for a list of agents which could solve a Goal
void	oaaCheckTriggers(java.lang.String Type, IclTerm Condition, java.lang.String Op) Given a trigger type, a mask and an Op (e.g.
boolean	oaaClass(java.lang.String inClass) Return the class (leaf, node, root) of the current agent
void	oaaClearCache() Clear the cache
void	oaaComTraceMsg(java.lang.String inMessage) If com trace mode is on, display message and arguments
boolean	oaaConnect(java.lang.String connectionID, IclTerm address, java.lang.String initialAgentName, IclList params) Connect and handshake with the agent listening on Address, or, if Address is a var, allow com_Connect to find the address.
IclTerm	oaaDeclare(IclTerm solvable, IclTerm initialCommonPerms, IclTerm initialCommonParams, IclTerm initialParams) Register the declaration of new procedure or data solvables for a client or facilitator on its parent facilitator.
boolean	oaaDelaySolution(java.lang.String Id) Requests that the current app_do_event function not return solutions to the current goal until a later time.
boolean	oaaDisconnect(IclList params) Disconnect all connections between client agent and Facilitator.
boolean	oaaDisconnect(java.lang.String connectionId, IclList params) Disconnect the connection between client agent and Facilitator at ConnectionId.
IclTerm	oaaGetEvent(int lowestPriority, IclTerm inEvent) Return the next event to execute, and the parameters associated with the event.
IclTerm	oaaGetEventAtLeast(int lowestPriority, IclTerm inEvent)
boolean	oaaInCache(IclTerm goal, IclTerm answers) Retrieve solutions from the cache if the goal we are asking for is properly contained in the cache (check subsumption)
void	oaaInform(java.lang.String TypeInfo, java.lang.String FormatString) Sends a typed message to interested agents
boolean	oaaInterpret(IclTerm expression, IclList params)
boolean	oaaInterpret(IclTerm expression, IclList params, IclList inSolutions) oaaIntepret in the Prolog library provides an interpreter for ICL expressions.
boolean	oaaIsConnected(java.lang.String connectionId) Determines whether the client-Facilitator connection at connectionId is valid and is connected.
void	oaaMainLoop(boolean ShouldPrint) The main event loop for the application.
java.lang.String	oaaName() Return the name of the current agent
float	oaaPing(IclTerm AgentAddr, float TimeLimit) Tests whether a given agent is currently responding to requests.
void	oaaPostEvent(IclTerm inContents, IclTerm inParams) Sends a single low-level event message to another agent.
IclTerm	oaaPrimaryAddress() name: oaaPrimaryAddress(MyAddress) purpose: Returns the primary address for this agent.
IclTerm	oaaPrimaryId() name: oaaPrimaryId(MyId) purpose: Returns the primary id for this agent.
void	oaaPrintDelayTable() Prints out the current table of delayed events
void	oaaProcessEvent(IclTerm event, IclList params) Interprets an incoming event - For a timeout, checks task triggers and calls user's idle procedure - Otherwise, oaaInterprets the event, checks on_receive comm triggers, and then checks task triggers.
void	oaaReady(boolean shouldPrint) Changes the agent's 'open' status to 'ready', indicating that the agent is now ready to receive message.
void	oaaRedeclare(IclTerm InitialSolvable, IclTerm InitialNewSolvable, IclTerm InitialParams) Replace a solvable on a client or facilitator, and inform the parent if appropriate.
boolean	oaaRegister(java.lang.String connectionId, java.lang.String agentName, IclTerm solvables, IclList params) Registers a client's name and capabilities declarations (solvables) with the Facilitator found at ConnectionId.
void	oaaRegisterCallback(java.lang.String callbackId, OAAEventListener listener) Declare an application-defined method to be invoked by the LibOaa when a key, well-known event (CallbackId) occurs during execution.
boolean	oaaRemoveData(IclTerm clause, IclList params) Remove an existing fact for a data solvable from a publicly writable or private data solvable of this agent, or from a publicly writable data solvable of another agent.
boolean	oaaRemoveTrigger(IclStr Type, IclTerm Condition, IclTerm Action, IclTerm InitialParams) Removes a trigger from a local or remote agent
boolean	oaaReplaceData(IclTerm clause1, IclTerm clause2, IclList params) Replace an existing fact for a data solvable from a publicly writable or private data solvable of this agent, or from a publicly writable data solvable of another agent.
boolean	oaaReturnDelayedSolutions(java.lang.String Id, IclTerm SolutionList) Provide solutions for a previously delayed solution.
boolean	oaaSetupCommunication(java.lang.String initialAgentName) Establishes default communications connections for a client agent.
boolean	oaaSolve(IclTerm goal, IclList params, IclList answers) Request that Goal be solved by one or more agents and the resulting solution(s) returned.
void	oaaTraceMsg(java.lang.String inMessage) If trace mode is on, display message and arguments
IclTerm	oaaUndeclare(IclTerm solvable, IclTerm initialParams) Remove an agent's solvables from a client or facilitator, or remove writable data solvables that exist on the parent facilitator.
IclList	oaaVersion(IclTerm agentAddr) Lookup the language and library version number for an agent.
void	run()
void	setExitOnEvHalt(boolean exit) By default LibOaa will call System.exit when the ev_halt event is received.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

OAA_LOG_CONFIG_FILE

public static final java.lang.String OAA_LOG_CONFIG_FILE

Property name for the OAA library log4j configuration file.

See Also:

Constant Field Values

OAA_LOG_CONFIG_FILE_DEFAULT

public static final java.lang.String OAA_LOG_CONFIG_FILE_DEFAULT

Default property value for the OAA library log4j configuration file.

See Also:

Constant Field Values

oaa_library_language

public static final java.lang.String oaa_library_language

Deprecated. Use LibOaa.getLibraryLanguage()

See Also:

Constant Field Values

oaa_library_version

public static final IclTerm oaa_library_version

Deprecated. Use getLibraryVersion()

Current version of the OAA agent library

oaa_library_release

public static final IclTerm oaa_library_release

Deprecated. Use LibOaa.oaa_library_version

prologDatabase

public IclDb prologDatabase

To store the current agent's pieces of data. In the prolog version, agent's data are directly stored as facts.

Constructor Detail

LibOaa

public LibOaa(LibCom inLibCom)

LibOaa contains all functions necessary to create an agent for the Open Agent Architecture. A LibOaa class is created with a communications object that will provide the networking to allow the agent to connect and communicate with a Facilitator agent. The LibCom object is most often initiallized using LibComTcpProtocol to act as the transport layer for communication.

Parameters:

inLibCom - Communications library to use for this agent

See Also:

LibCom, LibComTcpProtocol

Method Detail

configureLoggerFromXMLStreamIfNecessary

public static void configureLoggerFromXMLStreamIfNecessary(java.io.InputStream inStream)

Allows the OAA logger to be configured from the specified stream.

This method is similar to the configureLoggerFromXMLStream method, with the difference that existing configuration will be modified to the new configuration only if the logger was never configured before. This is the default case, and is used when we want to try several different configuration methods in order of priority.

This method is always invoked from the following two places in the LibOaa class.

• The static initializer which attempts to read the file from:
  • the location specified by the system property oaa.log.config.file.
  • the default system resource of com/sri/oaa2/oaa_log_config.xml.
• The default constructor which, if the static initializer did not work, reads the file from the resource (note that the static initializer had to use the system resource) of com/sri/oaa2/oaa_log_config.xml

The addition of the call from the default constructor allows this class to be used in contexts other than a privileged java application with access to system resources. For example, LibOaa can now be used in an applet or as part of RMI as well.

configureLoggerFromXMLStream

public static void configureLoggerFromXMLStream(java.io.InputStream inStream,
                                                boolean override)

Allows the OAA logger to be configured from the specified stream.

This is used by LibOaa to try to configure the logger from several standard places. The users of LibOaa can configure the logger from other locations (such as a website) as well.

Parameters:

inStream - The stream to read the XML file from. As usual, most OS streams (FileInputStream...) should be wrapped by a BufferedInputStream before being passed in here.

override - Controls whether the configuration should be always overridden or not.

The truth table for whether the configuration will be overridden or not is

Override	isLoggingConfigured	Operation
true	Don't care	Configure
false	true	Ignore
false	false	Configure

Note that this method is thread-safe since it's synchronized.

getLibraryLanguage

public static java.lang.String getLibraryLanguage()

Get the language in which this library was written

getLibraryVersion

public static IclTerm getLibraryVersion()

Return a copy of the library version IclTerm.

libInit

public static void libInit()

Initialize the OAA library. This is currently a no-op; it is a placeholder for future functionality.

getComLib

public final LibCom getComLib()

Returns the communications library defined at startup in the constructor.

Returns:

the communications library defined at startup in the constructor

oaaSetupCommunication

public boolean oaaSetupCommunication(java.lang.String initialAgentName)

Establishes default communications connections for a client agent.

Remarks:

• If oaa_listen argument is given, opens a listener socket, so the client can handle requests by direct connection.
• IAttempts to connect to facilitator at address indicated by oaa_connect or default_facilitator parameter in command line, environment variable, or setup file (see com_Connect, in com_tcp.pl).
• Icom_Connect (which see) provides some retry options.
• IFAILS if connection to the facilitator cannot be established, and prints a simple error message.
• IAfter performing local initializations, and calling this procedure, the default client agent should also call oaa_MainLoop(true).

Parameters:

initialAgentName - the agent name

Returns:

true if successful, false otherwise

oaaConnect

public boolean oaaConnect(java.lang.String connectionID,
                          IclTerm address,
                          java.lang.String initialAgentName,
                          IclList params)

Connect and handshake with the agent listening on Address, or, if Address is a var, allow com_Connect to find the address.

Parameters:

connectionID - the connection id to use

address - the address in icl to connect to

initialAgentName - the name of the agent

params - parameters to use when connecting

Returns:

true if the connection was successful and false if an error occurred.

oaaDisconnect

public final boolean oaaDisconnect(java.lang.String connectionId,
                                   IclList params)

Disconnect the connection between client agent and Facilitator at ConnectionId.

It is strongly suggested that oaaDisconnect be called directly rather than comDisconnect as the former performs other client clean-up activities necessary for proper shutdown of a connection.

Parameters:

connectionId - the Java String that specifies the name of the Facilitator connection.

params - a list of IclTerms which indicate options for performing the disconnection. At present, only one parameter is recognized, TBD. It signals to the Facilitator that the client is temporarily disconnecting (e.g., robot out of range, or PDA temporarily off line). Future service requests received by the Facilitator for the disconnected client will be queued by the Facilitator and delivered upon reconnection.

Returns:

true if the connection exists and was disconnected, and false otherwise.

See Also:

LibCom.comDisconnect(java.lang.String, com.sri.oaa2.icl.IclList), LibCom.comConnect(java.lang.String, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList)

oaaDisconnect

public final boolean oaaDisconnect(IclList params)

Disconnect all connections between client agent and Facilitator. All direct_connect connections are also disconnected.

It is strongly suggested that oaaDisconnect be called directly rather than comDisconnect as the former performs other client clean-up activities necessary for proper shutdown of a connection.

Parameters:

params - a list of IclTerms which indicate options for performing the disconnection. At present, only one parameter is recognized, TBD. It signals to the Facilitator that the client is temporarily disconnecting (e.g., robot out of range, or PDA temporarily off line). Future service requests received by the Facilitator for the disconnected client will be queued by the Facilitator and delivered upon reconnection.

Returns:

true if any connections were disconnected, and false if no connections were disconnected or an error occurred.

See Also:

LibCom.comDisconnect(java.lang.String, com.sri.oaa2.icl.IclList), LibCom.comConnect(java.lang.String, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList)

oaaRegister

public final boolean oaaRegister(java.lang.String connectionId,
                                 java.lang.String agentName,
                                 IclTerm solvables,
                                 IclList params)

Registers a client's name and capabilities declarations (solvables) with the Facilitator found at ConnectionId. This step is to be performed after a client agent successfully connects to a Facilitator agent using comConnect().

The actions described below provide a view of how oaaRegister() is implemented; these are NOT actions for a client agent to perform separately.

The registration process involves handshaking (i.e., an exchange of messages) between the client and Facilitator. The client sends a message containing its name, OAA library version, and implementation language. The Facilitator returns information about itself including:

     Facilitator name: symbolic name of the Facilitator
     OAA version: version number of the agent library used to construct the facilitator
     Language: facilitator's implementation language
     Client local id: a numeric identifier for this client assigned by the Facilitator
     Facilitator local id: a numerid identifier for the Facilitator to be used by this client
 

The client agent then provides its hostname (as retrieved from environment variable 'HOST') to the Facilitator using oaaAddData(). As the last step in the registration process, the client declares its solvables to the Facilitator using oaaDeclare().

Parameters:

connectionId - a Java String that specifies the name of the Facilitator connection ('parent' for the Prolog implementation and "parent" for Java implementation).

agentName - a symbolic name representing the agent, e.g., 'email'.

solvables - a list of capabilities or data definitions (solvables ) for this client. For example, [send(email,ToWhom,Params)].

params - parameters to register, if any

Returns:

true if registration was successful, or false if the connection between client and Facilitator is not open or if the registration otherwise fails.

See Also:

LibCom.comConnect(java.lang.String, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList), oaaRegisterCallback(java.lang.String, com.sri.oaa2.lib.OAAEventListener), oaaMainLoop(boolean), oaaDisconnect(java.lang.String, com.sri.oaa2.icl.IclList)

oaaReady

public final void oaaReady(boolean shouldPrint)

Changes the agent's 'open' status to 'ready', indicating that the agent is now ready to receive message.

Parameters:

shouldPrint - if true, prints 'Ready' to standard out.

iclBuiltin

public final boolean iclBuiltin(IclTerm goal)

Test whether an expression is an ICL built-in goal.

iclBuiltIn() differs significantly from the Quintus Prolog predicate built_in, in that here we do not include basic constructors such as ',' and ';'.

oaaInterpret/2 must be defined for every goal for which icl_BuiltIn succeeds.

See Also:

oaaInterpret(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList, com.sri.oaa2.icl.IclList)

iclBasicGoal

public final boolean iclBasicGoal(IclTerm goal)

Test whether an expression is an ICL basic (non-compound) goal; that is, just a functor with 0 or more arguments.

Basic goals include built-in's as well as solvables.

This is a syntactic test; that is, we're not checking whether the Goal is a declared solvable.

Parameters:

goal - A term to test

See Also:

iclCompoundGoal(com.sri.oaa2.icl.IclTerm)

iclCompoundGoal

public final boolean iclCompoundGoal(IclTerm goal)

Test whether an expression is an ICL compound goal.

Parameters:

goal - A term to test

See Also:

iclCompoundGoal(com.sri.oaa2.icl.IclTerm)

iclGoalComponents

public final IclTerm[] iclGoalComponents(IclTerm fullGoal)

Assemble, disassemble, or match against the top-level components of an ICL goal.

 name:  iclGoalComponents(+ICLGoal, -A, -G, -P).
      iclGoalComponents(-ICLGoal, +A, +G, +P).
      iclGoalComponents(+ICLGoal, +A, +G, +P).
  The top-level structure of an ICL goal is Address:Goal::Params,
  with Address and Params BOTH OPTIONAL.  Thus, every ICL goal
  either explicitly or implicitly includes all three components.
 

This may be used with any ICL goal, basic or compound. When P is missing, its value is returned or matched as []. When A is missing, its value is returned or matched as 'unknown'.

Returns:

An array of ICLTerms representing the parts of the goal.

• array[0] : Address
• array[1] : Goal
• array[2] : Param

iclGetParamValue

public final IclTerm iclGetParamValue(IclTerm param,
                                      IclTerm paramList)

Extracts or tests the value of a parameter list, using defaults.

To simply extractFor a parameter that has no default, you can use iclGetParamValue OR memberchk.

Param must be a partially or fully-instantiated structure (atom form will not work)

Examples

 1)
    param : priority(P)
    paramList : [priority(5), param(2)]

    return : priority(5)

 2)
    param : priority(P)
    paramList : [level(5), param(2)]

    return : priority(5) // Default value since not in list
 

iclGetNestedParamValue

public final IclTerm iclGetNestedParamValue(IclTerm subParam,
                                            IclTerm param,
                                            IclTerm paramList)

icl_GetNestedParamValue(+SubParam, +Param, +ParamList). Use this when the value of a parameter is ITSELF a param list, as with the propagate parameter. For example: Given param list Params = [propagate([up(true)])], Use icl_GetNestedParamValue(up(U), propagate, Params) to get U = true.

memberchk

public static final boolean memberchk(IclTerm elt,
                                      IclTerm aList)

Searches for elt in a list .

Parameters:

elt - A term to search for

aList - A list to search in

Returns:

TRUE if elt is contained in aList

iclGetPermValue

public final IclTerm iclGetPermValue(IclTerm perm,
                                     IclTerm permList)

To get or test the value of a parameter that has a default, it is best to call iclGetPermValue.

For a parameter that has no default, you can use iclGetPermValue OR memberchk.

Perm must be a partially- or fully-instantiated structure (atom form will not work)

Parameters:

perm - A permission type

permList - A permission list to search in

Returns:

true if passes the permission check

icl_standardize_address

public final IclTerm icl_standardize_address(IclTerm addr)

Standardizes an address or address list. Can only be used after oaaRegister() because of the reliance on comGetInfo()

Parameters:

addr - An address

Returns:

Address in standard form

icl_name

public final boolean icl_name(IclTerm term)

Is term is a valid address name. Any atom except for "parent", "self" or "facilitator" may be a name

Parameters:

term - the input term

Returns:

Returns TRUE if term is a valid address name

iclConvertSolvables

public final IclTerm iclConvertSolvables(boolean toStandard,
                                         IclTerm inSolvables)

Convert between shorthand and standard forms of solvables list.

     - In the standard form, each element is a term solvable(Goal,
     Params, Permissions), with Permissions and Params both lists.
     In the Permissions and Params lists, values appear only when they
     are OTHER than the default.
     - In the shorthand form, each element can be solvable/3, as above,
     or solvable(Goal, Params), or solvable(Goal), or just Goal.
     - Note that "shorthand" means "anything goes" - so shorthand
     solvables are a superset of standard solvables.
     - Permissions (defaults in square brackets):
       call(T_F) [true], read(T_F) [false], write(T_F) [false]
     - Params (defaults in square brackets):
       type(Data_Procedure) [procedure],
       callback(Functor) [user:app_do_event]
       utility(N) [5]
       synonym(SynonymHead, RealHead) [none]
       rules_ok(T_F) [false],
       single_value(T_F) [false],
       unique_values(T_F) [false],
       private(T_F) [false]
       bookkeeping(T_F) [true]
       persistent(T_F) [false]
     - Refer to Agent Library Reference Manual for details on Permissions
     and Params.
     - (@@DLM) This might be the place to check the validity of solvables,
     such as using only built-ins in tests.  Also, check for dependencies
     between solvables; e.g., when persistent(false) is there,
     bookkeeping(true) must also be there.
  An additional arg (toStandard) is added to
  distinguish between the two calling conventions and the function returns
  the converted solvable list
   ShorthandSolvables iclConvertSolvables(TRUE, StandardSolvables).
   StandardSolvables iclConvertSolvables(FALSE, ShorthandSolvables).
 

icl_standardize_solvable

public final IclTerm icl_standardize_solvable(IclTerm shorthand)

From shorthand form into standard. For a single solvable. shorthand could be of : Goal (Form1) solvable(Goal) (Form2) solvable(Goal,Params) (Form3) solvable(Goal,Params,Perms) (Form4)

icl_standardize_solvables

public final IclTerm icl_standardize_solvables(IclTerm shorthandSolvables)

From shorthand form into standard. For a list of solvables.

icl_readable_solvable

public final IclTerm icl_readable_solvable(IclTerm standardSolvable)

Convert a single solvable into shorthand notation.

    icl_readable_solvable(solvable(Goal, [], []), Goal).
    icl_readable_solvable(solvable(Goal,Params,[]),solvable(Goal,Params)).
    icl_readable_solvable(solvable(Goal, Params, Perms),
             solvable(Goal, Params, Perms)).
 

icl_readable_solvables

public final IclTerm icl_readable_solvables(IclTerm standardSolvables)

This is provided for use in "pretty-printing" solvables, in trace messages, etc.

icl_minimally_instantiate_solvables

public final IclTerm icl_minimally_instantiate_solvables(IclTerm shorthandSolvables)

Loop to call minimally_instantiate_solvable

oaaMainLoop

public final void oaaMainLoop(boolean ShouldPrint)

The main event loop for the application.

oaaMainLoop() first calls oaaReady(ShouldPrint), to let the Facilitator know that the agent is ready to receive events. Next, the main event loop for the application is run. It

• Reads an event using oaaGetEvent()
• Executes the event using oaaInterpret()
• Checks for and fires any triggers registered expressing interest in this communication reception event.
• Checks for and fires any application task triggers

If a timeout occurs waiting for an event (see oaaSetTimeout), the callback registered under "oaa_app_idle" (see oaaRegisterCallback) is called.

See Also:

oaaGetEvent(int, com.sri.oaa2.icl.IclTerm), oaaInterpret(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList, com.sri.oaa2.icl.IclList), oaaRegisterCallback(java.lang.String, com.sri.oaa2.lib.OAAEventListener)

run

public final void run()

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

oaaProcessEvent

public final void oaaProcessEvent(IclTerm event,
                                  IclList params)

Interprets an incoming event - For a timeout, checks task triggers and calls user's idle procedure - Otherwise, oaaInterprets the event, checks on_receive comm triggers, and then checks task triggers.

oaaGetEventAtLeast

public final IclTerm oaaGetEventAtLeast(int lowestPriority,
                                        IclTerm inEvent)

checkForExpiredEvents

public void checkForExpiredEvents()

oaaGetEvent

public final IclTerm oaaGetEvent(int lowestPriority,
                                 IclTerm inEvent)

Return the next event to execute, and the parameters associated with the event. If a timeout value has been set by oaaSetTimeout (for console-based agent libraries), and no event arrives or is in the event queue by the specified time, the 'timeout' event is returned.

oaaGetEvent keeps a queue of incoming events. When oaaGetEvent() is called any waiting events are read from the input stream and added to the current event queue; the queue is then sorted according to priority, and the the first event in the queue which has a priority greater than the requested LowestPriority parameter is returned.

If the debug flag ComTraceOn has been set for the agent, a trace message describing the arriving event is displayed.

oaaInterpret

public final boolean oaaInterpret(IclTerm expression,
                                  IclList params,
                                  IclList inSolutions)

oaaIntepret in the Prolog library provides an interpreter for ICL expressions. Currently in Java, ICL requests can only be simple (unitary) goal, and no Prolog builtin values are provided. While this may be improved eventually by coding a full Prolog interpreter in Java, oaaInterpret currently just passes the goal (after some checking) to oaa_exec_event which will evaluate a simple goal by testing some built-in agent message handler functions, and then, if appropriate, pass the goal to a user-defined callback for processing.

oaaInterpret

public final boolean oaaInterpret(IclTerm expression,
                                  IclList params)

setExitOnEvHalt

public void setExitOnEvHalt(boolean exit)

By default LibOaa will call System.exit when the ev_halt event is received. There are some cases where this is not desireable (ex: dotnetproxy). This method can be called with a false parameter value to disable calling System.exit when ev_halt is received.

Parameters:

exit - true if LibOaa should call System.exit when ev_halt is received, and false otherwise.

oaaPrintDelayTable

public final void oaaPrintDelayTable()

Prints out the current table of delayed events

oaaDelaySolution

public final boolean oaaDelaySolution(java.lang.String Id)

Requests that the current app_do_event function not return solutions to the current goal until a later time. This must only be called from an OAA callback that resulted from an external solve request. It must not be used on trigger callbacks. It must be done in the same thread (of course, since otherwise, we can't know which solution to delay).

Parameters:

Id - an Id which will be used to later match solutions to request

Returns:

false if the specified Id is not unique among currently delayed goals or if called from an invalid context

oaaReturnDelayedSolutions

public final boolean oaaReturnDelayedSolutions(java.lang.String Id,
                                               IclTerm SolutionList)

Provide solutions for a previously delayed solution. This method may block while waiting for the delay information from a prior oaaDelaySolution(...) call.

Parameters:

Id - an Id referring to a previously saved oaaDelaySolution

SolutionList - List of answers for the saved goal

Returns:

false if delayed ID can't be found or if we are interrupted while blocking on the delay information

oaaAddDelayedContextParams

public final boolean oaaAddDelayedContextParams(int Id,
                                                IclTerm Params,
                                                IclTerm NewParams)

When a goal is delayed using oaaDelaySolution(), incoming context parameters from the original request can not be automatically concatenated to outgoing oaaSolve requests -- since an agent can manage multiple delayed goals at the same time, liboaa doesn't know the correct context for the outgoing oaaSolve without explicit direction from the programmer. Hence, an agent programmer who wants to call oaaSolve during a delayed goal is expected to use this function to add the saved contexts for the delayed goal to his/her outgoing oaaSolve parameters.

Parameters:

Id - an Id which will be used to later match solutions to request

Params - Parameters for solve goal

NewParams - Params augmented by saved contexts

Returns:

example: oaaSolve(sub_goal(Y), P). oaa_AppDoEvent(final_event(S), _Params) :- oaaReturnDelayedSolutions(a_goal, [goal(S)]).

oaaPostEvent

public final void oaaPostEvent(IclTerm inContents,
                               IclTerm inParams)

Sends a single low-level event message to another agent.

oaaPostEvent is generally used within other LibOaa methods such as oaaSolve and infrequently used directly by client agent implementors. A common use when called directly is to turn debugging on and off for a remote agent using "ev_com_trace_on" and "ev_com_trace_off" respectively as the Body.

Parameters:

inContents - an IclTerm which contains the event to be sent.

inParams - is a list of parameters which provide additional information regarding the event or its handling.

The Params list may include:

• priority(P): P ranges from 1 (low priority) to 10 (high priority) with a default of 5.
• flush_events: Will flush (dispose of) all events of lower priority currently queued at the destination agent. These events are lost, and will not be executed. This parameter should be used with caution!
• address(Addr): The address of the destination agent for the event.
• connection_id(Id): The connection id of the destination agent for the event.
• from(Id): The address Id of the originating agent.

See Also:

oaaGetEvent(int, com.sri.oaa2.icl.IclTerm)

oaaVersion

public final IclList oaaVersion(IclTerm agentAddr)

Lookup the language and library version number for an agent. The default version (if unspecified) is 1.0. Returns an IclList whose elements are : List[1] = Language List[2] = Version

oaaCanSolve

public final IclTerm oaaCanSolve(IclTerm goal)

Asks the Facilitator for a list of agents which could solve a Goal

oaaPing

public final float oaaPing(IclTerm AgentAddr,
                           float TimeLimit)

Tests whether a given agent is currently responding to requests.

Parameters:

AgentAddr - address of agent to test

TimeLimit - Time limit (in seconds) for how long to wait for a response

Returns:

TotalResponseTime for round trip (in seconds).Returns -1.0 if a ping is not returned in TimeLimit amount of time

oaaDeclare

public final IclTerm oaaDeclare(IclTerm solvable,
                                IclTerm initialCommonPerms,
                                IclTerm initialCommonParams,
                                IclTerm initialParams)

Register the declaration of new procedure or data solvables for a client or facilitator on its parent facilitator. Inform the parent facilitator of the declaration if the client agent that is registering is a leaf of an agent hierarchy.

Client-requested facilitator solvables automatically acquire the permission write(true), and the parameters type(data), rules_ok(false), private(false), and bookkeeping(true). The CommonPermissions and CommonParams arguments are provided purely for programming convenience. The effect of including an item in these is no different than if that item were explicitly included in the permissions or params list of each element in Solvables. If called by a leaf or node agent, this procedure assumes the agent is already registered with a parent facilitator.

An attempt to declare a solvable that unifies with an existing solvable will cause a warning to be printed on standard output of the agent where the solvable exists. In addition, this solvable will not be included in DeclaredSolvables.

Parameters:

solvable - a single solvable or a list of solvables, in shorthand or standard form

initialCommonPerms - a list of permissions to be distributed to each solvable.

initialCommonParams - a list of parameters to be distributed to each solvable.

initialParams - may be an empty list or include one or more of the following: address(X): Where the solvables will exist. X may be either 'self,' 'parent,' or their local ids. Default: 'self'. if_exists(X): What to do when declaring solvables for self, and some already exist. X may be 'overwrite' or 'append'. 'overwrite' means to discard all existing solvables and replace them with the list provided in Solvables. 'append' means to add the new solvables to the end of the existing solvables list and update any existing solvables with new values provided in Solvables. Default: 'append'.

Returns:

an IclTerm which contains a list in standard form of all solvables successfully declared.

See Also:

oaaDeclare(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm), oaaUndeclare(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm), oaaRedeclare(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm)

oaaUndeclare

public final IclTerm oaaUndeclare(IclTerm solvable,
                                  IclTerm initialParams)

Remove an agent's solvables from a client or facilitator, or remove writable data solvables that exist on the parent facilitator. Inform the parent facilitator if appropriate.

If called by a leaf or node agent, this procedure assumes the agent is already registered with a parent facilitator. An attempt to remove a non-existent solvable will cause a warning to be printed on standard output of the agent where the solvable was supposed to exist. In addition, this solvable will not be included in UndeclaredSolvables.

See Also:

oaaDeclare(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm), oaaUndeclare(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm), oaaRedeclare(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm)

oaaRedeclare

public final void oaaRedeclare(IclTerm InitialSolvable,
                               IclTerm InitialNewSolvable,
                               IclTerm InitialParams)

Replace a solvable on a client or facilitator, and inform the parent if appropriate. If called by a leaf or node agent, assumes agent is already registered with a parent facilitator. FAILS if the operation cannot be completed.

Parameters:

InitialSolvable - A single solvable, in shorthand or standard form. If in standard form, however, ONLY the goal is considered in selecting the solvable to be replaced (permissions and parameters are ignored).

InitialNewSolvable - A single solvable, in shorthand or standard form.

oaaAddData

public final boolean oaaAddData(IclTerm clause,
                                IclList params)

Add a new fact for a data solvable to a publicly writable or private data solvable of this agent, or to a publicly writable data solvable of another agent.

Parameters:

clause - the fact to be added to the list of existing data elements for this agent.

params - a list of 0 or more of the following parameters which are used to qualify where or how the data is to be added.

• address(Addr): Send the data to a specific agent or agents. Addr is a list including 'self', 'parent', and/or the addresses of other client agents. The default (no address) behavior is the same as with oaaSolve.
• reflexive(T_F): If `true', the Facilitator will consider the originating agent when choosing agents to solve a request. Default: true.
• at_beginning(T_F): If true, add Clause at the beginning of the list of existing data elements. If false, add Clause at the end. Default: false.
• single_value(T_F): If true, all clauses for this predicate are removed before adding the new clause. Default: false.
• unique_values(T_F): If true, at most one copy of each value is stored. Default: false.
• owner(LocalId): If bookkeeping(true) for this solvable, record LocalId as the owner. Default: record the Id for the agent from which the request originated.
• get_address(X): Return a list of addresses (ids) of agents that were sent the request.
• get_satisfiers(X): Return a list of addresses (ids) of agents that successfully completed the request.
• reply(Mode): If 'true', generate a reply message when data is being added on a remote agent or agents. If 'none', no reply needed. Default: true. Note that 'none' is used here instead of false, because we anticipate future use of additional values.
• block(Mode) : If true, block until the reply arrives. If false, don't block. In this case, the reply events (ev_reply_data_updated) can be handled in the app_do_event callback. Default: true. Note that reply(none) overrides block(true).

Returns:

true if clause was successfully added and false otherwise.

See Also:

oaaRemoveData(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList), oaaReplaceData(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList)

oaaRemoveData

public final boolean oaaRemoveData(IclTerm clause,
                                   IclList params)

Remove an existing fact for a data solvable from a publicly writable or private data solvable of this agent, or from a publicly writable data solvable of another agent.

Parameters:

clause - the fact to be removed from the list of existing data elements for this agent.

params - a list of 0 or more of the following parameters which are used to qualify where or how the data is to be removed.

• address(X): A list including 'self', 'parent', and/or the addresses of other client agents. The default (no address) behavior is the same as with oaaSolve.
• reflexive(T_F): If true, the Facilitator will consider the originating agent when choosing agents to solve a request. Default: true.
• do_all(T_F): If true, removes all predicate values that match the Clause. Default: false (removes only the first matching fact)
• owner(LocalId): If bookkeeping(true) for this solvable, record LocalId as the owner. Default: the agent from which the request originated.
• get_address(X): Returns a list of addresses (ids) of agents that were sent the request.
• get_satisfiers(X): Returns a list of addresses (ids) of agents that successfully completed the request.
• reply(Mode): If 'true', generate a reply message when data is being removed on a remote agent or agents. If 'none', no reply needed. Default: true. Note that 'none' is used here instead of false, because we anticipate future use of additional values.
• block(Mode) : If true, block until the reply arrives. If false, don't block. In this case, the reply events (ev_reply_data_updated) can be handled in app_do_event callback. Default: true. Note that reply(none) overrides block(true).

Returns:

true if Clause was successfully removed and false otherwise.

See Also:

oaaAddData(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList), oaaReplaceData(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList)

oaaReplaceData

public final boolean oaaReplaceData(IclTerm clause1,
                                    IclTerm clause2,
                                    IclList params)

Replace an existing fact for a data solvable from a publicly writable or private data solvable of this agent, or from a publicly writable data solvable of another agent. This is done by first removing a data element that matches Clause1, and then adding Clause2.

The effect of this call is the same as that of a call to oaaRemoveData, followed by a call to oaaAddData. The difference is that the implementation of oaaReplaceData is guaranteed to be atomic; that is, for each agent that is affected by the call to oaaReplaceData, nothing can read or write that agent's data store between the occurrence of the replace and add operations.

Although Clause1 and Clause2 normally are facts of the same data solvable, this is not required to be the case. What is required is that each agent receiving the replacement request provides a data solvable that is appropriate for Clause1, and also a data solvable that is appropriate for Clause2.

Clause1 and/or Clause2 may be synonym predicates.

Clause1 and Clause2 are not required to have the same functor.

Clause1 and Clause2 may share variables.

Parameters:

clause1 - the fact to be removed from the list of existing data elements for this agent.

clause2 - the new fact to be added to the list of existing data elements for this agent.

params - a list of 0 or more of the following parameters which are used to qualify where or how the data is to be replaced.

• address(X): a list including 'self', 'parent', and/or the addresses of other client agents. The default (no address) behavior is the same as with oaaSolve and oaaAddData.
• reflexive(T_F): If true, the Facilitator will consider the originating agent when choosing agents to solve a request. Default: true.
• do_all(T_F): If true, removes all predicate values that match Clause1 Default: false (removes only the first)
• at_beginning(T_F): If true, add Clause2 at the beginning of the list of existing data elements. If false, add Clause2 at the end. Default: false. Note that this parameter is applied only if do_all is false.
• owner(LocalId): if bookkeeping(true) for this solvable, record LocalId as the owner of Clause2. Default: the agent from which the request originated.
• get_address(X): Returns a list of addresses (ids) of agents that were sent the request.
• get_satisfiers(X): Returns a list of addresses (ids) of agents that successfully completed the request.
• reply(Mode): If 'true', generate a reply message when data is being removed on a remote agent or agents. If 'none', no reply needed. Default: true. Note that 'none' is used here instead of false, because we anticipate future use of additional values.
• block(Mode): If true, block until the reply arrives. If false, don't block. In this case, the reply events (ev_reply_data_updated) can be handled in app_do_event callback. Default: true. Note that reply(none) overrides block(true).

Returns:

true if Clause was successfully replaced and false otherwise.

See Also:

oaaAddData(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList), oaaRemoveData(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList)

oaaName

public final java.lang.String oaaName()

Return the name of the current agent

oaaAddress

public final IclList oaaAddress(java.lang.String connectionId,
                                IclTerm Type)

Returns (one of more) Addresses for this agent. If ConnectionId is ground, returns a single Address, relative to that connection. Behavior : If connection Id is not null, the function returns a single answer for this specific connection. If the connection bound to the incoming Id not valid, (not actually connected), returns "no_address" and prints out a warning. If connection Id is null, returns all the addresses of the currently valid connections.

oaaPrimaryAddress

public final IclTerm oaaPrimaryAddress()

name: oaaPrimaryAddress(MyAddress) purpose: Returns the primary address for this agent.

oaaPrimaryId

public final IclTerm oaaPrimaryId()

name: oaaPrimaryId(MyId) purpose: Returns the primary id for this agent.

oaaClass

public final boolean oaaClass(java.lang.String inClass)

Return the class (leaf, node, root) of the current agent

oaaCheckTriggers

public final void oaaCheckTriggers(java.lang.String Type,
                                   IclTerm Condition,
                                   java.lang.String Op)

Given a trigger type, a mask and an Op (e.g. [send, receive], [add, remove], etc), see if any triggers fire.

oaaAddTrigger

public final boolean oaaAddTrigger(IclStr Type,
                                   IclTerm Condition,
                                   IclTerm Action,
                                   IclTerm InitialParams)

Adds a trigger according to parameters.

 Type  =  comm, data, task, time
 Condition=  comm:event to match,
        data:data to match,
        task:solvable to call
        time:@@
 Action  =  Can be any of these:
        oaa_Solve(Goal, Params)
        oaa_Interpret(Goal, Params)
        Goal [passed to oaaInterpret with default params]

 Params  =

    address(X):  a list including 'self', 'parent', and/or the addresses of other client agents.
            Default: see below.

    test(T):    additional tests before trigger will fire [@@needs work?]
    on(OP):    operation check: on(add), on(remove), on(receive), etc.
    recurrence(R):  when, whenever, or integer (# of times to execute)
    reply({true,none}): When a trigger is being added on a remote agent or agents,
              this tells whether reply message(s) are desired.
    block(Mode):  true: Block until the reply arrives.
            false: Don't block.  In this case, the reply events can be handled
            by the user's app_do_event callback
            default: true.  Note that reply(none) overrides block(true).
    get_address(X): Returns a list of addresses (ids) of agents that  were sent the request.
    get_satisfiers(X): Returns a list of addresses (ids) of agents that successfully completed
               the request.

 Default destination for triggers:
    Data triggers:    all agents with solvables matching the Condition field.
    All other types:  the local agent
 

oaaRemoveTrigger

public final boolean oaaRemoveTrigger(IclStr Type,
                                      IclTerm Condition,
                                      IclTerm Action,
                                      IclTerm InitialParams)

Removes a trigger from a local or remote agent

getCurrMilliTime

public static final long getCurrMilliTime()

oaaSolve

public final boolean oaaSolve(IclTerm goal,
                              IclList params,
                              IclList answers)

Request that Goal be solved by one or more agents and the resulting solution(s) returned.

It is important to note that requesting a solution does not require that the agent specify or even know of a particular agent to handle the call. While it is possible to specify one or more agents to handle a call (and there are situations in which this is desirable), in general, it is advantageous to leave this delegation task to the Facilitator.

Parameters:

goal - a description of the service (e.g. an action or query) desired. Each goal contains calls to one or more solvables. An example of a a goal is "get_message(MessageNum, Msg)."

params - a list of 0 or more of the following parameters which are used to qualify how the goal is to be achieved and how results are to be returned.

• cache(T_F): Cache all solutions locally, and if good solutions already exist in the cache, use the local values instead of making a distributed request. Default: false.
• level_limit(N): Highest number of hierarchical levels to climb for solutions.
• address(Addr): Send the request to a specific agent or agents. If Addr is 'self', solve the goal locally
• reply(Mode): If 'true', reply desired. If 'none', no reply needed. Default: true, except when the call to oaaSolve is a trigger action, in which case it is none. Note that 'none' is used here instead of false, because we anticipate future use of additional values.
• block(T_F): If 'true', execution blocks until the solutions are received from the Facilitator. If 'false', execution continues immediately. In this case, the reply events (ev_reply_solved, ev_reply_declared, ev_reply_data_updated, ev_reply_ trigger_updated) can be handled in the app_do_event callback. Default: true, except when the call to oaaSolve is a trigger action, in which case it is false. Note that reply(none) overrides block(true).
• solution_limit(N): Limits the maximum number of solutions found to N.
• time_limit(N): Waits a maximum of N seconds before returning (failure if no solution found in time).
• context(C): Passes a context value through any subsequent solves.
• parallel_ok(T_F): If 'true' (default), multiple agents that can solve the Goal will attempt to work on it in parallel. If 'false', one agent will be selected at a time to solve the goal, until the maximum number of requested solutions (see solution_limit) is found.
• provider_limit(N): limits the maximum number of providers selected by the facilitator to N
• reflexive(T_F): If `true', the Facilitator will consider the originating agent when choosing agents to solve a request. Default: true.
• priority(P): P ranges from 1 (low priority) to 10 (high priority) with a default of 5.
• flush_events(T_F): Will flush (dispose of) all events of lower priority currently queued at the destination agent. These events are lost, and will not be executed. This parameter should be used with caution! Default: false.
• direct_connect(T_F): If true, a direct peer-peer connection will be attempted with the client.
• get_address(X): Returns a list of addresses (ids) of agents that were asked to solve the goal, or one of its subgoals.
• get_satisfiers(X): Returns a list of addresses (ids) of agents that succeeded in solving the goal, or one of its subgoals.
• get_direct_connect_used(X): Returns "true" or "false" indicating if direct_connect was actually used.
• strategy(S): Shorthand for certain combinations of the above parameters. S is one of:
• query = [parallel_ok(true)]
• action = [parallel_ok(false), solution_limit(1)]
• inform = [parallel_ok(true), reply(none)]
Default: query.

answers - the answers returned

Returns:

Solutions are returned in a list (the parameter answers). If no results are available or the agent is not connectected to the facilitator, oaaSolve will return false and the list will be empty. If one or more result is available, the list will contain them and oaaSolve will return true.

See Also:

oaaInterpret(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList, com.sri.oaa2.icl.IclList)

oaaInCache

public final boolean oaaInCache(IclTerm goal,
                                IclTerm answers)

Retrieve solutions from the cache if the goal we are asking for is properly contained in the cache (check subsumption)

oaaAddToCache

public final void oaaAddToCache(IclTerm Goal,
                                IclTerm Solutions)

Add each solution to goal one at a time so we can retrieve solutions later using findall.

oaaClearCache

public final void oaaClearCache()

Clear the cache

oaaRegisterCallback

public void oaaRegisterCallback(java.lang.String callbackId,
                                OAAEventListener listener)

Declare an application-defined method to be invoked by the LibOaa when a key, well-known event (CallbackId) occurs during execution.

The table below defines the set of well-known events, lists the interface definition for the Java method (Prolog is similar) which will be invoked when the event occurrs, and provides a description of the condition under which the callback is executed. User-defined callbacks need not be named as below in the Definition column, but they must support the listed set of arguments. Although each callback has the same argument list, not all will be used for every well-known event. The Description column will note which arguments will be used; those that are not will be null.

CallbackId	Definition (Java)	Description
app_init	boolean oaa_AppInit(IclTerm goal, IclList params, IclList answers)	Called when oaaRegister has completed successfully to signal registration of the client with the Facilitator. No arguments are used; all are null.
app_done	boolean oaa_AppDone(IclTerm goal, IclList params, IclList answers)	If the agent receives a "halt" event, the app_done callback is called before the agent exits. No arguments are used; all are null.
app_idle	void oaa_AppIdle(IclTerm goal, IclList params, IclList answers)	Executing the app_idle callback provides a way for LibOaa to pass control to a client after oaaMainLoop has been executed. Control is passed when LibOaa is idle, such as during a timeout while waiting for an incoming communication event, or when a user-defined timeout has occurred (see oaaSetTimeout). app_idle is useful only for Prolog which has a single thread of execution. No arguments are used; all are null.
app_do_event	boolean oaa_AppDoEvent(ICLTerm goal, ICLList params, ICLList answers)	oaa_AppDoEvent is called when a new ICL request has arrived for the client. Users may register either one callback for all new ICL requests, or one callback per solvable. The latter is done when declaring a solvable by using the "callback" parameter (see Declaring Solvables) of oaaRegister or oaaDeclare. All oaa_AppDoEvent parameters are used.
app_on_data_change	void oaa_AppOnDataChange(ICLTerm goal, ICLList params, ICLList answers)	app_on_data_change is called upon any data change event. Users may register either one callback for all data change events or one callback per event. The latter is done when publishing a data declaration by using the "callback" parameter (see Declaring Solvables) of oaaRegister or oaaDeclare. Only the first argument will be used, the remaining two will be null. The first argument indicates the type of data change event that occurred and will be in the form: removed(Data) added(Data) replaced(OldData, NewData) defined(Data, Params) redefined(Data, Params) undefined(Data)

If a user-defined callback is not registered and the event is received, a warning message is printed to stdout.

Parameters:

callbackId - a Java String that specifies the name of the well-known event for which a callback is being registered. See CallbackId column in the table above for the list of valid ids.

listener - the Java method to be invoked when the event specified in CallbackId occurrs.

See Also:

oaaDeclare(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclTerm), oaaRegister(java.lang.String, java.lang.String, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList), oaaInterpret(com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList, com.sri.oaa2.icl.IclList)

oaaTraceMsg

public final void oaaTraceMsg(java.lang.String inMessage)

If trace mode is on, display message and arguments

oaaComTraceMsg

public final void oaaComTraceMsg(java.lang.String inMessage)

If com trace mode is on, display message and arguments

oaaInform

public final void oaaInform(java.lang.String TypeInfo,
                            java.lang.String FormatString)

Sends a typed message to interested agents

oaaIsConnected

public final boolean oaaIsConnected(java.lang.String connectionId)

Determines whether the client-Facilitator connection at connectionId is valid and is connected.

Parameters:

connectionId - a Java String that specifies the name of the Facilitator connection.

Returns:

true if connected and false otherwise.

See Also:

LibCom.comConnect(java.lang.String, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList)