Class JavaAgent.agent.Agent

All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class JavaAgent.agent.Agent

java.lang.Object
   |
   +----JavaAgent.agent.Agent

public class Agent
extends Object

Class which represents a autonomous software agent whose capabilities are represented by a set of resource objects which include both data and Java class definitions. Agent's communicate with one another via KQML messages which are transmitted by a CommInterface object. Resource storage and management is handled by a ResourceManager object. Message transmission via the CommInterface is the responsibility of a MessageHandler object.

The Agent must be created, along with the CommInterface, in an external class which implements the ContextInterface interface. Upon creation the agent must be provided with:

Reference to a ContextInterface.
A String name for the Agent.
A URL for an initialization file which contains a set of KQMLmessages to be processed at startup. (One of these messages will provide the address of an Agent Name Server (ANS) to which the Agent must send its name and address.)
A URL for a directory which contains shared classes and files. If the Agent will communicate with other Agents distributed over the Internet, this URL must have the http protocol.
A directory for local access to shared classes, which will be null if the Agent is unable to write to the local file system.
A directory for local files, which will be null if the Agent is unable to write to the local file system.

Each Agent, when created, loads a set of initialization messages from an initialization file. One of these messages will provide the address of an Agent Name Server (ANS) to which the Agent must send its name and address. Each Agent automatically "knows" the "KQML" language (KQMLmessage class) and the "agent" Interpreter (AgentInterpreter class).

The internal knowledge of an Agent is contained in a set of Resource classes (managed by the ResourceManager). Access to the data within these classes is synchronized to prevent race conditions. A special subclass of Resource, RetrievalResource, provides the storage for addresses, languages, interpreters and remotely loaded classes. When an Agent attempts to access a non-existent element from a RetrievalResource instance, the access thread is blocked and a message is sent to obtain the desired object. When the object is received, the access thread is restarted. (See the RetrievalResource class for more information). This action is taken for unknown addresses, languages, interpreters, general classes and files. For the retrieval of remote code, a Hashtable of NetworkClassLoaders is maintained.

When a message is received by an Agent the following steps occur within the MessageHandler:

The CommInterface receives a string message and parses it to create a KQMLmessage and calls the Agent's receiveMessage method.
The KQMLmessage is passed to the interpretMessage method of an instance of the specified Interpreter. (In this context, an Interpreter is represented by a class which contains procedural instructions for interpreting a specific message. A more appropriate name may be message handler) If the Agent does not possess the Interpreter, a request for that class is sent, per the RetrievalResource functionality, to the Agent who sent the message.
For each Interpreter, the message is interpreted according to the language specified for the content. (Here language represents the syntatical knowledge necessary to parse the content string and construct a subclass of Language which can be interpreted by an Interpreter subclass) Again, if the Agent does not possess the specified Language subclass, a request is sent to the message sender.

Agent communications regarding addressing, code retrieval and other organizational or architectural issues (not related to domain knowledge) are done using KQML for the message content syntax and the "agent" MessageHandler. (See class AgentHandler).

