jade.proto
Class TwoPh0Initiator

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

All Implemented Interfaces:

java.io.Serializable

public class TwoPh0Initiator
extends FSMBehaviour

Class description

Author:

Elena Quarantotto - TILAB, Giovanni Caire - TILAB

See Also:

Serialized Form

Nested Class Summary

protected static interface

Initiator.ProtocolSession Inner interface Session

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

Behaviour.RunnableChangedEvent

Field Summary

java.lang.String	ALL_CFPS_KEY key to retrieve from the DataStore of the behaviour the vector of CFP messages that have to be sent.
protected java.lang.String	ALL_INITIATIONS_K
java.lang.String	ALL_PENDINGS_KEY key to retrieve from the DataStore of the behaviour the vector of CFP messages for which a response has not been received yet.
java.lang.String	ALL_PROPOSES_KEY key to retrieve from the DataStore of the behaviour the vector of PROPOSE messages that have been received as response.
java.lang.String	ALL_RESPONSES_KEY key to retrieve from the DataStore of the behaviour the vector of all messages that have been received as response.
java.lang.String	CFP_KEY key to retrieve from the DataStore of the behaviour the ACLMessage object passed in the constructor of the class.
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_FAILURE
protected static java.lang.String	HANDLE_NOT_UNDERSTOOD
protected static java.lang.String	HANDLE_OUT_OF_SEQ
protected java.lang.String	INITIATION_K
protected static java.lang.String	PREPARE_INITIATIONS
protected static java.lang.String	RECEIVE_REPLY
protected java.lang.String	REPLY_K
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 jade.proto.states.MsgReceiver	replyReceiver
protected MessageTemplate	replyTemplate
protected static java.lang.String	SEND_INITIATIONS
protected Map	sessions

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

TwoPh0Initiator(Agent a, ACLMessage cfp, java.lang.String outputKey)
Constructs a TwoPh0Initiator behaviour.

TwoPh0Initiator(Agent a, ACLMessage cfp, java.lang.String outputKey, DataStore store)
Constructs a TwoPh0Initiator behaviour.

Method Summary

protected void	adjustReplyTemplate(ACLMessage msg)
protected boolean	checkInSequence(ACLMessage reply) Check whether a reply is in-sequence and than update the appropriate Session and removes corresponding cfp from vector of pendings.
protected int	checkSessions(ACLMessage reply) Check if there are still active sessions or if timeout is expired.
protected java.lang.String	createConvId(java.util.Vector msgs) Create a new conversation identifier to begin a new interaction.
protected Initiator.ProtocolSession	getSession(ACLMessage msg, int sessionIndex) Return a ProtocolSession object to manage replies to a given initiation message
protected java.lang.String[]	getToBeReset() Return the states that must be reset before they are visited again.
protected void	handleAllResponses(java.util.Vector responses, java.util.Vector proposes, java.util.Vector pendings, java.util.Vector nextPhMsgs) This method is called when all the responses have been collected or when the timeout is expired.
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	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) This method is called every time a propose message is received, which is not out-of-sequence according to the protocol rules.
protected void	initializeDataStore(ACLMessage msg) Initialize the data store.
int	onEnd() Override the onEnd() method to return the exit value of the last executed state.
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.
protected java.util.Vector	prepareInitiations(ACLMessage initiation) Prepare vector containing cfps.
void	registerHandleAllResponses(Behaviour b) This method allows to register a user defined Behaviour in the HANDLE_ALL_RESPONSES state.
void	registerHandleFailure(Behaviour b) This method allows to register a user defined Behaviour in the HANDLE_FAILURE 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	registerPrepareCfps(Behaviour b) This method allows to register a user-defined Behaviour in the PREPARE_CFPS state.
protected void	registerPrepareInitiations(Behaviour b) Attach a behaviour to the Prepare-initiations protocol 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
protected void	sendInitiations(java.util.Vector initiations) This method sets for all prepared cfps conversation-id slot (with value passed in the constructor), protocol slot and reply-with slot with a unique value constructed by concatenating receiver's agent name and phase number (i.e. 0).
void	setDataStore(DataStore ds) Override the setDataStore() method to propagate this setting to all children.

Methods inherited from class jade.core.behaviours.FSMBehaviour

checkTermination, deregisterDefaultTransition, deregisterState, deregisterTransition, forceTransitionTo, getChildren, getCurrent, getLastExitValue, getName, getPrevious, getState, handleInconsistentFSM, handleStateEntered, hasDefaultTransition, 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, setExecutionState

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 messages 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 all messages that have been received as response.

ALL_PROPOSES_KEY

public final java.lang.String ALL_PROPOSES_KEY

key to retrieve from the DataStore of the behaviour the vector of PROPOSE messages that have been received as response.

ALL_PENDINGS_KEY

public final java.lang.String ALL_PENDINGS_KEY

key to retrieve from the DataStore of the behaviour the vector of CFP messages for which a response has not been received yet.

INITIATION_K

protected final java.lang.String INITIATION_K

ALL_INITIATIONS_K

protected final java.lang.String ALL_INITIATIONS_K

REPLY_K

