jade.proto
Class ContractNetResponder

java.lang.Object
  |
  +--jade.core.behaviours.Behaviour
        |
        +--jade.core.behaviours.CompositeBehaviour
              |
              +--jade.core.behaviours.FSMBehaviour
                    |
                    +--jade.proto.ContractNetResponder

public class ContractNetResponder
extends FSMBehaviour

Behaviour class for fipa-contract-net Responder role. This behaviour implements the fipa-contract-net interaction protocol from the point of view of a responder to a call for proposal (cfp) message.

The API of this class is similar and homogeneous to the AchieveREResponder.

Read also the introduction to ContractNetInitiator for a description of the protocol.

When a message arrives that matches the message template passed to the constructor, the callback method prepareResponse is executed that must return the wished response, for instance the PROPOSE reply message. Any other type of returned communicative act is sent and then closes the protocol.

Then, if the initiator accepted the proposal, i.e. if an ACCEPT-PROPOSAL message was received, the callback method prepareResultNotification would be executed that must return the message with the result notification, i.e. INFORM or FAILURE.
In alternative, if the initiator rejected the proposal, i.e. if an REJECT-PROPOSAL message was received, the callback method handleRejectProposal would be executed and the protocol terminated.

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.

Version:
$Date: 2003/03/19 11:16:01 $ $Revision: 1.9 $
Author:
Fabio Bellifemine - TILAB, Giovanni Caire - TILAB, Marco Monticone - TILAB
See Also:
ContractNetInitiator, AchieveREResponder, Serialized Form

Inner classes inherited from class jade.core.behaviours.Behaviour
Behaviour.RunnableChangedEvent
 
Field Summary
 java.lang.String CFP_KEY
          key to retrieve from the DataStore of the behaviour the ACLMessage object received by the initiator.
 java.lang.String PROPOSE_ACCEPTANCE_KEY
          key to retrieve from the DataStore of the behaviour the ACLMessage object sent as an ACCEPT/REJECT PROPOSAL response to the initiator CFP.
 java.lang.String PROPOSE_KEY
          key to retrieve from the DataStore of the behaviour the ACLMessage object sent as a response to the initiator CFP.
 java.lang.String RESULT_NOTIFICATION_KEY
          key to retrieve from the DataStore of the behaviour the ACLMessage object sent as a result notification to the initiator.
 
Fields inherited from class jade.core.behaviours.CompositeBehaviour
currentExecuted
 
Fields inherited from class jade.core.behaviours.Behaviour
myAgent, myEvent, NOTIFY_DOWN, NOTIFY_UP, parent, STATE_BLOCKED, STATE_READY, STATE_RUNNING
 
Constructor Summary
ContractNetResponder(Agent a, MessageTemplate mt)
          Constructor of the behaviour that creates a new empty DataStore
ContractNetResponder(Agent a, MessageTemplate mt, DataStore store)
          Constructor of the behaviour.
 
Method Summary
static MessageTemplate createMessageTemplate(java.lang.String iprotocol)
          This static method can be used to set the proper message Template (based on the interaction protocol and the performative) to be passed to the constructor of this behaviour.
protected  void handleOutOfSequence(ACLMessage cfp, ACLMessage propose, ACLMessage outOfSequenceMsg)
          This callback method is called after a message arrives that does not respect the protocol (i.e. a message with the correct in-reply-to field but with a unexpected performative).
protected  void handleRejectProposal(ACLMessage cfp, ACLMessage propose, ACLMessage rejectProposal)
          This method is called after the reject-propose has been received or the timeout expires, as expressed by the reply-by value of the PROPOSE reply.
protected  ACLMessage prepareResponse(ACLMessage request)
          This method is called when the initiator's message is received that matches the message template passed in the constructor.
