jade.proto
Class ContractNetResponder

java.lang.Object
  jade.core.behaviours.Behaviour
      jade.core.behaviours.CompositeBehaviour
          jade.core.behaviours.SerialBehaviour
              jade.core.behaviours.FSMBehaviour
                  jade.proto.SSContractNetResponder
                      jade.proto.ContractNetResponder

All Implemented Interfaces:

java.io.Serializable

public class ContractNetResponder
extends SSContractNetResponder

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: 2006-05-25 15:29:42 +0200 (gio, 25 mag 2006) $ $Revision: 5884 $

Author:

Fabio Bellifemine - TILAB, Giovanni Caire - TILAB, Marco Monticone - TILAB

See Also:

ContractNetInitiator, AchieveREResponder, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class jade.core.behaviours.Behaviour

Behaviour.RunnableChangedEvent

Field Summary

protected static java.lang.String	CHECK_IN_SEQ
protected static java.lang.String	DUMMY_FINAL
protected static java.lang.String	HANDLE_OUT_OF_SEQUENCE
java.lang.String	INITIATION_KEY Key to retrieve from the DataStore of the behaviour the initiation ACLMessage that triggered this responder session
java.lang.String	PROPOSE_ACCEPTANCE_KEY Deprecated. Use either ACCEPT_PROPOSAL_KEY or REJECT_PROPOSAL_KEY according to the message that has been received
static java.lang.String	RECEIVE_CFP
protected static java.lang.String	RECEIVE_NEXT
java.lang.String	RECEIVED_KEY Key to retrieve from the DataStore of the behaviour the last received ACLMessage
java.lang.String	REPLY_KEY Key to set into the DataStore of the behaviour the new ACLMessage to be sent back to the initiator as a reply.
java.lang.String	RESPONSE_KEY Deprecated. Use REPLY_KEY
java.lang.String	RESULT_NOTIFICATION_KEY Deprecated. Use REPLY_KEY
protected static java.lang.String	SEND_REPLY

Fields inherited from class jade.proto.SSContractNetResponder

ACCEPT_PROPOSAL_KEY, CFP_KEY, HANDLE_ACCEPT_PROPOSAL, HANDLE_CFP, HANDLE_REJECT_PROPOSAL, PROPOSE_KEY, REJECT_PROPOSAL_KEY

Fields inherited from class jade.core.behaviours.FSMBehaviour

currentName, lastStates

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 ACLMessage	handleAcceptProposal(ACLMessage cfp, ACLMessage propose, ACLMessage accept) Redefine this method to call prepareResultNotification()
protected ACLMessage	handleCfp(ACLMessage cfp) Redefine this method to call prepareResponse()
void	onStart() This method is just an empty placeholders for subclasses.
protected ACLMessage	prepareResponse(ACLMessage cfp) Deprecated. Use handleCfp() instead
protected ACLMessage	prepareResultNotification(ACLMessage cfp, ACLMessage propose, ACLMessage accept) Deprecated. Use handleAcceptProposal() instead.
protected void	registerDSState(Behaviour b, java.lang.String name) Utility method to register a behaviour in a state of the protocol and set the DataStore appropriately
void	registerHandleCfp(Behaviour b) Redefine this method so that the HANDLE_CFP state is not registered as first state
void	registerHandleOutOfSequence(Behaviour b) This method allows to register a user defined Behaviour in the HANDLE_OUT_OF_SEQ state.
void	registerPrepareResponse(Behaviour b) Deprecated. Use registerHandleCfp() instead.
void	registerPrepareResultNotification(Behaviour b) Deprecated. Use registerHandleAcceptProposal() instead.
void	reset() Reset this behaviour.
protected void	sessionTerminated() This method can be redefined by protocol specific implementations to take proper actions after the completion of the current protocol session.

Methods inherited from class jade.proto.SSContractNetResponder

afterReply, beforeReply, checkInSequence, handleOutOfSequence, handleOutOfSequence, handleRejectProposal, registerHandleAcceptProposal, registerHandleRejectProposal, reinit

Methods inherited from class jade.core.behaviours.FSMBehaviour

checkTermination, deregisterDefaultTransition, deregisterState, deregisterTransition, forceTransitionTo, getChildren, getCurrent, getLastExitValue, getName, getPrevious, getState, handleInconsistentFSM, handleStateEntered, hasDefaultTransition, onEnd, registerDefaultTransition, registerDefaultTransition, registerFirstState, registerLastState, registerState, registerTransition, registerTransition, resetStates, scheduleFirst, scheduleNext, stringifyTransitionTable

Methods inherited from class jade.core.behaviours.SerialBehaviour

handle

Methods inherited from class jade.core.behaviours.CompositeBehaviour

action, done, handleBlockEvent, handleRestartEvent, registerAsChild, resetChildren, setAgent

Methods inherited from class jade.core.behaviours.Behaviour

actionWrapper, block, block, getBehaviourName, getDataStore, getExecutionState, getParent, getRestartCounter, isRunnable, restart, root, setBehaviourName, setDataStore, setExecutionState

