jade.proto

Class ContractNetInitiator

java.lang.Object

jade.core.behaviours.Behaviour

jade.core.behaviours.CompositeBehaviour

jade.core.behaviours.SerialBehaviour

jade.core.behaviours.FSMBehaviour

jade.proto.ContractNetInitiator

All Implemented Interfaces:

java.io.Serializable

public class ContractNetInitiator
extends FSMBehaviour

This class implements the initiator role in a Fipa-Contract-Net or Iterated-Fipa-Contract-Net interaction protocol.
This implementation works both for 1:1 and 1:N conversation.

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

The initiator solicits proposals from other agents by sending a CFP message that specifies the action to be performed and, if needed, conditions upon its execution. The implementation of the callback method prepareCfps must return the Vector of messages to be sent (eventually a single message with multiple receivers).

The responders can then reply by sending a PROPOSE message including the preconditions that they set out for the action, for instance the price or the time. Alternatively, responders may send a REFUSE, to refuse the proposal or, eventually, a NOT-UNDERSTOOD to communicate communication problems. This first category of reply messages has been here identified as a responses 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: handlePropose(), handleRefuse(), handleNotUnderstood().

The initiator can evaluate all the received proposals and make its choice of which agent proposals will be accepted and which will be rejected. This class provides two ways for this evaluation. It can be done progressively each time a new PROPOSE message is received and a new call to the handlePropose() callback method is executed or, in alternative, it can be done just once when all the PROPOSE messages have been collected (or the reply-by deadline has expired) and a single call to the handleAllResponses() callback method is executed. In both cases, the second parameter of the method, i.e. the Vector acceptances, must be filled with the appropriate ACCEPT/REJECT-PROPOSAL messages. Notice that, for the first case, the method skipNextResponses() has been provided that, if called by the programmer when waiting for PROPOSE messages, allows to skip to the next state and ignore all the responses and proposals that have not yet been received.

Once the responders whose proposal has been accepted (i.e. those that have received a ACCEPT-PROPOSAL message) have completed the task, they can, finally, 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 notifications and can be handled via the handleAllResultNotifications() callback method. Again, specific handle callback methods for each type of communicative act are also available when the programmer wishes to handle them separately: handleInform(), handleFailure().

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.

When needed this class can also be used to play the initiator role in an Iterated-Fipa-Contract-Net protocol. To activate a new CFP-PROPOSE iteration it is sufficient to invoke the newIteration() method from within the handleAllResponses() method.

Since:

JADE2.5

Version:

$Date: 2016-03-28 17:07:43 +0200 (lun, 28 mar 2016) $ $Revision: 6795 $

Author:

Giovanni Caire - TILab, Fabio Bellifemine - TILab, Tiziana Trucco - TILab, Marco Monticone - TILab

See Also:

ContractNetResponder, AchieveREInitiator, FIPA Spec, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.String	ALL_ACCEPTANCES_KEY key to retrieve from the DataStore of the behaviour the vector of ACCEPT/REJECT_PROPOSAL ACLMessage objects that have to be sent
java.lang.String	ALL_CFPS_KEY key to retrieve from the DataStore of the behaviour the vector of CFP 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 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.
java.lang.String	CFP_KEY key to retrieve from the DataStore of the behaviour the ACLMessage object passed in the constructor of the class.
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).

Fields inherited from class jade.core.behaviours.FSMBehaviour

currentName, lastStates

Fields inherited from class jade.core.behaviours.Behaviour

myAgent

Constructor Summary

Constructors

Constructor and Description
ContractNetInitiator(Agent a, ACLMessage cfp) Constructor for the class that creates a new empty DataStore
ContractNetInitiator(Agent a, ACLMessage cfp, DataStore store) Constructs a ContractNetInitiator behaviour

Method Summary

Modifier and Type	Method and Description
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	handleAllResponses(java.util.Vector responses, java.util.Vector acceptances) 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	handlePropose(ACLMessage propose, java.util.Vector acceptances) This method is called every time a propose message is received, which is not 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	moreAcceptances(java.util.Vector nextAcceptances) This method can be called to send acceptances to responder agents that replied with PROPOSE not all together but in more tranches.
void	newIteration(java.util.Vector nextMessages) This method can be called (typically within the handleAllResponses() method) to activate a new iteration (this means we are implementing an Iterated-Contract-Net protocol).
void	onStart() Override the onStart() method to initialize the vectors that will keep all the replies in the data store.
protected java.util.Vector	prepareCfps(ACLMessage cfp) This method must return the vector of ACLMessage objects to be sent.
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	registerHandlePropose(Behaviour b) This method allows to register a user defined Behaviour in the HANDLE_PROPOSE state.
void	registerHandleRefuse(Behaviour b) This method allows to register a user defined Behaviour in the HANDLE_REFUSE state.
void	registerPrepareCfps(Behaviour b) This method allows to register a user-defined Behaviour in the PREPARE_CFPS state.
protected void	reinit() Re-initialize the internal state without performing a complete reset.
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.
void	skipNextResponses() This method can be called (typically within the handlePropose() method) to skip all responses that have not been received yet.

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.CompositeBehaviour

