jade.proto
Class AchieveREInitiator

java.lang.Object
  |
  +--jade.core.behaviours.Behaviour
        |
        +--jade.core.behaviours.CompositeBehaviour
              |
              +--jade.core.behaviours.SerialBehaviour
                    |
                    +--jade.core.behaviours.FSMBehaviour
                          |
                          +--jade.proto.Initiator
                                |
                                +--jade.proto.AchieveREInitiator
All Implemented Interfaces:
java.io.Serializable, Serializable
Direct Known Subclasses:
IteratedAchieveREInitiator

public class AchieveREInitiator
extends jade.proto.Initiator

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. This implementation works both for 1:1 and 1:N conversation.

FIPA has already specified a number of these interaction protocols, like FIPA-Request, FIPA-query, FIPA-Request-When, FIPA-recruiting, FIPA-brokering, 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.
One message for every receiver is sent instead of a single message for all the receivers.

Version:
$Date: 2005-12-01 14:09:42 +0100 (Thu, 01 Dec 2005) $ $Revision: 5839 $
Author:
Giovanni Caire - TILab, Fabio Bellifemine - TILab, Tiziana Trucco - TILab
See Also:
Serialized Form

Field Summary
 java.lang.String ALL_REQUESTS_KEY
          key to retrieve from the DataStore of the behaviour the vector of ACLMessage objects that have been sent.
 java.lang.String ALL_RESPONSES_KEY
          key to retrieve from the DataStore of the behaviour the vector of ACLMessage objects that have been received as response.
 java.lang.String ALL_RESULT_NOTIFICATIONS_KEY
          key to retrieve from the DataStore of the behaviour the vector of ACLMessage objects that have been received as result notifications.
protected static java.lang.String CHECK_AGAIN
           
protected static java.lang.String HANDLE_AGREE
           
protected static java.lang.String HANDLE_ALL_RESPONSES
           
protected static java.lang.String HANDLE_ALL_RESULT_NOTIFICATIONS
           
protected static java.lang.String HANDLE_INFORM
           
protected static java.lang.String HANDLE_REFUSE
           
 java.lang.String REPLY_KEY
          key to retrieve from the DataStore of the behaviour the last ACLMessage object that has been received (null if the timeout expired).
 java.lang.String REQUEST_KEY
          key to retrieve from the DataStore of the behaviour the ACLMessage object passed in the constructor of the class.
 
Fields inherited from class jade.core.behaviours.FSMBehaviour
currentName, lastStates, previousName
 
Fields inherited from class jade.core.behaviours.Behaviour
myAgent
 
Constructor Summary
AchieveREInitiator(Agent a, ACLMessage msg)
          Construct an AchieveREInitiator with an empty DataStore
AchieveREInitiator(Agent a, ACLMessage msg, DataStore store)
          Construct an AchieveREInitiator with a given DataStore
 
Method Summary
protected  java.lang.String createConvId(java.util.Vector msgs)
          Create a new conversation identifier to begin a new interaction.
protected  ProtocolSession getSession(ACLMessage msg, int sessionIndex)
           
protected  void handleAgree(ACLMessage agree)
          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 responses)
          This method is called when all the responses have been collected or when the timeout is expired.
protected  void handleAllResultNotifications(java.util.Vector resultNotifications)
          This method is called when all the result notification messages have been collected.
protected  void handleFailure(ACLMessage failure)
          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 inform)
          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 notUnderstood)
          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 refuse)
          This method is called every time a refuse message is received, which is not out-of-sequence according to the protocol rules.
 void onStart()
          Override the onStart() method to initialize the vectors that will keep all the replies in the data store.
