casa.interfaces

Interface TransientAgentInterface

All Superinterfaces:

AgentPrintInterface, CasaObservable, MessageSender, Observer, PolicyAgentInterface, ProcessInterface, Runnable

All Known Subinterfaces:

AgentInterface, ChatAgentInterface, CooperationDomainInterface, LACInterface, YellowPagesAgentInterface

All Known Implementing Classes:

camera.AbstractCameraAgent, AbstractTransactionAgent, Agent, AgentProxy, AgentRemoteProxy, AuctionAgent, AuctionCD, BallPusher, CameraSimulation, CASAProcess, ChatAgent, CliffCalibratingController, Controller, CooperationDomain, CooperationDomainObserver, CreateBounce, DrEvil, DutchAuctionAgent, EnglishAuctionAgent, Environment, iRobotCreate, LAC, LineFollower, MasvisAgent, newAgent, ObnoxiousTimeInformAgent, SealedBidAuctionAgent, SecureProxy, ServiceAgent, StateBasedController, TimeAgent, TimeGiver, TimeRequester, TimeSuper, TransactionAgent, TransientAgent, VickreyAuctionAgent, YellowPagesAgent

public interface TransientAgentInterface
extends ProcessInterface, PolicyAgentInterface

Copyright: Copyright 2003-2014, Knowledge Science Group, University of Calgary. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. The Knowledge Science Group makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

Version:

0.9

Author:

Rob Kremer, Daniel Bidulock

Method Summary

Modifier and Type	Method and Description
Status	doAdvertise(URLDescriptor yp, ServiceDescriptor service) This method is called when this agent wishes to advertises a service.
StatusMLMessageList	doCDGetHistory_sync(URLDescriptor cdURL) Retrieves the history list from a cooperation domain.
Status	doCDGetMembers(URLDescriptor cd) Attempts to retrieve the list of participants in a the specified cooperation domain.
Status	doCDPutData(URLDescriptor cdURL, DataStorageDescriptor dsd) Attempts to store data with a Cooperation Domain.
StatusURLDescriptorList	doFindInstances_sync(String pattern)
Vector	doGetCooperationDomains(URLDescriptor cds) Retrieves the list of URLDescriptor's from a cooperation domain server.
Status	doGetOnology(URLDescriptor url, String GET_PERFORMATIVESorGET_ACTS, String typeName) Sends a message to retrieve information about the performatives in the performative type library of another agent.
Status	doInviteToCD(URLDescriptor agent, URLDescriptor cd, boolean sense) Requests an agent to join a particular cooperation domain.
Status	doJoinCD(URLDescriptor cd) Join a cooperation domain.
URLDescriptor	doPing_sync(URLDescriptor agent, long timeout) Pings another agent synchronously.
Status	doPing(URLDescriptor agent, long timeout) Pings another agent.
Status	doRegisterAgentInstance(int lacPort)
Status	doRegisterAgentInstance(int port, RunnableWithParameter<MLMessage> successAction, RunnableWithParameter<MLMessage> failureAction) Registers with the LAC that this Agent is running.
StatusURLDescriptorList	doSearchYP(URLDescriptor yp, ServiceDescriptor service) Attempts to search a yellow pages service for a agents matching a particular service descriptor.
Status	doUnadvertise(URLDescriptor yp, ServiceDescriptor service) This method is called when this agent wishes to withdraw a previously advertised service from a yellow pages service.
Status	doUnregisterAgentInstance(boolean request) Unregisters this Agent from the LAC.
Status	doUnregisterAgentType(int port) Unregisters this Agent type from the LAC's permanent registry.
Status	doWithdrawCD(URLDescriptor cd, boolean request) Withdraw from a cooperation domain.
Status	executeCommand(String command, AgentUI ui) Used to execute a command string at runtime.
StatusURLDescriptorList	getInstancesFound()
Set<URLDescriptor>	getJoinedCooperationDomains()
URLDescriptor	getLACURL() Returns the URL of the LAC the agent is registered to.
Vector<URLDescriptor>	getMembers(URLDescriptor cd)
Ontology	getOntology() Returns the performatives hierarchy for this agent.
ProcessOptions	getOptions() Returns a reference to this object's ProcessOptions object.
String	getSerializedOntology() Returns the String (persistent) representation of the performatives hierarchy for this agent.
JComponent	getStrategyGUI() Returns a GUI that can be used to interact with the strategy of this agent.
boolean	hasStrategyGUI() Used to determine if the agent's strategy has a GUI.
boolean	isAAct(Act a1, Act a2)
boolean	isInitialized()
boolean	isRegistered() If the Agent is registered to a LAC returns true.
AgentUI	makeDefaultInterface(String[] args, boolean GUI) Returns a default AgentUI.
Status	putExtendedOntology(String perfHierarchy) Add the persistent TypeHierarchy data in perfHierarchy to this agent's performative hierarchy.
Status	putReplacementOntology(String types) Replace this agent's type performative hierarchy with the persistent TypeHierarchy data in types.
void	putUI(AgentUI ui) A creating process should call this to let the agent know of any user interface it has attached to the agent.
PerformDescriptor	release_get_ontology(MLMessage msg) Handles get.performative replies from another agent.
void	removeCooperationDomains(URLDescriptor url)
Status	requestInstances(String pattern)
void	setOptions(ProcessOptions options) Sets this object's ProcessOptions object.
void	updateOptions() Save the options to a persistent database.

