zeus.agents
Class SimpleAPI

java.lang.Object
  zeus.agents.SimpleAPI

public class SimpleAPI

extends java.lang.Object

SimpleAPI is intended to provide a simple way to program a Zeus agent. The intention is that the methods that are implemented here will allow a novice agent programmer to easily perform a number of the most common task that they will need to build a functional agent.

Since:

1.1

Author:

Simon Thompson

Field Summary

private AgentContext	agentContext
private Queue	messageQueue
private boolean	messQ

Constructor Summary

SimpleAPI(AgentContext agentContext)
this init() method is used to set up a SimpleAPI for you to use The suggested method of use is from your AgentExternal : public class myExternal implements ZeusExternal { public void exec(AgentContext ac) { SimpleAPI api = new SimpleAPI (ac);
You can now use the methods in this class via the api instance.

Method Summary

void	achieve(Fact[] toGet) achieve is used to make the agent attempt to satisfy the postcondition formed by the parameter toGet[] The array will be iterated over and a goal will be set for each of the facts that are passed.
void	addFact(Fact toAdd) addFact can be used to add a fact into the Zeus resourceDb (the agents beliefs) This will trigger any rules that match the fact, and will allow agents to acheive goals that can be met by exectuing tasks with preconditions that match the fact.
void	addQueue(Performative perf) addQueue is used to add a message to the internal queue maintained by this agent.
Performative	getNextMessage() if the messageQueue has been turned on this method will return the next message on the queue.
boolean	isQueueOn() Simple method that is called to find out if the message enqueue mechanism has been turned on or off.
boolean	sendMessage(java.lang.String performative, java.lang.String content, java.lang.String target) sendMessage can be used to send a message to another agent.
void	setHandler(java.lang.String messageType, java.lang.Object target, java.lang.String methodName) setHandler method allows you to specify a method in an object that will be called when a message of type messageType The method methodName will be called, it must have a single parameter of type zeus.concepts.Performative - when this method is called by the handling code this parameter will contain the message that has been received.
void	setHandler(java.lang.String messageType, java.lang.String agentFrom, java.lang.Object target, java.lang.String methodName) setHandler method allows you to specify a method in an object that will be called when a message of type messageType and from the agent agentFrom is received by this agent.
void	setMessageQueue() setMessageQueue method is used to specify to zeus that it should queue messages in this method so that they can be picked up one at a time in a simple to understand way.
Performative	waitNextMessage() waitNextMessage bocks until a message is received by the agent, it will then return that message.

Methods inherited from class java.lang.Object

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

Field Detail

messQ

private boolean messQ

messageQueue

private Queue messageQueue

agentContext

private AgentContext agentContext

Constructor Detail

SimpleAPI

public SimpleAPI(AgentContext agentContext)

this init() method is used to set up a SimpleAPI for you to use

The suggested method of use is from your AgentExternal :

public class myExternal implements ZeusExternal { public void exec(AgentContext ac) { SimpleAPI api = new SimpleAPI (ac);
You can now use the methods in this class via the api instance.

Parameters:

agentContext - used by this class to access the internals of the zeus agent the agentContext object is the directory of agent components that is passed to a Zeus AgentExternal when it is instantiated. Sophisticated agent programmers will want to utilize the agentContext object directly rather than via this simple wrapper, which is designed for novice users.

See Also:

AgentContext, ZeusAgentContext

Method Detail

sendMessage

public boolean sendMessage(java.lang.String performative,
                           java.lang.String content,
                           java.lang.String target)

sendMessage can be used to send a message to another agent.

Parameters:

performative - the type of message ie. inform,confirm, cfp

content - the content string in the message - what it is that you are sending to the other agent

target - the agent that you are sending this message to. The form of this string should follow the traditional AID or tcp/ip format ie. transport://host.place.domain:portNo/context1/context2/contextn/name
where transport might be iiop, iiopname, zeus or http,
host is the machine that this is on
place is the company or institution's domain name
domain is the internet domaine - edu or com or org, or co.uk or fr
portNo is an integer which is the port that the agent is listening on
contextx is the naming context of the agent addressed
name is the name of the agent that is being addressed

achieve

public void achieve(Fact[] toGet)

achieve is used to make the agent attempt to satisfy the postcondition formed by the parameter toGet[] The array will be iterated over and a goal will be set for each of the facts that are passed.

setHandler

public void setHandler(java.lang.String messageType,
                       java.lang.String agentFrom,
                       java.lang.Object target,
                       java.lang.String methodName)

setHandler method allows you to specify a method in an object that will be called when a message of type messageType and from the agent agentFrom is received by this agent.

The method methodName will be called, it must have a single parameter of type zeus.concepts.Performative - when this method is called by the handling code this parameter will contain the message that has been received.

Parameters:

messageType - the type of message (performative type) that is being watched for Examples of a performative type are inform, confirm , cfp , request

agentFrom - the putative source of the messages in the form

http://www.adastralCity.com/test

This would mean that all messages from the agent called test on the platform www.adastralCity.com that are passed via http will be picked up and forwarded to the handleing method.

target - the object instance that is providing the handler method for this

methodName - the name of the method that is to be called

setHandler

public void setHandler(java.lang.String messageType,
                       java.lang.Object target,
                       java.lang.String methodName)

setHandler method allows you to specify a method in an object that will be called when a message of type messageType

The method methodName will be called, it must have a single parameter of type zeus.concepts.Performative - when this method is called by the handling code this parameter will contain the message that has been received.

Parameters:

messageType - the type of message (performative type) that is being watched for Examples of a performative type are inform, confirm , cfp , request

target - the object instance that is providing the handler method for this

methodName - the name of the method that is to be called

setMessageQueue

public void setMessageQueue()

setMessageQueue method is used to specify to zeus that it should queue messages in this method so that they can be picked up one at a time in a simple to understand way.

This is a very primative way of handling messages and should only be invoked for simple applications. Once the messageQueue has been tyrned on it cannot be turned off, however, a repeat invokation of this method will cause the queue to be reset, and all the messages currently stored on it will be discarded.

isQueueOn

public boolean isQueueOn()

Simple method that is called to find out if the message enqueue mechanism has been turned on or off.

getNextMessage

public Performative getNextMessage()

if the messageQueue has been turned on this method will return the next message on the queue.

If the messageQueue is not on then this call will return null.

If the messageQueue is empty this method will return null

waitNextMessage

public Performative waitNextMessage()

waitNextMessage bocks until a message is received by the agent, it will then return that message. However, this will only work if the setMessageQueue method has been called first, because if it hasn't this will block until you call the addQueue(Performative) method.

addQueue

public void addQueue(Performative perf)

addQueue is used to add a message to the internal queue maintained by this agent. It is primarily intended for internal use, but if the message queue is turned on you could use this to send a message to yourself!

Parameters:

perf - the performative to add to the queue

addFact

public void addFact(Fact toAdd)

addFact can be used to add a fact into the Zeus resourceDb (the agents beliefs) This will trigger any rules that match the fact, and will allow agents to acheive goals that can be met by exectuing tasks with preconditions that match the fact.

Parameters:

toAdd - the fact that you want to be added

Since:

1.3