jade.proto
Class ProposeInitiator

java.lang.Object
  |
  +--jade.core.behaviours.Behaviour
        |
        +--jade.core.behaviours.CompositeBehaviour
              |
              +--jade.core.behaviours.SerialBehaviour
                    |
                    +--jade.core.behaviours.FSMBehaviour
                          |
                          +--jade.proto.ProposeInitiator
All Implemented Interfaces:
Serializable, java.io.Serializable

public class ProposeInitiator
extends FSMBehaviour

This class implements the Fipa-Propose interaction protocol with an API similar and homogeneous to AchieveREInitiator.
This implementation works both for 1:1 and 1:N conversation and, of course, implements the role of the initiator of the protocol.

The following is a brief description of the protocol. The programmer should however refer to the FIPA Spec for a complete description.

The initiator sends a PROPOSE message to the Participant indicating that it will perform some action if the Participant agrees. The implementation of the callback method prepareInitiations must return the vector of messages to be sent (eventually a single message with multiple receivers).

The responders can then reply by sending a ACCEPT-PROPOSAL message. Alternatively, responders may send a REJECT-PROPOSAL, to refuse the proposal or, eventually, a NOT-UNDERSTOOD to communicate communication problems. This category of reply messages has been here identified as a response and can be handled via the handleAllResponses callback method. Specific handle callback methods for each type of communicative act are also available when the programmer wishes to handle them separately: handleRejectProposal, handleAcceptProposal, handleNotUnderstood

If a message were received, with the same value of this conversation-id, but that does not comply with the FIPA protocol, than the method handleOutOfSequence would be called.

This class can be extended by the programmer by overriding all the needed handle methods or, in alternative, appropriate behaviours can be registered for each handle via the registerHandle-type of methods. This last case is more difficult to use and proper care must be taken to properly use the DataStore of the Behaviour as a shared memory mechanism with the registered behaviour.

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

Since:
JADE3.1
Version:
$Date: 2005-09-16 15:54:46 +0200 (ven, 16 set 2005) $ $Revision: 5780 $
Author:
Jerome Picault - Motorola Labs
See Also:
ProposeResponder, AchieveREInitiator, FIPA Spec, Serialized Form

Field Summary
protected  java.lang.String ALL_INITIATIONS_K
          key to retrieve from the DataStore of the behaviour the vector of PROPOSE ACLMessage objects that have to be 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 responses.
protected static java.lang.String CHECK_IN_SEQ
           
protected static java.lang.String CHECK_SESSIONS
           
protected static java.lang.String DUMMY_FINAL
           
protected static java.lang.String HANDLE_ACCEPT_PROPOSAL
           
protected static java.lang.String HANDLE_ALL_RESPONSES
           
protected static java.lang.String HANDLE_NOT_UNDERSTOOD
           
protected static java.lang.String HANDLE_OUT_OF_SEQ
           
protected static java.lang.String HANDLE_REJECT_PROPOSAL
           
protected  java.lang.String INITIATION_K
          key to retrieve from the DataStore of the behaviour the ACLMessage object passed in the constructor of the class.
protected static java.lang.String PREPARE_INITIATIONS
           
protected static java.lang.String RECEIVE_REPLY
           
 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).
protected static java.lang.String SEND_INITIATIONS
           
 
Fields inherited from class jade.core.behaviours.FSMBehaviour
currentName, lastStates
 
Fields inherited from class jade.core.behaviours.Behaviour
myAgent
 
Constructor Summary
ProposeInitiator(Agent a, ACLMessage msg)
          Construct a ProposeInitiator with an empty DataStore
ProposeInitiator(Agent a, ACLMessage initiation, DataStore store)
          Construct a ProposeInitiator with a given DataStore
 
Method Summary
protected  boolean checkInSequence(ACLMessage reply)
          Check whether a reply is in-sequence and update the appropriate Session.
protected  int checkSessions(ACLMessage reply)
          Check the status of the sessions after the reception of the last reply or the expiration of the timeout.
protected  java.lang.String createConvId(java.util.Vector msgs)
          Create a new conversation identifier to begin a new interaction.
