com.sri.oaa2.com
Class LibCom

java.lang.Object
  |
  +--com.sri.oaa2.com.LibCom

All Implemented Interfaces:

LibComClient, LibComListener, LibComServerListener

public class LibCom

extends java.lang.Object

implements LibComClient, LibComServerListener, LibComListener

Provides communications methods for the agentlib

Field Summary

IclDb	commdb
static int	MAXBACKLOG
protected java.lang.String[]	mCmdLine

Constructor Summary

LibCom(LibComProtocol inProtocol, java.lang.String[] inCmdLine)
Constructor

Method Summary

int	availTerms()
boolean	comAddInfo(java.lang.String connectionId, IclTerm newInfo) Add NewInfo to the database entry for the client connection described by ConnectionId.
void	comAddProtocol(LibComProtocol inProtocol)
boolean	comConnect(java.lang.String connectionId, IclTerm address, IclList params) Connect a client agent to the Facilitator found at Address.
boolean	comConnected(java.lang.String connectionId) Determines whether a given connection is actually valid.
boolean	comDisconnect(java.lang.String connectionId, IclList params) Shut down the connection between client agent and Facilitator as named by ConnectionId.
java.lang.String	comGetConnectionFromInfo(IclTerm conStruct) purpose: Looks up a connection that contains a given information returns: Null if fail, an IclTerm if success
java.lang.String	comGetConnectionId(IclTerm Info) purpose: Looks up a connection that contains the given information in the info list.
IclTerm	comGetInfo(java.lang.String connectionId, IclTerm infoIn) Find and return information associated with Info stored in the client database for the connection named ConnectionId.
boolean	comListenAt(java.lang.String connectionId, IclTerm params, IclTerm address) Given a connection ID and an address, initiate a server connection.
void	ComPrintDB(java.lang.String inMessage)
boolean	comSendData(java.lang.String connectionId, IclTerm t)
IclList	getAllValidConnections() Returns an IclList containing all valid connections' ids.
java.util.HashMap	getBuffers()
java.lang.String[]	getCmdLine()
IclTerm	getNextTermRR() Get next term from any connection, in round robin fashion
boolean	haveTerms()
void	notifyConnectionEstablished(LibComConnection newConnection, java.lang.String connectionId, IclTerm address, IclList params) Notifies the listener that a new connection has been established.
void	notifyConnectionShutDown(LibComConnection connection, com.sri.oaa2.simplefac.ConnectionId connectionId, java.lang.Throwable ex) Notifies the listener that a new connection has been established.
void	processIncomingTerm(java.lang.String connectionId, IclTerm t) processIncomingMessage(String connectionId, String message)

Methods inherited from class java.lang.Object

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

Field Detail

MAXBACKLOG

public static final int MAXBACKLOG

See Also:

Constant Field Values

commdb

public IclDb commdb

mCmdLine

protected java.lang.String[] mCmdLine

Constructor Detail

LibCom

public LibCom(LibComProtocol inProtocol,
              java.lang.String[] inCmdLine)

Constructor

Method Detail

comAddProtocol

public void comAddProtocol(LibComProtocol inProtocol)

comConnect

public boolean comConnect(java.lang.String connectionId,
                          IclTerm address,
                          IclList params)

Connect a client agent to the Facilitator found at Address. Assign the value of ConnectionId as the name for this connection which is used to reference it in subsequent operations such as oaaDisconnect and comGetInfo.

For successful connections, comConnect() adds a new entry to a database maintained by LibCom, also called the InfoList. LibCom uses this database for managing the the set of connections, and for Java, a corresponding set of execution threads (one per connection). The database contains a key which identifies the connection (ConnectionId), a list of ICL Terms that describe the connection (e.g., status(connected), connection(8)), and a pointer to a buffer which is used for storing data received from the Facilitator for the client.

A client agent may connect to only one Facilitator. The value for connectionId must be 'parent' or "parent" for the Prolog and Java implementations respectively. Future releases will support connections to multiple facilitators by a single client.

Parameters:

connectionId - a Prolog ICL atom or Java String that specifies the name of the Facilitator connection.

params - a list of IclTerms. THe only param used is "other_address". If "other_address" is defined, it is used as "other_address" in the connection_info.

address - may be either an explicit connection address for a Facilitator or an uninitialized variable. The latter is most commonly used. Examples include tcp("test.ai.sri.com", "7576") and tcp(Host, Port).

Returns:

returns true if the connection attempt was successful and false otherwise.

 Use of an uninitialized variable for Address cues comConnect to determine the host
 and port according to the following order of priority:

 Highest: retrieve host and port from command line arguments
			-oaa_connect tcp(Host,Port)
 Example:
			-oaa_connect "tcp('test.ai.sri.com', 7576)"
 Next: retrieve this information from the environment variables OAA_CONNECT.
 Lowest: use information found in the configuration file setup.pl. Entries must be of the form
			default_facilitator(tcp(Host,PortNumber)).
 For example
			default_facilitator(tcp('test.ai.sri.com', 7576)).

 comConnect() locates setup.pl by first looking in the local directory, then if not found,
 looks in the user's home directory.

 Example:
		// First, connect to the facilitator
		if (!oaa.getComLib().comConnect("parent", IclTerm.fromString(true, "tcp(Host,Port)"))){
		  printError("Could not connect");
		  return;
		}
 