Methods inherited from interface casa.interfaces.ProcessInterface

addObserver, addObserver, closePort, deleteObserver, deleteObserver, exit, getAgentName, getName, getNewMessage, getPort, getStrategy, getTrace, getUniqueRequestID, getURL, getUseAckProtocol, hasOpenPort, isA, isAPerformative, isExiting, isLoggingTag, isStoppable, isTracing, println, println, println, realizeAgentBehaviourFromOptions, sendMessage, setTracing, setUseAckProtocol, startTraceMonitor

Methods inherited from interface java.lang.Runnable

run

Methods inherited from interface casa.CasaObservable

addObserver, addObserver, countObservers, deleteObservers, hasChanged, notifyObservers, notifyObservers, notifyObserversWithNoArg, notifyObserversWithTop

Methods inherited from interface casa.interfaces.PolicyAgentInterface

abclEval, abclEval, abclEval, addTransformation, bump, chooseSC, defer, dequeueEvent, dispatchMsgHandlerMethod, evesdrop, getKnowledgeBase, getName, getSCStore, getSubscribeEvents, getTransformationFor, getUniqueRequestID, getURL, getUseAckProtocol, isA, isA, isA, isA, isAPerformative, isAPerformative, isLoggingTag, notifyObservers, println, println, println, queueEvent, queueEventIf, revTransform, revTransform, sendMessage, transform, transform

Methods inherited from interface java.util.Observer

update

Method Detail

doRegisterAgentInstance

Status doRegisterAgentInstance(int port,
                               RunnableWithParameter<MLMessage> successAction,
                               RunnableWithParameter<MLMessage> failureAction)

Registers with the LAC that this Agent is running. That is, tells the LAC that this Agent is up and running. Also tells the LAC its URL. When the conversation with the LAC ends, it executes sucessAction() or failureAction as appropriate (but this will happend sometime AFTER the method returns).

Parameters:

lac - URLDescriptor for the LAC to register with.

Returns:

a Status object describing success or failure

doRegisterAgentInstance

Status doRegisterAgentInstance(int lacPort)

doUnregisterAgentInstance

Status doUnregisterAgentInstance(boolean request)

Unregisters this Agent from the LAC. This should always be done before the agent exits.

Parameters:

request - true if the message will be a request; false if it is to be an inform.

Returns:

a Status object describing success or failure

doUnregisterAgentType

Status doUnregisterAgentType(int port)

Unregisters this Agent type from the LAC's permanent registry.

Returns:

a Status object describing success or failure

doFindInstances_sync

StatusURLDescriptorList doFindInstances_sync(String pattern)

isRegistered

boolean isRegistered()

If the Agent is registered to a LAC returns true. Otherwise returns false.

Returns:

true if the Agent is registered to a LAC, false if it is not.

isInitialized

boolean isInitialized()

getJoinedCooperationDomains

Set<URLDescriptor> getJoinedCooperationDomains()

getMembers

Vector<URLDescriptor> getMembers(URLDescriptor cd)

removeCooperationDomains

void removeCooperationDomains(URLDescriptor url)

getInstancesFound

StatusURLDescriptorList getInstancesFound()

requestInstances

Status requestInstances(String pattern)

getLACURL

URLDescriptor getLACURL()

Returns the URL of the LAC the agent is registered to.

Returns:

URLDescriptor of the LAC the agent is registered to. Null if it isn't registered.

doGetCooperationDomains

Vector doGetCooperationDomains(URLDescriptor cds)

Retrieves the list of URLDescriptor's from a cooperation domain server.

Parameters:

cds -

Returns:

Throws:

CDSexception

doJoinCD

Status doJoinCD(URLDescriptor cd)

Join a cooperation domain. Attempts to join the cooperation domain corresponding to the URLdesciptor cd, and notifies observers if successful.

If this agent is already in the cooperation domain, observers are notified of this.

Parameters:

cd - URLDescriptor of the cooperation domain to join

cds - URLDescriptor of the cooperation domain server to be set as the server for the URLdesciptor cd