protected  void handleAcceptProposal(ACLMessage accept_proposal)
          This method is called every time an accept-proposal 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 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 handleRejectProposal(ACLMessage reject_proposal)
          This method is called every time an reject-proposal message is received, which is not out-of-sequence according to the protocol rules.
protected  void initializeDataStore(ACLMessage msg)
          Initialize the data store.
 void onStart()
          Override the onStart() method to initialize the vectors that will keep all the replies in the data store.
protected  java.util.Vector prepareInitiations(ACLMessage propose)
          This method must return the vector of ACLMessage objects to be sent.
 void registerHandleAcceptProposal(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_ACCEPT_PROPOSAL state.
 void registerHandleAllResponses(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_ALL_RESPONSES 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 registerHandleRejectProposal(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_REJECT_PROPOSAL state.
 void reset()
          reset this behaviour by putting a null ACLMessage as message to be sent
 void reset(ACLMessage msg)
          reset this behaviour
protected  void sendInitiations(java.util.Vector initiations)
          Create and initialize the Sessions and sends the initiation messages.
 void setDataStore(DataStore ds)
          Override the setDataStore() method to initialize 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

INITIATION_K

protected final java.lang.String INITIATION_K
key to retrieve from the DataStore of the behaviour the ACLMessage object passed in the constructor of the class.


ALL_INITIATIONS_K

protected final java.lang.String ALL_INITIATIONS_K
key to retrieve from the DataStore of the behaviour the vector of PROPOSE ACLMessage objects that have to be 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 responses.


PREPARE_INITIATIONS

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

SEND_INITIATIONS

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

RECEIVE_REPLY

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

CHECK_IN_SEQ

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

HANDLE_NOT_UNDERSTOOD

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

HANDLE_OUT_OF_SEQ

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

HANDLE_ALL_RESPONSES

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

HANDLE_REJECT_PROPOSAL

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

HANDLE_ACCEPT_PROPOSAL

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

CHECK_SESSIONS

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

DUMMY_FINAL

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

ProposeInitiator

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

See Also:
ProposeInitiator(Agent, ACLMessage, DataStore)

ProposeInitiator

public ProposeInitiator(Agent a,
                        ACLMessage initiation,
                        DataStore store)
Construct a ProposeInitiator with a given DataStore

Parameters:
a - The agent performing the protocol
initiation - The message that must be used to initiate the protocol. Notice that the default implementation of the prepareInitiations() 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 ProposeInitiator
Method Detail

initializeDataStore

protected void initializeDataStore(ACLMessage msg)
Initialize the data store.


sendInitiations

protected void sendInitiations(java.util.Vector initiations)
Create and initialize the Sessions and sends the initiation messages. This method is called internally by the framework and is not intended to be called by the user


checkInSequence

protected boolean checkInSequence(ACLMessage reply)
Check whether a reply is in-sequence and update the appropriate Session. This method is called internally by the framework and is not intended to be called by the user


checkSessions

protected int checkSessions(ACLMessage reply)
Check the status of the sessions after the reception of the last reply or the expiration of the timeout. This method is called internally by the framework and is not intended to be called by the user


prepareInitiations

protected java.util.Vector prepareInitiations(ACLMessage propose)
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 (a PROPOSE) passed in the constructor. Programmers might prefer to override this method in order to return a vector of PROPOSE objects for 1:N conversations or also to prepare the messages during the execution of the behaviour.

Parameters:
propose - the ACLMessage object passed in the constructor
Returns:
a Vector of ACLMessage objects. The value of the slot reply-with is ignored and regenerated automatically by this class.

handleAcceptProposal

protected void handleAcceptProposal(ACLMessage accept_proposal)
This method is called every time an accept-proposal 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:
accept_proposal - the received accept-proposal message

handleRejectProposal

protected void handleRejectProposal(ACLMessage reject_proposal)
This method is called every time an reject-proposal 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:
reject_proposal - the received reject-proposal message

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

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

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

registerHandleAcceptProposal

public void registerHandleAcceptProposal(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_ACCEPT_PROPOSAL 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

registerHandleRejectProposal

public void registerHandleRejectProposal(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_REJECT_PROPOSAL 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

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

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

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 accept-proposal, reject-proposal, not-understood 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

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 initialize 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