See Also:

LibOaa.oaaRegister(java.lang.String, java.lang.String, com.sri.oaa2.icl.IclTerm, com.sri.oaa2.icl.IclList), LibOaa.oaaRegisterCallback(java.lang.String, com.sri.oaa2.lib.OAAEventListener), LibOaa.oaaMainLoop(boolean), LibOaa.oaaDisconnect(java.lang.String, com.sri.oaa2.icl.IclList), comDisconnect(java.lang.String, com.sri.oaa2.icl.IclList)

notifyConnectionEstablished

public void notifyConnectionEstablished(LibComConnection newConnection,
                                        java.lang.String connectionId,
                                        IclTerm address,
                                        IclList params)

Description copied from interface: LibComServerListener

Notifies the listener that a new connection has been established.

Specified by:

notifyConnectionEstablished in interface LibComServerListener

Parameters:

newConnection - the new connection

connectionId - the id for the new connection

address - the connection's address

params - any parameters to use when adding the connection to the comm db.

comDisconnect

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

Shut down the connection between client agent and Facilitator as named by ConnectionId.

comDisconnect() immediatly disconnects the client-Facilitator connection with no delays (e.g., remaining data on the connection is discarded) and removes the entry corresponding to ConnectionId from the LibCom database. For the Java implementation, comDisconnect() also kills the thread of execution associated with this connection.

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:

returns true if the disconnection attempt was successful and false otherwise.

See Also:

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

comListenAt

public boolean comListenAt(java.lang.String connectionId,
                           IclTerm params,
                           IclTerm address)

Given a connection ID and an address, initiate a server connection. remarks: - if Address is a variable, instantiates the Address by using oaa_ResolveVariables, which looks in a setup file, command line, and environment variables for the required info. - stores the connection info for connection ID in com_connection_info/5. - fails if connection can't be made

comSendData

public boolean comSendData(java.lang.String connectionId,
                           IclTerm t)

comGetInfo

public IclTerm comGetInfo(java.lang.String connectionId,
                          IclTerm infoIn)

Find and return information associated with Info stored in the client database for the connection named ConnectionId.

Returns:

null if connectionId is invalid or if Info is not found in the dataset. Otherwise, it returns an IclTerm instance containing the result(s).

See Also:

comAddInfo(java.lang.String, com.sri.oaa2.icl.IclTerm)

comGetConnectionFromInfo

public java.lang.String comGetConnectionFromInfo(IclTerm conStruct)

purpose: Looks up a connection that contains a given information returns: Null if fail, an IclTerm if success

Parameters:

conStruct - a com_connection_info struct

comGetConnectionId

public java.lang.String comGetConnectionId(IclTerm Info)

purpose: Looks up a connection that contains the given information in the info list. returns: Null if fail, an IclTerm if success

Parameters:

Info - an info parameter struct (ex: other_address(..))

comConnected

public boolean comConnected(java.lang.String connectionId)

Determines whether a given connection is actually valid.

Parameters:

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

getAllValidConnections

public IclList getAllValidConnections()

Returns an IclList containing all valid connections' ids.

comAddInfo

public boolean comAddInfo(java.lang.String connectionId,
                          IclTerm newInfo)

Add NewInfo to the database entry for the client connection described by ConnectionId. If NewInfo already exists in the database for this client, update its value instead.

Parameters:

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

newInfo - a Java String which contains one or more elements to be stored for this client such as status(S), type(T), or protocol(P); e.g., "status(connected), protocol(tcp)".

Returns:

true if the entry was successfully added and false otherwise.

See Also:

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

getNextTermRR

public IclTerm getNextTermRR()

Get next term from any connection, in round robin fashion

processIncomingTerm

public void processIncomingTerm(java.lang.String connectionId,
                                IclTerm t)

Description copied from interface: LibComClient

processIncomingMessage(String connectionId, String message)

Specified by:

processIncomingTerm in interface LibComClient

haveTerms

public boolean haveTerms()

availTerms

public int availTerms()

getBuffers

public java.util.HashMap getBuffers()

getCmdLine

public java.lang.String[] getCmdLine()

ComPrintDB

public void ComPrintDB(java.lang.String inMessage)

notifyConnectionShutDown

public void notifyConnectionShutDown(LibComConnection connection,
                                     com.sri.oaa2.simplefac.ConnectionId connectionId,
                                     java.lang.Throwable ex)

Description copied from interface: LibComListener

Notifies the listener that a new connection has been established.

Specified by:

notifyConnectionShutDown in interface LibComListener

Parameters:

connection - the connection which shut down

connectionId - the id for the connection which shut down

ex - an error detailing the reason the connection was shut down