Returns:

a Status object describing success or failure

doWithdrawCD

Status doWithdrawCD(URLDescriptor cd,
                    boolean request)

Withdraw from a cooperation domain. Attempts to join the cooperation domain corresponding to the URLdesciptor cd, and notifies observers if successful.

If this agent is already in the cooperation domain, observers are notified of this.

Parameters:

cd - URLDescriptor of the cooperation domain to join

request - true if the message will be a request; false if it is to be an inform.

Returns:

a Status object describing success or failure

doCDPutData

Status doCDPutData(URLDescriptor cdURL,
                   DataStorageDescriptor dsd)

Attempts to store data with a Cooperation Domain. This Agent must be a member (successfully joined) the cooperation(??).

Parameters:

dsd - The data descriptor of the data to be stored

cd - The URLDescriptor of the cooperation domain.

Throws:

CDDataException - If the data cannot be successfully stored with the CD.

doCDGetHistory_sync

StatusMLMessageList doCDGetHistory_sync(URLDescriptor cdURL)

Retrieves the history list from a cooperation domain. Note that this method is usually implemented in terms of the method getDataCD.

Parameters:

url - The URLDescriptor of the CD from which to retrieve the history list

Returns:

A Vector of messages forming the history list

Throws:

CDDataException - If the retrieval fails

doCDGetMembers

Status doCDGetMembers(URLDescriptor cd)

Attempts to retrieve the list of participants in a the specified cooperation domain.

Parameters:

cd - The URLDescriptor of the CD.

Returns:

A Vector of URLDescriptor's of agents currently participating in the CD.

Throws:

CDException - If the retrieval fails.

doAdvertise

Status doAdvertise(URLDescriptor yp,
                   ServiceDescriptor service)

This method is called when this agent wishes to advertises a service. The service added is advertised on a the YellowPages at the urlDescriptor yp. Adds the URLDescriptor and ServiceDescriptor pair to the bufferOfAdvertisements Hashmap. If the entry is already present in the bufferOfAdvertisements, the function simply returns.

Parameters:

yp - URLDescriptor of the agent advertising the service

service - ServiceDescriptor of the service being advertised

Returns:

A Status object describing success or failure

doUnadvertise

Status doUnadvertise(URLDescriptor yp,
                     ServiceDescriptor service)

This method is called when this agent wishes to withdraw a previously advertised service from a yellow pages service.

Parameters:

yp - URLDescriptor of the agent advertising the service

service - ServiceDescriptor of the service being withdrawn

Returns:

A Status object describing success or failure

doSearchYP

StatusURLDescriptorList doSearchYP(URLDescriptor yp,
                                   ServiceDescriptor service)

Attempts to search a yellow pages service for a agents matching a particular service descriptor.

Parameters:

yp - The URLDescriptor of the YP to search

service - A (perhaps partial) ServiceDescriptor description of a service that the YP should match its advertisements against

Returns:

A Vector of URLdescritors of matching services (this might be expanded to be ServiceDescriptor/URLDescriptor pairs)

Throws:

YPexception - If the retrieval fails.

makeDefaultInterface

AgentUI makeDefaultInterface(String[] args,
                             boolean GUI)

Returns a default AgentUI. This will normally be called only if the the -i (interface) qualifier does not appear on the command line.

Parameters:

args - The command line arguments

userName - The name of the user

Returns:

some default interface the conforms to AgentUI interface.

putUI

void putUI(AgentUI ui)

A creating process should call this to let the agent know of any user interface it has attached to the agent. Note that this could be called more than once, which may mean the agent has more than one user interface. The default behaviour is just to ignore it, since the interface could work via the Observer interface and various set*() and get*() calls on the agent.

Parameters:

ui - the user interface to be attached to the agent.

doInviteToCD

Status doInviteToCD(URLDescriptor agent,
                    URLDescriptor cd,
                    boolean sense)

Requests an agent to join a particular cooperation domain.

Parameters:

agent - Agent this agent is requesting the join the CD.

cd - The CD the agent should join.

Returns:

A Status object describing success or failure

doPing

Status doPing(URLDescriptor agent,
              long timeout)

Pings another agent. Attempts to ping the agent corresponding to the URLDesciptor agent by sending a message of the format:

performative	request
act	ping

Note that his method only sends the message; it relies on #handleReply_ping(MLMessage) to do the actual processing of the returned reply.

Parameters:

agent - URLDescriptor of the agent to ping

timeout - maxiumum time (in milliseconds) to wait for the ping response

Returns:

a Status object with value 0 for success, or describing the failure otherwise.

Throws:

Exception - if there is an error sending the message

doPing_sync

URLDescriptor doPing_sync(URLDescriptor agent,
                          long timeout)

