|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--jade.core.behaviours.Behaviour | +--jade.core.behaviours.CompositeBehaviour | +--jade.core.behaviours.FSMBehaviour | +--jade.proto.Initiator | +--jade.proto.ContractNetInitiator
This class implements the Fipa-Contract-Net 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 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
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:
handleRefuse, handlePropose, 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
elapsed) 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 notification and can be handled via the
handleAllResultNotification
callback method.
Again, specific handle callback
methods for each type of communicative act are also
available when the programmer wishes to handle them separately:
handleRefuse, handleInform
.
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.
ContractNetResponder
,
AchieveREInitiator
,
FIPA Spec, Serialized FormInner classes inherited from class jade.core.behaviours.Behaviour |
Behaviour.RunnableChangedEvent |
Field Summary | |
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.proto.Initiator |
ALL_INITIATIONS_K,
CHECK_IN_SEQ,
CHECK_SESSIONS,
DUMMY_FINAL,
HANDLE_FAILURE,
HANDLE_INFORM,
HANDLE_NOT_UNDERSTOOD,
HANDLE_OUT_OF_SEQ,
HANDLE_POSITIVE_RESPONSE,
HANDLE_REFUSE,
INITIATION_K,
PREPARE_INITIATIONS,
RECEIVE_REPLY,
REPLY_K,
replyReceiver,
replyTemplate,
SEND_INITIATIONS,
sessions,
toBeReset |
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 | |
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 | |
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 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 |
handlePositiveResponse(ACLMessage positiveResp)
|
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.
|
protected void |
initializeDataStore(ACLMessage msg)
Initialize 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)
|
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 |
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.
|
void |
reset(ACLMessage cfp)
reset this behaviour |
protected void |
sendInitiations(java.util.Vector initiations)
Create and initialize the Sessions and sends the initiation messages |
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.proto.Initiator |
adjustReplyTemplate,
createConvId,
onStart,
registerHandleFailure,
registerHandleInform,
registerHandleNotUnderstood,
registerHandleOutOfSequence,
registerHandlePositiveResponse,
registerHandleRefuse,
registerPrepareInitiations,
reset,
setDataStore |
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,
restart,
setAgent |
Methods inherited from class jade.core.behaviours.Behaviour |
actionWrapper,
block,
getBehaviourName,
getDataStore,
isRunnable,
root,
setBehaviourName |
Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Field Detail |
public final java.lang.String CFP_KEY
public final java.lang.String ALL_CFPS_KEY
public final java.lang.String ALL_ACCEPTANCES_KEY
public final java.lang.String REPLY_KEY
public final java.lang.String ALL_RESPONSES_KEY
public final java.lang.String ALL_RESULT_NOTIFICATIONS_KEY
Constructor Detail |
public ContractNetInitiator(Agent a, ACLMessage cfp)
ContractNetInitiator(Agent, ACLMessage, DataStore)
public ContractNetInitiator(Agent a, ACLMessage cfp, DataStore store)
ContractNetInitiator
behavioura
- The agent performing the protocolmsg
- 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 |
protected java.util.Vector prepareInitiations(ACLMessage initiation)
protected void sendInitiations(java.util.Vector initiations)
protected boolean checkInSequence(ACLMessage reply)
protected void handlePositiveResponse(ACLMessage positiveResp)
protected int checkSessions(ACLMessage reply)
protected java.util.Vector prepareCfps(ACLMessage cfp)
cfp
- the ACLMessage object passed in the constructorreply-with
is ignored and regenerated automatically
by this class.protected void handlePropose(ACLMessage propose, java.util.Vector acceptances)
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.propose
- the received propose messageacceptances
- 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.protected void handleRefuse(ACLMessage refuse)
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.refuse
- the received refuse messageprotected void handleNotUnderstood(ACLMessage notUnderstood)
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.notUnderstood
- the received not-understood messageprotected void handleInform(ACLMessage inform)
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.inform
- the received inform messageprotected void handleFailure(ACLMessage failure)
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.failure
- the received failure messageprotected void handleOutOfSequence(ACLMessage msg)
msg
- the received messageprotected void handleAllResponses(java.util.Vector responses, java.util.Vector acceptances)
replyBy
of all the sent messages.
By response message we intend here all the agree, 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.responses
- the Vector of ACLMessage objects that have been receivedacceptances
- 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.protected void handleAllResultNotifications(java.util.Vector resultNotifications)
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.resultNodifications
- the Vector of ACLMessage object receivedpublic void registerPrepareCfps(Behaviour b)
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.b
- the Behaviour that will handle this statepublic void registerHandlePropose(Behaviour b)
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
b
- the Behaviour that will handle this statepublic void registerHandleAllResponses(Behaviour b)
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
b
- the Behaviour that will handle this statepublic void registerHandleAllResultNotifications(Behaviour b)
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.b
- the Behaviour that will handle this statepublic void skipNextResponses()
public void reset(ACLMessage cfp)
msg
- is the ACLMessage to be sentprotected void initializeDataStore(ACLMessage msg)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |