jade.proto

Class SimpleAchieveREInitiator

java.lang.Object

jade.core.behaviours.Behaviour

jade.core.behaviours.SimpleBehaviour

jade.proto.SimpleAchieveREInitiator

All Implemented Interfaces:

java.io.Serializable

public class SimpleAchieveREInitiator
extends SimpleBehaviour

This is simple implementation of the AchieveREInitiator. This implementation in particular is 1:1 and does not allow the possibility to add Handler. This is a single homogeneous and effective implementation of all the FIPA-Request-like interaction protocols defined by FIPA, that is all those protocols where the initiator sends a single message (i.e. it performs a single communicative act) within the scope of an interaction protocol in order to verify if the RE (Rational Effect) of the communicative act has been achieved or not.

FIPA has already specified a number of these interaction protocols, like FIPA-Request, FIPA-query, FIPA-Request-When, FIPA-recruiting, FIPA-brokering, FIPA-subscribe, that allows the initiator to verify if the expected rational effect of a single communicative act has been achieved.

The structure of these protocols is equal. The initiator sends a message (in general it performs a communicative act).

The responder can then reply by sending a not-understood, or a refuse to achieve the rational effect of the communicative act, or also an agree message to communicate the agreement to perform (possibly in the future) the communicative act. This first category of reply messages has been here identified as a response.

The responder performs the action and, finally, must respond with an inform of the result of the action (eventually just that the action has been done) or with a failure if anything went wrong. This second category of reply messages has been here identified as a result notification.

Notice that we have extended the protocol to make optional the transmission of the agree message. Infact, in most cases performing the action takes so short time that sending the agree message is just an useless and uneffective overhead; in such cases, the agree to perform the communicative act is subsumed by the reception of the following message in the protocol.

Read carefully the section of the JADE programmer's guide that describes the usage of this class.

Known bugs: The handler handleAllResponses is not called if the agree message is skipped and the inform message is received instead.

Version:

$Date: 2005-09-16 15:54:46 +0200 (ven, 16 set 2005) $ $Revision: 5780 $

Author:

Tiziana Trucco - TILab

See Also:

SimpleAchieveREResponder, AchieveREInitiator, AchieveREResponder, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.String	ALL_RESPONSES_KEY key to retrive all the responses received.
java.lang.String	ALL_RESULT_NOTIFICATIONS_KEY key to retrive the result notification received.
java.lang.String	REQUEST_KEY key to retrive from the datastore the ACLMessage passed in the constructor
java.lang.String	REQUEST_SENT_KEY key to retrive from the datastore the ACLMessage that has been sent.
java.lang.String	SECOND_REPLY_KEY key to retrive the second reply received.

Fields inherited from class jade.core.behaviours.Behaviour

myAgent

Constructor Summary

Constructors

Constructor and Description
SimpleAchieveREInitiator(Agent a, ACLMessage msg) Construct for the class by creating a new empty DataStore
SimpleAchieveREInitiator(Agent a, ACLMessage msg, DataStore store) Constructs a SimpleAchieveREInitiator behaviour

Method Summary

Modifier and Type	Method and Description
void	action() Runs the behaviour.
boolean	done() Check if this behaviour is done.
protected void	handleAgree(ACLMessage msg) This method is called every time an agree message is received, which is not out-of-sequence according to the protocol rules.
protected void	handleAllResponses(java.util.Vector msgs) This method is called when all the responses have been collected or when the timeout is expired.
protected void	handleAllResultNotifications(java.util.Vector msgs) This method is called when all the result notification messages have been collected.
protected void	handleFailure(ACLMessage msg) This method is called every time a failure message is received, which is not out-of-sequence according to the protocol rules.
protected void	handleInform(ACLMessage msg) This method is called every time a inform message is received, which is not out-of-sequence according to the protocol rules.
protected void	handleNotUnderstood(ACLMessage msg) This method is called every time a not-understood message is received, which is not out-of-sequence according to the protocol rules.
protected void	handleOutOfSequence(ACLMessage msg) This method is called every time a message is received, which is out-of-sequence according to the protocol rules.
protected void	handleRefuse(ACLMessage msg) This method is called every time a refuse message is received, which is not out-of-sequence according to the protocol rules.
void	onStart() This method is just an empty placeholders for subclasses.
protected ACLMessage	prepareRequest(ACLMessage msg) This method must return the ACLMessage to be sent.
void	reset() This method resets this behaviour so that it restarts from the initial state of the protocol with a null message.
void	reset(ACLMessage msg) This method resets this behaviour so that it restarts the protocol with another request message.

Methods inherited from class jade.core.behaviours.Behaviour

block, block, getAgent, getBehaviourName, getDataStore, getParent, isRunnable, onEnd, restart, root, setAgent, setBehaviourName, setDataStore

Methods inherited from class java.lang.Object

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

Field Detail

REQUEST_KEY

public final java.lang.String REQUEST_KEY

key to retrive from the datastore the ACLMessage passed in the constructor

REQUEST_SENT_KEY

public final java.lang.String REQUEST_SENT_KEY

key to retrive from the datastore the ACLMessage that has been sent.

SECOND_REPLY_KEY

public final java.lang.String SECOND_REPLY_KEY

key to retrive the second reply received.

ALL_RESPONSES_KEY