RESTRICTED RIGHTS LEGEND: Use, duplication or disclosure by the Government is subject to restrictions as set forth in subparagraph(c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similar clauses in the FAR and NASA FAR supplement.

This software is bound by the terms and conditions listed in the attached LICENSE file.

context: Interface to the context in which the Agent was created.
handler: Object which handles all message transmission and maintains a history of both sent and received messages.
init_url: URL for initialization file.
io_enabled: Can the Agent perform local file io?
name: A unique String identifier for the Agent.
resources: Object which contains and manages all of the Agent's resources.
shared_classes: URL for the classes directory containing classes which will be shared with other agents.
shared_dir: Directory for local access to the shared classes URL.
working_dir: Working directory for saving files on the local disk, null if the Agent cannot write to the local file system.

Agent(ContextInterface, String, URL, URL, File, File): Contructs an Agent with a name, init file, shared classes URL and working directory.

addPanel(Panel): If the context supports a GUI, then add the instantiated and intialized panel to a new top-level window.
addSystemMessage(String): Pipes a system message to the Agent's context.
addSystemMessage(String, Exception): Pipes a system message to the Agent's context.
currentMessage(): Returns the message currently being interpreted, returns null if no message is being interpreted.
getName(): Gets name of Agent.
getReceivedMessages(): Returns a Vector of received messages, if more than MESSAGE_STORAGE number have been received, only returns the most recent.
getResource(String): Get the resource object for the specified type.
getSentMessages(): Returns a Vector of transmitted messages, if more than MESSAGE_STORAGE number have been sent, only returns the most recent.
getSharedClassesURL(): Retrieves the URL for shared classes and files, returns null if there are no files to share.
getSharedDir(): Retrieves the directory for local access to the shared classe dir.
getWorkingDir(): Retrieves the directory for local file storage, might be null.
hasGUI(): Returns true if the AgentContext supports a GUI.
init(): Creates the ResourceManager, MessageHandler and reads in the init_file.
initiateTermination(): Called when the executable class which contains the Agent terminates.
interpretingMessage(): Returns true if the Agent is currently interpreting a message.
loadClass(URL, String): Called to load a remote class into the current runtime environment.
loadInitFile(URL): Loads a set of KQMLmessages from a file at the specified URL.
loadResource(String, String, String, String): Loads a given resource.
localIO()
receiveMessage(KQMLmessage): Called by the associated CommInterface when a KQMLmessage is received.
releasePending(): Releases the transmission block.
resourceChanged(Resource): Called by a Resource object when the number of elements has changed.
resourceChanged(String): Called when a non-Resource object has changed.
sendInitMessages(): Group of messages which are automatically sent out at startup.
sendMessage(KQMLmessage): Called to send a given KQMLmessage.
sendResult(KQMLmessage, boolean, String): Called by the associated CommInterface to report the success of a sendMessage call.
setComm(CommInterface): Sets the value of the CommInterface.
setName(String): Sets the name of the Agent.
terminate(): Called when the last termination message has been sent.

context

  protected ContextInterface context

Interface to the context in which the Agent was created.

resources

  protected ResourceManager resources

Object which contains and manages all of the Agent's resources.

handler

  protected MessageHandler handler

Object which handles all message transmission and maintains a history of both sent and received messages.

name

  protected String name

A unique String identifier for the Agent. When an Agent is started the user is requested to either provide a name or let the name default to one generated from the Agent's address (will be unique).

working_dir

  protected File working_dir

Working directory for saving files on the local disk, null if the Agent cannot write to the local file system.

shared_classes

  protected URL shared_classes

URL for the classes directory containing classes which will be shared with other agents.

shared_dir

  protected File shared_dir

Directory for local access to the shared classes URL.

init_url

  protected URL init_url

URL for initialization file.

io_enabled

  protected boolean io_enabled

Can the Agent perform local file io?

Agent

  public Agent(ContextInterface context,
               String n,
               URL init_url,
               URL shared,
               File shared_dir,
               File working_dir)

Contructs an Agent with a name, init file, shared classes URL and working directory.

Parameters:: n - String identifier for the Agent.; init_url - URL for the initialization file.; shared - URL for shared classes.; shared_dir - Directory for local access to shared classes.; working_dir - Directory for local files, will be null if the Agent is unable to write to the local file system.

init

  public void init()

Creates the ResourceManager, MessageHandler and reads in the init_file.

setComm

  public void setComm(CommInterface c)

Sets the value of the CommInterface.

Parameters:: c - CommInterface for this Agent.

sendInitMessages

  public void sendInitMessages()

Group of messages which are automatically sent out at startup. If the name submitted by the agent is non-unique, these message will be resent with the unique name.

localIO

  public boolean localIO()

Returns:: True if the Agent can perform local file IO.

getSharedClassesURL

  public URL getSharedClassesURL()

Retrieves the URL for shared classes and files, returns null if there are no files to share.

Returns:: URL for directory containing both the classes directory and the directory for files.

getWorkingDir

  public File getWorkingDir()

Retrieves the directory for local file storage, might be null.

Returns:: Directory for local files.

getSharedDir

  public File getSharedDir()

Retrieves the directory for local access to the shared classe dir.

Returns:: Directory for shared classes

loadInitFile

  public void loadInitFile(URL file_url)

Loads a set of KQMLmessages from a file at the specified URL. This file must be a text file containing one KQMLmessage per line. The language and Interpreter fields for the messages are limited to "KQML" and "agent", respectively. At a minimum this file must contain a KQMLmessage informing the Agent of the address of the ANS, this message will have the following structure: "(evaluate :sender file :receiver: agent :language KQML :ontology agent :content (tell-address :name <name> :host <host> :port <port>))".

Parameters:: file_url - The URL for the init file.

loadResource

  public void loadResource(String type,
                           String name,
                           String object_name,
                           String url)

Loads a given resource. If the resource currently exists does not overwrite.

Parameters:: type - Type of resource, either language, Interpreter or class; name - The identifier for the resource.; object_name - The class or file name.; url - The code base for the class.

getResource

  public Resource getResource(String type)

Get the resource object for the specified type.

Parameters:: type - Resource type to get, one of: "address", "language", "interpreter" or "class".
Returns:: Resource object or null if type does not exist.

resourceChanged

  public void resourceChanged(Resource r)

Called by a Resource object when the number of elements has changed.

Parameters:: type - Type of the Resource.

resourceChanged

  public void resourceChanged(String resource)

Called when a non-Resource object has changed.

Parameters:: type - Type of resource.

addSystemMessage

  public void addSystemMessage(String message)

Pipes a system message to the Agent's context.

Parameters:: message - The system message to output.

addSystemMessage

  public void addSystemMessage(String message,
                               Exception e)

Pipes a system message to the Agent's context.

Parameters:: message - The system message to output.; e - Exception which generated the message, may be null.

interpretingMessage

  public boolean interpretingMessage()

Returns true if the Agent is currently interpreting a message.

Returns:: true if a message is being interpreted.

currentMessage

  public KQMLmessage currentMessage()

Returns the message currently being interpreted, returns null if no message is being interpreted.

getName

  public String getName()

Gets name of Agent.

Returns:: Agent name.

setName

  public void setName(String name)

Sets the name of the Agent.

Parameters:: name - Agent name.

hasGUI

  public boolean hasGUI()

Returns true if the AgentContext supports a GUI.

Returns:: True if the context has a GUI, false otherwise.

addPanel

  public void addPanel(Panel p)

If the context supports a GUI, then add the instantiated and intialized panel to a new top-level window.

Parameters:: p - Panel to add.

sendMessage

  public void sendMessage(KQMLmessage message)

Called to send a given KQMLmessage. Calls the sendMessage method of the associated MessageHandler which will pass the message to the CommInterface for transmission.

Parameters:: message - The KQMLmessage to send, null if the buffer is being flushed.

releasePending

  public void releasePending()

Releases the transmission block.

sendResult

  public void sendResult(KQMLmessage message,
                         boolean status,
                         String reason)

Called by the associated CommInterface to report the success of a sendMessage call.

Parameters:: message - The KQMLmessage which the CommInterface was asked to send.; status - True if the message transmission was successful, false if otherwise.; reason - String with detailed reason.

getSentMessages

  public Vector getSentMessages()

Returns a Vector of transmitted messages, if more than MESSAGE_STORAGE number have been sent, only returns the most recent.

Returns:: Vector of KQMLmessages.

getReceivedMessages

  public Vector getReceivedMessages()

Returns a Vector of received messages, if more than MESSAGE_STORAGE number have been received, only returns the most recent.

Returns:: Vector of KQMLmessages.

receiveMessage

  public void receiveMessage(KQMLmessage message)

Called by the associated CommInterface when a KQMLmessage is received. The message is handled based on the Interpreter for the message content. Content language is considered within the Interpreter handler.

Parameters:: message - The KQMLmessage which was received.

loadClass

  public Class loadClass(URL code_url,
                         String name)

Called to load a remote class into the current runtime environment. First check to see if a loader for the URL already exists, only create a new loader if one doesn't currently exist. Returns null if no code is found.

Parameters:: code_url - code base URL; name - Class name.
Returns:: The loaded Class.

terminate

  public void terminate()

Called when the last termination message has been sent.

initiateTermination

  public void initiateTermination()

Called when the executable class which contains the Agent terminates. The agent sends a remove-address message to the ANS.

All Packages  Class Hierarchy  This Package  Previous  Next  Index