protected  ACLMessage prepareResultNotification(ACLMessage cfp, ACLMessage propose, ACLMessage accept)
          This callback method is called after the acceptance has been sent and only if the response was an accept-propose message.
 void registerHandleOutOfSequnece(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_OUT_OF_SEQUENCE state.
 void registerHandleRejectProposal(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_REJECT state.
 void registerPrepareResponse(Behaviour b)
          This method allows to register a user defined Behaviour in the PREPARE_RESPONSE state.
 void registerPrepareResultNotification(Behaviour b)
          This method allows to register a user defined Behaviour in the PREPARE_RESULT_NOTIFICATION state.
 void reset()
          Reset the behaviour.
 void reset(MessageTemplate mt)
          This method reset the behaviour and allows to change the MessageTemplate that defines what messages this ContractNetResponder will react to.
 
Methods inherited from class jade.core.behaviours.FSMBehaviour
checkTermination, forceTransitionTo, getChildren, getCurrent, getLastExitValue, getName, getState, handle, onEnd, registerDefaultTransition, registerDefaultTransition, registerFirstState, registerLastState, registerState, registerTransition, registerTransition, resetStates, scheduleFirst, scheduleNext
 
Methods inherited from class jade.core.behaviours.CompositeBehaviour
action, block, done, onStart, restart, setAgent
 
Methods inherited from class jade.core.behaviours.Behaviour
actionWrapper, block, getBehaviourName, getDataStore, isRunnable, root, setBehaviourName, setDataStore
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CFP_KEY

public final java.lang.String CFP_KEY
key to retrieve from the DataStore of the behaviour the ACLMessage object received by the initiator.

PROPOSE_KEY

public final java.lang.String PROPOSE_KEY
key to retrieve from the DataStore of the behaviour the ACLMessage object sent as a response to the initiator CFP.

PROPOSE_ACCEPTANCE_KEY

public final java.lang.String PROPOSE_ACCEPTANCE_KEY
key to retrieve from the DataStore of the behaviour the ACLMessage object sent as an ACCEPT/REJECT PROPOSAL response to the initiator CFP.

RESULT_NOTIFICATION_KEY

public final java.lang.String RESULT_NOTIFICATION_KEY
key to retrieve from the DataStore of the behaviour the ACLMessage object sent as a result notification to the initiator.
Constructor Detail

ContractNetResponder

public ContractNetResponder(Agent a,
                            MessageTemplate mt)
Constructor of the behaviour that creates a new empty DataStore
See Also:
ContractNetResponder(Agent a, MessageTemplate mt, DataStore store)

ContractNetResponder

public ContractNetResponder(Agent a,
                            MessageTemplate mt,
                            DataStore store)
Constructor of the behaviour.
Parameters:
a - is the reference to the Agent object
mt - is the MessageTemplate that must be used to match the initiator message. Take care that if mt is null every message is consumed by this protocol. The best practice is to have a MessageTemplate that matches the protocol slot; the static method createMessageTemplate might be usefull.
store - the DataStore for this protocol behaviour
Method Detail

handleRejectProposal

protected void handleRejectProposal(ACLMessage cfp,
                                    ACLMessage propose,
                                    ACLMessage rejectProposal)
This method is called after the reject-propose has been received or the timeout expires, as expressed by the reply-by value of the PROPOSE reply. This default implementation do nothing. Programmers should override the method in case they need to react to this event. After the execution of this method this responder behaviour is automatically resetted.
Parameters:
cfp - the received message
propose - the previously sent propose message
rejectProposal - the received reject-propose message, null if the timeout expired

handleOutOfSequence

protected void handleOutOfSequence(ACLMessage cfp,
                                   ACLMessage propose,
                                   ACLMessage outOfSequenceMsg)
This callback method is called after a message arrives that does not respect the protocol (i.e. a message with the correct in-reply-to field but with a unexpected performative). This default implementation do nothing. Programmers should override the method in case they need to react to this event. After the execution of this method this responder behaviour is reset.
Parameters:
cfp - the received message
propose - the previously sent propose message
outOfSequence - the received message that does not respect the protocol

prepareResultNotification

protected ACLMessage prepareResultNotification(ACLMessage cfp,
                                               ACLMessage propose,
                                               ACLMessage accept)
                                        throws FailureException
This callback method is called after the acceptance has been sent and only if the response was an accept-propose message. This default implementation return null which has the effect of sending no result notification. Programmers should override the method in case they need to react to this event.
Parameters:
cfp - the received message
propose - the previously sent propose message
accept - the received accept-propose message
Returns:
the ACLMessage to be sent as a result notification (i.e. one of inform, failure. Remind to use the method createReply of the class ACLMessage in order to create a valid reply message
See Also:
ACLMessage.createReply()

registerHandleRejectProposal

public void registerHandleRejectProposal(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_REJECT 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 find the sent and receivet messages within the datastore at the keys: CFP_KEY, PROPOSE_KEY, PROPOSE_ACCEPTANCE_KEY_KEY,
Parameters:
b - the Behaviour that will handle this state

registerPrepareResponse

public void registerPrepareResponse(Behaviour b)
This method allows to register a user defined Behaviour in the PREPARE_RESPONSE 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 response to be sent into the datastore at the RESPONSE_KEY key.
Parameters:
b - the Behaviour that will handle this state

registerPrepareResultNotification

public void registerPrepareResultNotification(Behaviour b)
This method allows to register a user defined Behaviour in the PREPARE_RESULT_NOTIFICATION 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 result notification message to be sent into the datastore at the RESULT_NOTIFICATION_KEY key.
Parameters:
b - the Behaviour that will handle this state

registerHandleOutOfSequnece

public void registerHandleOutOfSequnece(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_OUT_OF_SEQUENCE 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 found the send and received message in the datastore at the keys: CFP_KEY, PROPOSE_KEY, PROPOSE_ACCEPTANCE_KEY_KEY,
Parameters:
b - the Behaviour that will handle this state

createMessageTemplate

public static MessageTemplate createMessageTemplate(java.lang.String iprotocol)
This static method can be used to set the proper message Template (based on the interaction protocol and the performative) to be passed to the constructor of this behaviour.
See Also:
FIPANames.InteractionProtocol

prepareResponse

protected ACLMessage prepareResponse(ACLMessage request)
                              throws NotUnderstoodException,
                                     RefuseException
This method is called when the initiator's message is received that matches the message template passed in the constructor. This default implementation return null which has the effect of sending no reponse. Programmers should override the method in case they need to react to this event.
Parameters:
request - the received message
Returns:
the ACLMessage to be sent as a response (i.e. one of PROPOSE, refuse, not-understood. Remind to use the method createReply of the class ACLMessage in order to create a valid reply message
See Also:
ACLMessage.createReply()

reset

public void reset()
Reset the behaviour.
Overrides:
reset in class FSMBehaviour

reset

public void reset(MessageTemplate mt)
This method reset the behaviour and allows to change the MessageTemplate that defines what messages this ContractNetResponder will react to.