protected final java.lang.String REPLY_K

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_FAILURE

protected static final java.lang.String HANDLE_FAILURE

See Also:

Constant Field Values

HANDLE_OUT_OF_SEQ

protected static final java.lang.String HANDLE_OUT_OF_SEQ

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

sessions

protected Map sessions

replyReceiver

protected jade.proto.states.MsgReceiver replyReceiver

replyTemplate

protected MessageTemplate replyTemplate

Constructor Detail

TwoPh0Initiator

public TwoPh0Initiator(Agent a,
                       ACLMessage cfp,
                       java.lang.String outputKey)

Constructs a TwoPh0Initiator behaviour.

Parameters:

a - The agent performing the protocol.

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

outputKey - Data store key where the behaviour will store the Vector of messages to be sent to initiate the successive phase.

TwoPh0Initiator

public TwoPh0Initiator(Agent a,
                       ACLMessage cfp,
                       java.lang.String outputKey,
                       DataStore store)

Constructs a TwoPh0Initiator behaviour.

Parameters:

a - The agent performing the protocol.

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

outputKey - Data store key where the behaviour will store the Vector of messages to be sent to initiate the successive phase.

store - DataStore that will be used by this TwoPh0Initiator.

Method Detail

onEnd

public int onEnd()

Description copied from class: FSMBehaviour

Override the onEnd() method to return the exit value of the last executed state.

Overrides:

onEnd in class FSMBehaviour

Returns:

an integer code representing the termination value of the behaviour.

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.

Parameters:

cfp - the ACLMessage object passed in the constructor

Returns:

a vector of ACLMessage objects. The value of the reply-with slot is ignored and regenerated automatically by this class. Instead user can specify reply-by slot representing phase0 timeout.

handlePropose

protected void handlePropose(ACLMessage propose)

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

handleAllResponses

protected void handleAllResponses(java.util.Vector responses,
                                  java.util.Vector proposes,
                                  java.util.Vector pendings,
                                  java.util.Vector nextPhMsgs)

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 reply-By of all the sent messages. By response message we intend here all the propose, failure, not-understood received messages, which are not out-of-sequence according to the protocol rules. This default implementation does nothing; programmers might wish to override this method to modify the Vector of initiation messages (nextPhMsgs) for next phase. More in details this Vector already includes messages with the performative set according to the default protocol rules i.e. QUERY_IF (if all responders replied with PROPOSE) or REJECT_PROPOSAL (if at least one responder failed or didn't reply). In particular, by setting the reply-by slot, users can specify a timeout for next phase.

Parameters:

responses - The Vector of all messages received as response

proposes - The Vector of PROPOSE messages received as response

pendings - The Vector of CFP messages for which a response has not been received yet

nextPhMsgs - The Vector of initiation messages for next phase already filled with QUERY_IF messages (if all responders replied with PROPOSE) or REJECT_PROPOSAL (if at least one responder failed or didn't reply).

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.

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 proposes, failures, pending and responses from the datastore at ALL_PROPOSES_KEY, ALL_FAILURES_KEY, ALL_PH0_PENDINGS_KEY and output field.

Parameters:

b - the Behaviour that will handle this state

getToBeReset

protected java.lang.String[] getToBeReset()

Return the states that must be reset before they are visited again. Note that resetting a state before visiting it again is required only if - The onStart() method is redefined - The state has an "internal memory"

prepareInitiations

protected final java.util.Vector prepareInitiations(ACLMessage initiation)

Prepare vector containing cfps.

Parameters:

initiation - cfp passed in the constructor

Returns:

Vector of cfps

sendInitiations

protected final void sendInitiations(java.util.Vector initiations)

This method sets for all prepared cfps conversation-id slot (with value passed in the constructor), protocol slot and reply-with slot with a unique value constructed by concatenating receiver's agent name and phase number (i.e. 0). After that it sends all cfps.

Parameters:

initiations - vector prepared in PREPARE_CFPS state

checkInSequence

protected final boolean checkInSequence(ACLMessage reply)

Check whether a reply is in-sequence and than update the appropriate Session and removes corresponding cfp from vector of pendings.

Parameters:

reply - message received

Returns:

true if reply is compliant with flow of protocol, false otherwise

checkSessions

protected final int checkSessions(ACLMessage reply)

Check if there are still active sessions or if timeout is expired.

Parameters:

reply - last message received

Returns:

ALL_RESPONSES_RECEIVED or -1 (still active sessions)

initializeDataStore

protected void initializeDataStore(ACLMessage msg)

Initialize the data store.

Parameters:

msg - Message passed in the constructor

getSession

protected Initiator.ProtocolSession getSession(ACLMessage msg,
                                               int sessionIndex)

Return a ProtocolSession object to manage replies to a given initiation 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

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

registerPrepareInitiations

protected void registerPrepareInitiations(Behaviour b)

Attach a behaviour to the Prepare-initiations protocol state.

Parameters:

b - The behaviour object to be executed in the Prepare-initiations 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

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

reinit

protected void reinit()

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

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.

adjustReplyTemplate

protected void adjustReplyTemplate(ACLMessage msg)