public final java.lang.String ALL_RESPONSES_KEY

key to retrive all the responses received.

ALL_RESULT_NOTIFICATIONS_KEY

public final java.lang.String ALL_RESULT_NOTIFICATIONS_KEY

key to retrive the result notification received.

Constructor Detail

SimpleAchieveREInitiator

public SimpleAchieveREInitiator(Agent a,
                                ACLMessage msg)

Construct for the class by creating a new empty DataStore

See Also:

SimpleAchieveREInitiator(Agent, ACLMessage, DataStore)

SimpleAchieveREInitiator

public SimpleAchieveREInitiator(Agent a,
                                ACLMessage msg,
                                DataStore store)

Constructs a SimpleAchieveREInitiator behaviour

Parameters:

a - The agent performing the protocol

msg - The message that must be used to initiate the protocol. Notice that in this simple implementation, the prepareMessage method returns a single message.

s - The DataStore that will be used by this SimpleAchieveREInitiator

Method Detail

action

public final void action()

Description copied from class: Behaviour

Runs the behaviour. This abstract method must be implemented by Behavioursubclasses to perform ordinary behaviour duty. An agent schedules its behaviours calling their action() method; since all the behaviours belonging to the same agent are scheduled cooperatively, this method must not enter in an endless loop and should return as soon as possible to preserve agent responsiveness. To split a long and slow task into smaller section, recursive behaviour aggregation may be used.

Specified by:

action in class Behaviour

See Also:

CompositeBehaviour

onStart

public void onStart()

Description copied from class: Behaviour

This method is just an empty placeholders for subclasses. It is executed just once before starting behaviour execution. Therefore, it acts as a prolog to the task represented by this Behaviour.

Overrides:

onStart in class Behaviour

done

public boolean done()

Description copied from class: Behaviour

Check if this behaviour is done. The agent scheduler calls this method to see whether a Behaviour still need to be run or it has completed its task. Concrete behaviours must implement this method to return their completion state. Finished behaviours are removed from the scheduling queue, while others are kept within to be run again when their turn comes again.

Specified by:

done in class Behaviour

Returns:

true if the behaviour has completely executed.

prepareRequest

protected ACLMessage prepareRequest(ACLMessage msg)

This method must return the ACLMessage to be sent. This default implementation just return the ACLMessage object passed in the constructor. Programmer might override the method in order to return a different ACLMessage. Note that for this simple version of protocol, the message will be just send to the first receiver set.

Parameters:

msg - the ACLMessage object passed in the constructor.

Returns:

a ACLMessage.

handleAgree

protected void handleAgree(ACLMessage msg)

This method is called every time an agree message is received, which is not out-of-sequence according to the protocol rules. This default implementation does nothing; programmers might wish to override the method in case they need to react to this event.

Parameters:

agree - the received agree message

handleRefuse

protected void handleRefuse(ACLMessage msg)

This method is called every time a refuse message is received, which is not out-of-sequence according to the protocol rules. This default implementation does nothing; programmers might wish to override the method in case they need to react to this event.

Parameters:

refuse - the received refuse message

handleNotUnderstood

protected void handleNotUnderstood(ACLMessage msg)

This method is called every time a not-understood message is received, which is not out-of-sequence according to the protocol rules. This default implementation does nothing; programmers might wish to override the method in case they need to react to this event.

Parameters:

notUnderstood - the received not-understood message

handleInform

protected void handleInform(ACLMessage msg)

This method is called every time a inform message is received, which is not out-of-sequence according to the protocol rules. This default implementation does nothing; programmers might wish to override the method in case they need to react to this event.

Parameters:

inform - the received inform message

handleFailure

protected void handleFailure(ACLMessage msg)

This method is called every time a failure message is received, which is not out-of-sequence according to the protocol rules. This default implementation does nothing; programmers might wish to override the method in case they need to react to this event.

Parameters:

failure - the received failure message

handleOutOfSequence

protected void handleOutOfSequence(ACLMessage msg)

This method is called every time a message is received, which is out-of-sequence according to the protocol rules. This default implementation does nothing; programmers might wish to override the method in case they need to react to this event.

Parameters:

msg - the received message

handleAllResponses

protected void handleAllResponses(java.util.Vector msgs)

This method is called when all the responses have been collected or when the timeout is expired. By response message we intend here all the agree, not-understood, refuse received messages, which are not not out-of-sequence according to the protocol rules. This default implementation does nothing; programmers might wish to override the method in case they need to react to this event by analysing all the messages in just one call.

Parameters:

responses - the Vector of ACLMessage objects that have been received

handleAllResultNotifications

protected void handleAllResultNotifications(java.util.Vector msgs)

This method is called when all the result notification messages have been collected. By result notification message we intend here all the inform, failure received messages, which are not not out-of-sequence according to the protocol rules. This default implementation does nothing; programmers might wish to override the method in case they need to react to this event by analysing all the messages in just one call.

Parameters:

resultNodifications - the Vector of ACLMessage object received

reset

public void reset()

This method resets this behaviour so that it restarts from the initial state of the protocol with a null message.

Overrides:

reset in class SimpleBehaviour

reset

public void reset(ACLMessage msg)

This method resets this behaviour so that it restarts the protocol with another request message.

Parameters:

msg - updates message to be sent.