protected  java.util.Vector prepareRequests(ACLMessage request)
          This method must return the vector of ACLMessage objects to be sent.
 void registerHandleAgree(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_AGREE state.
 void registerHandleAllResponses(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_ALL_RESPONSES state.
 void registerHandleAllResultNotifications(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_ALL_RESULT_NOTIFICATIONS state.
 void registerHandleFailure(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_FAILURE state.
 void registerHandleInform(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_INFORM state.
 void registerHandleNotUnderstood(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_NOT_UNDERSTOOD state.
 void registerHandleOutOfSequence(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_OUT_OF_SEQ state.
 void registerHandleRefuse(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_REFUSE state.
 void registerPrepareRequests(Behaviour b)
          This method allows to register a user defined Behaviour in the PREPARE_REQUESTS state.
protected  void reinit()
          reset this behaviour
 void reset()
          reset this behaviour by putting a null ACLMessage as message to be sent
 void reset(ACLMessage msg)
          reset this behaviour
 void setDataStore(DataStore ds)
          Override the setDataStore() method to propagate this setting to all children.
 
Methods inherited from class jade.core.behaviours.FSMBehaviour
checkTermination, deregisterState, forceTransitionTo, getChildren, getCurrent, getLastExitValue, getName, getPrevious, getState, handleInconsistentFSM, handleStateEntered, onEnd, registerDefaultTransition, registerDefaultTransition, registerFirstState, registerLastState, registerState, registerTransition, registerTransition, resetStates, scheduleFirst, scheduleNext
 
Methods inherited from class jade.core.behaviours.CompositeBehaviour
action, block, done, resetChildren, restart, setAgent
 
Methods inherited from class jade.core.behaviours.Behaviour
block, getBehaviourName, getDataStore, getParent, isRunnable, root, setBehaviourName
 
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 retrieve from the DataStore of the behaviour the ACLMessage object passed in the constructor of the class.


ALL_REQUESTS_KEY

public final java.lang.String ALL_REQUESTS_KEY
key to retrieve from the DataStore of the behaviour the vector of ACLMessage objects that have been sent.


REPLY_KEY

public final java.lang.String REPLY_KEY
key to retrieve from the DataStore of the behaviour the last ACLMessage object that has been received (null if the timeout expired).


ALL_RESPONSES_KEY

public final java.lang.String ALL_RESPONSES_KEY
key to retrieve from the DataStore of the behaviour the vector of ACLMessage objects that have been received as response.


ALL_RESULT_NOTIFICATIONS_KEY

public final java.lang.String ALL_RESULT_NOTIFICATIONS_KEY
key to retrieve from the DataStore of the behaviour the vector of ACLMessage objects that have been received as result notifications.


HANDLE_AGREE

protected static final java.lang.String HANDLE_AGREE
See Also:
Constant Field Values

HANDLE_REFUSE

protected static final java.lang.String HANDLE_REFUSE
See Also:
Constant Field Values

HANDLE_INFORM

protected static final java.lang.String HANDLE_INFORM
See Also:
Constant Field Values

HANDLE_ALL_RESPONSES

protected static final java.lang.String HANDLE_ALL_RESPONSES
See Also:
Constant Field Values

HANDLE_ALL_RESULT_NOTIFICATIONS

protected static final java.lang.String HANDLE_ALL_RESULT_NOTIFICATIONS
See Also:
Constant Field Values

CHECK_AGAIN

protected static final java.lang.String CHECK_AGAIN
See Also:
Constant Field Values
Constructor Detail

AchieveREInitiator

public AchieveREInitiator(Agent a,
                          ACLMessage msg)
Construct an AchieveREInitiator with an empty DataStore

See Also:
AchieveREInitiator(Agent, ACLMessage, DataStore)

AchieveREInitiator

public AchieveREInitiator(Agent a,
                          ACLMessage msg,
                          DataStore store)
Construct an AchieveREInitiator with a given DataStore

Parameters:
a - The agent performing the protocol
msg - The message that must be used to initiate the protocol. Notice that the default implementation of the prepareRequest() method returns an array composed of only this message. The values of the slot reply-with is ignored and a different value is assigned automatically by this class for each receiver.
store - The DataStore that will be used by this AchieveREInitiator
Method Detail

prepareRequests

protected java.util.Vector prepareRequests(ACLMessage request)
This method must return the vector of ACLMessage objects to be sent. It is called in the first state of this protocol. This default implementation just returns the ACLMessage object passed in the constructor. Programmers might prefer to override this method in order to return a vector of objects for 1:N conversations or also to prepare the messages during the execution of the behaviour.

Parameters:
request - the ACLMessage object passed in the constructor
Returns:
a Vector of ACLMessage objects. The values of the slot reply-with is ignored and a different value is assigned automatically by this class for each receiver.

handleAgree

protected void handleAgree(ACLMessage agree)
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 refuse)
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

handleInform

protected void handleInform(ACLMessage inform)
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

handleAllResponses

protected void handleAllResponses(java.util.Vector responses)
This method is called when all the responses have been collected or when the timeout is expired. The used timeout is the minimum value of the slot replyBy of all the sent messages. 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 resultNotifications)
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.


registerPrepareRequests

public void registerPrepareRequests(Behaviour b)
This method allows to register a user defined Behaviour in the PREPARE_REQUESTS state. This behaviour would override the homonymous method. This method also set the data store of the registered Behaviour to the DataStore of this current behaviour. It is responsibility of the registered behaviour to put the Vector of ACLMessage objects to be sent into the datastore at the ALL_REQUESTS_KEY key. The values of the slot reply-with is ignored and a different value is assigned automatically by this class for each receiver.

Parameters:
b - the Behaviour that will handle this state

registerHandleAgree

public void registerHandleAgree(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_AGREE state. This behaviour would override the homonymous method. This method also set the data store of the registered Behaviour to the DataStore of this current behaviour. The registered behaviour can retrieve the agree ACLMessage object received from the datastore at the REPLY_KEY key.

Parameters:
b - the Behaviour that will handle this state

registerHandleInform

public void registerHandleInform(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_INFORM state. This behaviour would override the homonymous method. This method also set the data store of the registered Behaviour to the DataStore of this current behaviour. The registered behaviour can retrieve the inform ACLMessage object received from the datastore at the REPLY_KEY key.

Parameters:
b - the Behaviour that will handle this state

registerHandleRefuse

public void registerHandleRefuse(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_REFUSE state. This behaviour would override the homonymous method. This method also set the data store of the registered Behaviour to the DataStore of this current behaviour. The registered behaviour can retrieve the refuse ACLMessage object received from the datastore at the REPLY_KEY key.

Parameters:
b - the Behaviour that will handle this state

registerHandleAllResponses

public void registerHandleAllResponses(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_ALL_RESPONSES state. This behaviour would override the homonymous method. This method also set the data store of the registered Behaviour to the DataStore of this current behaviour. The registered behaviour can retrieve the vector of ACLMessage objects, received as a response, from the datastore at the ALL_RESPONSES_KEY key.

Parameters:
b - the Behaviour that will handle this state

registerHandleAllResultNotifications

public void registerHandleAllResultNotifications(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_ALL_RESULT_NOTIFICATIONS state. This behaviour would override the homonymous method. This method also set the data store of the registered Behaviour to the DataStore of this current behaviour. The registered behaviour can retrieve the Vector of ACLMessage objects, received as a result notification, from the datastore at the ALL_RESULT_NOTIFICATIONS_KEY key.

Parameters:
b - the Behaviour that will handle this state

reinit

protected void reinit()
reset this behaviour

Overrides:
reinit in class jade.proto.Initiator

getSession

protected ProtocolSession getSession(ACLMessage msg,
                                     int sessionIndex)

handleNotUnderstood

protected void handleNotUnderstood(ACLMessage notUnderstood)
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

handleFailure

protected void handleFailure(ACLMessage failure)
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

registerHandleNotUnderstood

public void registerHandleNotUnderstood(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_NOT_UNDERSTOOD state. This behaviour would override the homonymous method. This method also set the data store of the registered Behaviour to the DataStore of this current behaviour. The registered behaviour can retrieve the not-understood ACLMessage object received from the datastore at the REPLY_KEY key.

Parameters:
b - the Behaviour that will handle this state

registerHandleFailure

public void registerHandleFailure(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_FAILURE state. This behaviour would override the homonymous method. This method also set the data store of the registered Behaviour to the DataStore of this current behaviour. The registered behaviour can retrieve the failure ACLMessage object received from the datastore at the REPLY_KEY key.

Parameters:
b - the Behaviour that will handle this state

registerHandleOutOfSequence

public void registerHandleOutOfSequence(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_OUT_OF_SEQ state. This behaviour would override the homonymous method. This method also set the data store of the registered Behaviour to the DataStore of this current behaviour. The registered behaviour can retrieve the out of sequence ACLMessage object received from the datastore at the REPLY_KEY key.

Parameters:
b - the Behaviour that will handle this state

reset

public void reset()
reset this behaviour by putting a null ACLMessage as message to be sent

Overrides:
reset in class FSMBehaviour

reset

public void reset(ACLMessage msg)
reset this behaviour

Parameters:
msg - is the ACLMessage to be sent

onStart

public void onStart()
Override the onStart() method to initialize the vectors that will keep all the replies in the data store.

Overrides:
onStart in class Behaviour

setDataStore

public void setDataStore(DataStore ds)
Override the setDataStore() method to propagate this setting to all children.

Overrides:
setDataStore in class Behaviour
Parameters:
ds - the DataStore that this Behaviour will use as its private data store

createConvId

protected java.lang.String createConvId(java.util.Vector msgs)
Create a new conversation identifier to begin a new interaction.

Parameters:
msgs - A vector of ACL messages. If the first one has a non-empty :conversation-id slot, its value is used, else a new conversation identifier is generated.


JADE