action, done, resetChildren, setAgent

Methods inherited from class jade.core.behaviours.Behaviour

block, block, getAgent, getBehaviourName, getDataStore, getParent, isRunnable, restart, root, setBehaviourName

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 passed in the constructor of the class.

ALL_CFPS_KEY

public final java.lang.String ALL_CFPS_KEY

key to retrieve from the DataStore of the behaviour the vector of CFP ACLMessage objects that have to be sent.

ALL_ACCEPTANCES_KEY

public final java.lang.String ALL_ACCEPTANCES_KEY

key to retrieve from the DataStore of the behaviour the vector of ACCEPT/REJECT_PROPOSAL 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 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.

Constructor Detail

ContractNetInitiator

public ContractNetInitiator(Agent a,
                            ACLMessage cfp)

Constructor for the class that creates a new empty DataStore

See Also:

ContractNetInitiator(Agent, ACLMessage, DataStore)

ContractNetInitiator

public ContractNetInitiator(Agent a,
                            ACLMessage cfp,
                            DataStore store)

Constructs a ContractNetInitiator behaviour

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 prepareCfps method returns an array composed of that message only.

s - The DataStore that will be used by this ContractNetInitiator

Method Detail

prepareCfps

protected java.util.Vector prepareCfps(ACLMessage cfp)

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 CFP) passed in the constructor. Programmers might prefer to override this method in order to return a vector of CFP objects for 1:N conversations or also to prepare the messages during the execution of the behaviour.

Parameters:

cfp - 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.

handlePropose

protected void handlePropose(ACLMessage propose,
                             java.util.Vector acceptances)

This method is called every time a propose 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:

propose - the received propose message

acceptances - the list of ACCEPT/REJECT_PROPOSAL to be sent back. This list can be filled step by step redefining this method, or it can be filled at once redefining the handleAllResponses method.

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,
                                  java.util.Vector acceptances)

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 propose, 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

acceptances - the list of ACCEPT/REJECT_PROPOSAL to be sent back. This list can be filled at once redefining this method, or step by step redefining the handlePropose method.

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.

Parameters:

resultNodifications - the Vector of ACLMessage object received

registerPrepareCfps

public void registerPrepareCfps(Behaviour b)

This method allows to register a user-defined Behaviour in the PREPARE_CFPS 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_CFPS_KEY key.

Parameters:

b - the Behaviour that will handle this state

registerHandlePropose

public void registerHandlePropose(Behaviour b)

This method allows to register a user defined Behaviour in the HANDLE_PROPOSE 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 propose ACLMessage object received from the datastore at the REPLY_KEY key and the Vector of ACCEPT/REJECT_PROPOSAL to be sent back at the ALL_ACCEPTANCES_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

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

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 and the Vector of ACCEPT/REJECT_PROPOSAL to be sent back at the ALL_ACCEPTANCES_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

skipNextResponses

public void skipNextResponses()

This method can be called (typically within the handlePropose() method) to skip all responses that have not been received yet.

newIteration

public void newIteration(java.util.Vector nextMessages)

This method can be called (typically within the handleAllResponses() method) to activate a new iteration (this means we are implementing an Iterated-Contract-Net protocol).

Parameters:

nextMessages - The messages to be sent to responders at next iteration. Such messages can be CFPs (for responders actually involved in the next iteration) or REJECT_PROPOSALs (for responders no longer involved in the next iteration).

See Also:

SSIteratedContractNetResponder

moreAcceptances

public void moreAcceptances(java.util.Vector nextAcceptances)

This method can be called to send acceptances to responder agents that replied with PROPOSE not all together but in more tranches. This is useful, for instance, to send an ACCEPT_PROPOSAL to the best proposer immediately and the REJECT_PROPOSALs to the other proposers only after the reception of the final INFORM from the best proposer. To achieve that the first tranche of acceptances is managed normally. However by calling the moreAcceptances() method in one of the result notifications handler methods (i.e. handleInform(), handleFailure(), handleAllResultNotifications()) an additional tranche of acceptances is specified and the protocol goes on.

Parameters:

nextAcceptances - An additional tranche of acceptance messages

reinit

protected void reinit()

Re-initialize the internal state without performing a complete reset.

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.