|
|||||||||
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.SubscriptionInitiator
This is a single homogeneous and effective implementation of the initiator role in all the FIPA-Subscribe-like interaction protocols defined by FIPA, that is all those protocols where the initiator sends a single "subscription" message and receives notifications each time a given condition becomes true. This implementation works both for 1:1 and 1:N conversations.
FIPA has already specified a number of these interaction protocols, like FIPA-subscribe and FIPA-request-whenever.
The structure of these protocols is always the same. The initiator sends a "subscription" message (in general it performs a communicative act).
The responder can then reply by sending a not-understood
, a
refuse
or
an agree
message to communicate that the subscription has been
agreed. This first category
of reply messages has been here identified as a "response". Sending
no response is allowed and is equivalent to sending an agree
.
Each time the condition indicated within the subscription message becomes true, the responder sends proper "notification" messages to the initiator.
This behaviour terminates if a) neither a response nor a notification has been
received before the timeout set by the reply-by
of the
subscription message has expired or b) all responders replied with REFUSE
or NOT_UNDERSTOOD. Otherwise the behaviour will run forever.
NOTE that this implementation is in an experimental state and the API will possibly change in next versions also taking into account that the FIPA specifications related to subscribe-like protocols are not yet stable.
Read carefully the section of the
JADE programmer's guide
that describes
the usage of this class.
One message for every receiver is sent instead of a single
message for all the receivers.
Inner classes inherited from class jade.core.behaviours.Behaviour |
Behaviour.RunnableChangedEvent |
Field Summary | |
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 responses. |
java.lang.String |
ALL_SUBSCRIPTIONS_KEY
key to retrieve from the DataStore of the behaviour the vector of subscription ACLMessage objects that have been sent. |
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). |
java.lang.String |
SUBSCRIPTION_KEY
key to retrieve from the DataStore of the behaviour the subscription ACLMessage object passed in the constructor of the class. |
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 | |
SubscriptionInitiator(Agent a,
ACLMessage msg)
Construct a SubscriptionInitiator with an empty DataStore |
|
SubscriptionInitiator(Agent a,
ACLMessage msg,
DataStore store)
Construct a SubscriptionInitiator with a given DataStore |
Method Summary | |
void |
cancel(AID receiver,
boolean ignoreResponse)
Cancel the subscription to agent receiver .
|
void |
cancellationCompleted(AID receiver)
This method should be called when the notification of a successful subscription cancellation is received from agent receiver to terminate the session with him.
|
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 |
fillCancelContent(ACLMessage subscription,
ACLMessage cancel)
This method is used to fill the :content slot
of the CANCEL message that is being sent to an agent to cancel
the subscription previously activated by means of the
subscription message. |
protected void |
handleAgree(ACLMessage agree)
This method is called every time an agree
message is received, which is not out-of-sequence according
to the protocol rules.
|
protected void |
handleAllResponses(java.util.Vector responses)
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 |
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)
This method is called internally by the framework and is not intended to be called by the user |
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 |
prepareInitiations(ACLMessage initiation)
This method is called internally by the framework and is not intended to be called by the user |
protected java.util.Vector |
prepareSubscriptions(ACLMessage subscription)
This method must return the vector of subscription ACLMessage objects to be sent. |
void |
registerHandleAgree(Behaviour b)
This method allows to register a user defined Behaviour
in the HANDLE_AGREE state.
|
void |
registerHandleAllResponses(Behaviour b)
This method allows to register a user defined Behaviour
in the HANDLE_ALL_RESPONSES state.
|
void |
registerPrepareRequests(Behaviour b)
This method allows to register a user defined Behaviour
in the PREPARE_SUBSCRIPTIONS state.
|
void |
reset(ACLMessage msg)
reset this behaviour |
protected void |
sendInitiations(java.util.Vector initiations)
Create and initialize the Sessions and sends the initiation messages. |
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 SUBSCRIPTION_KEY
public final java.lang.String ALL_SUBSCRIPTIONS_KEY
public final java.lang.String REPLY_KEY
public final java.lang.String ALL_RESPONSES_KEY
Constructor Detail |
public SubscriptionInitiator(Agent a, ACLMessage msg)
SubscriptionInitiator
with an empty DataStoreSubscriptionInitiator(Agent, ACLMessage, DataStore)
public SubscriptionInitiator(Agent a, ACLMessage msg, DataStore store)
SubscriptionInitiator
with a given DataStorea
- The agent performing the protocolmsg
- The message that must be used to initiate the protocol.
Notice that the default implementation of the
prepareSubscription()
method returns
an array composed of only this message.
The values of the slot
reply-with
is ignored and a different value is assigned
automatically by this class for each receiver.store
- The DataStore
that will be used by this
SubscriptionInitiator
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 prepareSubscriptions(ACLMessage subscription)
subscription
- the ACLMessage object passed in the constructorreply-with
is ignored and a different value is assigned
automatically by this class for each receiver.protected void handleAgree(ACLMessage agree)
agree
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.agree
- the received agree messageprotected 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)
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 receivedpublic void registerPrepareRequests(Behaviour b)
Behaviour
in the PREPARE_SUBSCRIPTIONS 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.
It is responsibility of the registered behaviour to put the
Vector of ACLMessage objects to be sent
into the datastore at the ALL_SUBSCRIPTIONS_KEY
key.
The values of the slot
reply-with
is ignored and a different value is assigned
automatically by this class for each receiver.b
- the Behaviour that will handle this statepublic void registerHandleAgree(Behaviour b)
Behaviour
in the HANDLE_AGREE 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 agree
ACLMessage object received
from the datastore at the REPLY_KEY
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 sets 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.b
- the Behaviour that will handle this statepublic void cancel(AID receiver, boolean ignoreResponse)
receiver
.
This method retrieves the subscription message sent to
receiver
and sends a suitable CANCEL message with
the conversationID and all other protocol fields appropriately set.
The :content
slot of this CANCEL message is filled
in by means of the fillCancelContent()
method. The way the CANCEL content is set in fact is application
specific.receiver
- The agent to whom we are cancelling the subscription.ignoreResponse
- When receiving a CANCEL, the responder may
send back a response to notify that the subscription has been
cancelled (INFORM) or not (FAILURE). If this parameter is set to
true
this response is ignored and the session with
agent receiver
is immediately terminated. When
ignoreResponse
is set to false
, on the
other hand, the session with agent receiver
remains
active and the INFORM or FAILURE massage (if any) will be handled by the
HANDLE_INFORM
and HANDLE_FAILURE
states
as if they were normal notifications. It is responsibility of
the programmer to distinguish them and actually terminate the
session with agent receiver
by calling the
cancellationCompleted()
method.fillCancelContent(ACLMessage, ACLMessage)
,
cancellationCompleted(AID)
protected void fillCancelContent(ACLMessage subscription, ACLMessage cancel)
:content
slot
of the CANCEL message that is being sent to an agent to cancel
the subscription previously activated by means of the
subscription
message. Note that all other relevant
fields of the cancel
message have already been
set appropriately and the programmer should not modify them.
The default implementation just sets a null content (the responder
should be able to identify the subscription that has to be
cancelled on the basis of the sender and conversationID fields
of the CANCEL message). Programmers may override this method to
create an appropriate content as exemplified in the code below.
try { AID receiver = (AID) cancel.getAllReceiver().next(); Action a = new Action(receiver, OntoACLMessage.wrap(subscription)); getContentManager.fillContent(cancel, a); } catch (Exception e) { e.printStackTrace(); }
cancel(AID, boolean)
public void cancellationCompleted(AID receiver)
receiver
to terminate the session with him.
This method has some effect only if a cancellation for
agent receiver
was previously activated by
means of the cancel()
method.public void reset(ACLMessage msg)
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 |