Pings another agent synchronously. Attempts to ping the agent corresponding to the URLDesciptor agent by sending a message of the format:

performative	request
act	ping

The reply is not verified in any way, but generally should have the format:

performative	reply
act	ping

Parameters:

agent - URLDescriptor of the agent to ping

timeout - maxiumum time (in milliseconds) to wait for the ping response

Returns:

the MLMessage that was recieved in reply to the ping

Throws:

Exception - if there is an error sending the message

getOptions

ProcessOptions getOptions()

Description copied from interface: ProcessInterface

Returns a reference to this object's ProcessOptions object.

Specified by:

getOptions in interface PolicyAgentInterface

Specified by:

getOptions in interface ProcessInterface

Returns:

an reference to this object's ProcessOptions object.

setOptions

void setOptions(ProcessOptions options)

Description copied from interface: ProcessInterface

Sets this object's ProcessOptions object.

Specified by:

setOptions in interface ProcessInterface

Parameters:

options -

updateOptions

void updateOptions()

Description copied from interface: ProcessInterface

Save the options to a persistent database. Subclasses should override as appropriate.

Specified by:

updateOptions in interface ProcessInterface

doGetOnology

Status doGetOnology(URLDescriptor url,
                    String GET_PERFORMATIVESorGET_ACTS,
                    String typeName)

Sends a message to retrieve information about the performatives in the performative type library of another agent. Sends a message of format:

performative	request
act	get.performatives
language	identifier	may be missing if performativeName is null
content	performativeName | null	blank or missing requests all performative information

The corresponding handler is #handleReply_GetPerformatives(MLMessage).

Parameters:

url - The URLDescriptor of an agent to request performative information from

GET_PERFORMATIVESorGET_ACTS - either the act name GET_PERFORMATIVES or GET_ACTS

typeName - the name of the performative, or null to request a complete description of url's performatives

Returns:

A Status object from the sendMessage.

release_get_ontology

PerformDescriptor release_get_ontology(MLMessage msg)

Handles get.performative replies from another agent. The expected format is:

performative	reply
act	get.performatives
language	casa.TypeHierarchy
content	a description of the requested performative(s) conforming to casa.TypeHierarchy

or standard error replies. If the message is successfully interpreted, updates the local performatives type hierarchy with a call to AbstractProcess.??? ??

Parameters:

msg - the incoming get.members request message

Returns:

a status describing the success or failure of the operation

getSerializedOntology

String getSerializedOntology()

Returns the String (persistent) representation of the performatives hierarchy for this agent. This is compatible with the String constructor of TypeHiearchy.

Returns:

the String (persistent) representation of the performatives hierarchy for this agent.

getOntology

Ontology getOntology()

Returns the performatives hierarchy for this agent.

Specified by:

getOntology in interface PolicyAgentInterface

putExtendedOntology

Status putExtendedOntology(String perfHierarchy)

Add the persistent TypeHierarchy data in perfHierarchy to this agent's performative hierarchy.

Parameters:

perfHierarchy - A String containing the persistent for of a TypeHierarchy

Returns:

a Status object indicating:

• 0: success
• -1: Attempted insertion of duplicate type node into performatives type hierarchy
• -2: Malformed content field: Parent node not found in performatives type hierarchy
• -3: Malformed content field: Parse exception
• -4: Type information is incompatible with existing performatives hierarchy

putReplacementOntology

Status putReplacementOntology(String types)

Replace this agent's type performative hierarchy with the persistent TypeHierarchy data in types. If types is not well-formed, a negative status is returned and the original performative hierarchy is left unchanged.

Parameters:

types - A String containing the persistent for of a TypeHierarchy

Returns:

a Status object indicating:

• 0: success
• -1: Attempted insertion of duplicate type node into performatives type hierarchy
• -2: Malformed content field: Parent node not found in performatives type hierarchy
• -3: Malformed content field: Parse exception

executeCommand

Status executeCommand(String command,
                      AgentUI ui)

Used to execute a command string at runtime.

Specified by:

executeCommand in interface PolicyAgentInterface

Parameters:

command - a command string

ui - an AgentUI object (may be null).

Returns:

a Status object with the result of the attempted execution.

getStrategyGUI

JComponent getStrategyGUI()

Returns a GUI that can be used to interact with the strategy of this agent. Will return a null value if hasStrategyGUI() returns false.

Returns:

A JPanel that is the GUI responsible for interacting with this agent's strategy.

hasStrategyGUI

boolean hasStrategyGUI()

Used to determine if the agent's strategy has a GUI.

Returns:

Whether the strategy has a GUI.

isAAct

boolean isAAct(Act a1,
               Act a2)

Specified by:

isAAct in interface PolicyAgentInterface