Methods inherited from class java.lang.Object

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

Field Detail

RESPONSE_KEY

public final java.lang.String RESPONSE_KEY

Deprecated. Use REPLY_KEY

PROPOSE_ACCEPTANCE_KEY

public final java.lang.String PROPOSE_ACCEPTANCE_KEY

Deprecated. Use either ACCEPT_PROPOSAL_KEY or REJECT_PROPOSAL_KEY according to the message that has been received

RESULT_NOTIFICATION_KEY

public final java.lang.String RESULT_NOTIFICATION_KEY

Deprecated. Use REPLY_KEY

RECEIVE_CFP

public static final java.lang.String RECEIVE_CFP

See Also:

Constant Field Values

INITIATION_KEY

public final java.lang.String INITIATION_KEY

Key to retrieve from the DataStore of the behaviour the initiation ACLMessage that triggered this responder session

RECEIVED_KEY

public final java.lang.String RECEIVED_KEY

Key to retrieve from the DataStore of the behaviour the last received ACLMessage

REPLY_KEY

public final java.lang.String REPLY_KEY

Key to set into the DataStore of the behaviour the new ACLMessage to be sent back to the initiator as a reply.

RECEIVE_NEXT

protected static final java.lang.String RECEIVE_NEXT

See Also:

Constant Field Values

CHECK_IN_SEQ

protected static final java.lang.String CHECK_IN_SEQ

See Also:

Constant Field Values

HANDLE_OUT_OF_SEQUENCE

protected static final java.lang.String HANDLE_OUT_OF_SEQUENCE

See Also:

Constant Field Values

SEND_REPLY

protected static final java.lang.String SEND_REPLY

See Also:

Constant Field Values

DUMMY_FINAL

protected static final java.lang.String DUMMY_FINAL

See Also:

Constant Field Values

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

prepareResponse

protected ACLMessage prepareResponse(ACLMessage cfp)
                              throws NotUnderstoodException,
                                     RefuseException

Deprecated. Use handleCfp() instead

Throws:

NotUnderstoodException

RefuseException

prepareResultNotification

protected ACLMessage prepareResultNotification(ACLMessage cfp,
                                               ACLMessage propose,
                                               ACLMessage accept)
                                        throws FailureException

Deprecated. Use handleAcceptProposal() instead.

Throws:

FailureException

registerPrepareResponse

public void registerPrepareResponse(Behaviour b)

Deprecated. Use registerHandleCfp() instead.

registerPrepareResultNotification

public void registerPrepareResultNotification(Behaviour b)

Deprecated. Use registerHandleAcceptProposal() instead.

handleCfp

protected ACLMessage handleCfp(ACLMessage cfp)
                        throws RefuseException,
                               FailureException,
                               NotUnderstoodException

Redefine this method to call prepareResponse()

Overrides:

handleCfp in class SSContractNetResponder

Parameters:

cfp - the initial CFP message to handle.

Returns:

the reply message to be sent back to the initiator. Returning a message different than PROPOSE (or returning null) terminates the protocol.

Throws:

RefuseException - if the CFP is refused. Throwing a RefuseException has the same effect as returning a REFUSE message, but automatically manages the :content slot.

FailureException - if there is an error serving the CFP. Throwing a FailureException has the same effect as returning a FAILURE message, but automatically manages the :content slot.

NotUnderstoodException - if the CFP content is not understood. Throwing a NotUnderstoodException has the same effect as returning a NOT_UNDERSTOOD message, but automatically manages the :content slot.

handleAcceptProposal

protected ACLMessage handleAcceptProposal(ACLMessage cfp,
                                          ACLMessage propose,
                                          ACLMessage accept)
                                   throws FailureException

Redefine this method to call prepareResultNotification()

Overrides:

handleAcceptProposal in class SSContractNetResponder

Parameters:

cfp - the initial CFP message.

propose - the PROPOSE message sent back as reply to the initial CFP message.

accept - the received ACCEPT_PROPOSAL message.

Returns:

the reply message to be sent back to the initiator.

Throws:

FailureException - if there is an error serving the ACCEPT_PROPOSAL. Throwing a FailureException has the same effect as returning a FAILURE message, but automatically manages the :content slot.

registerHandleCfp

public void registerHandleCfp(Behaviour b)

Redefine this method so that the HANDLE_CFP state is not registered as first state

Overrides:

registerHandleCfp in class SSContractNetResponder

Parameters:

b - the Behaviour that will handle this state

sessionTerminated

protected void sessionTerminated()

This method can be redefined by protocol specific implementations to take proper actions after the completion of the current protocol session.

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

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

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 sets 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 RECEIVED_KEY key.

Parameters:

b - the Behaviour that will handle this state

reset

public void reset()

Reset this behaviour.

Overrides:

reset in class FSMBehaviour

registerDSState

protected void registerDSState(Behaviour b,
                               java.lang.String name)

Utility method to register a behaviour in a state of the protocol and set the DataStore appropriately