jade.proto
Class SimpleAchieveREInitiator

java.lang.Object
  |
  +--jade.core.behaviours.Behaviour
        |
        +--jade.core.behaviours.SimpleBehaviour
              |
              +--jade.proto.SimpleAchieveREInitiator
Direct Known Subclasses:
RequestFIPAServiceBehaviour

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-propose, 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: 2002/03/14 14:59:43 $ $Revision: 1.1 $
Author:
Tiziana Trucco - TILab
See Also:
SimpleAchieveREResponder, AchieveREInitiator, AchieveREResponder, Serialized Form

Inner classes inherited from class jade.core.behaviours.Behaviour
Behaviour.RunnableChangedEvent
 
Field Summary
 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, myEvent, NOTIFY_DOWN, NOTIFY_UP, parent, STATE_BLOCKED, STATE_READY, STATE_RUNNING
 
Constructor Summary
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
 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
actionWrapper, block, block, getBehaviourName, getDataStore, handle, 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.
Overrides:
action in class Behaviour
Tags copied from 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.
Overrides:
done in class Behaviour
Tags copied from 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.