|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectjade.core.behaviours.Behaviour
jade.core.behaviours.CompositeBehaviour
jade.core.behaviours.SerialBehaviour
jade.core.behaviours.FSMBehaviour
jade.proto.SubscriptionInitiator
public class 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.
| 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.core.behaviours.FSMBehaviour |
|---|
currentName, lastStates |
| Fields inherited from class jade.core.behaviours.Behaviour |
|---|
myAgent |
| 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 java.lang.String |
createConvId(java.util.Vector msgs)
Create a new conversation identifier to begin a new interaction. |
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 |
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 |
onStart()
Override the onStart() method to initialize the vectors that will keep all the replies in the data store. |
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 |
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 |
registerHandleRefuse(Behaviour b)
This method allows to register a user defined Behaviour
in the HANDLE_REFUSE state. |
void |
registerPrepareSubscriptions(Behaviour b)
This method allows to register a user defined Behaviour
in the PREPARE_SUBSCRIPTIONS 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. |
| Methods inherited from class jade.core.behaviours.CompositeBehaviour |
|---|
action, done, resetChildren, setAgent |
| Methods inherited from class jade.core.behaviours.Behaviour |
|---|
block, block, 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 |
|---|
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 DataStore
SubscriptionInitiator(Agent, ACLMessage, DataStore)
public SubscriptionInitiator(Agent a,
ACLMessage msg,
DataStore store)
SubscriptionInitiator with a given DataStore
a - 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 prepareSubscriptions(ACLMessage subscription)
subscription - the ACLMessage object passed in the constructor
reply-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 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 handleAllResponses(java.util.Vector responses)
replyBy
of all the sent messages.
By response message we intend here all the agree, not-understood,
refuse, failure received messages, which are
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 registerPrepareSubscriptions(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 registerHandleInform(Behaviour b)
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.
b - the Behaviour that will handle this statepublic void registerHandleRefuse(Behaviour b)
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.
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 state
public 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.
cancel(AID, boolean)protected void reinit()
protected 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 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 messagepublic void registerHandleNotUnderstood(Behaviour b)
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.
b - the Behaviour that will handle this statepublic void registerHandleFailure(Behaviour b)
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.
b - the Behaviour that will handle this statepublic void registerHandleOutOfSequence(Behaviour b)
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.
b - the Behaviour that will handle this statepublic void reset()
reset in class FSMBehaviourpublic void reset(ACLMessage msg)
msg - is the ACLMessage to be sentpublic void onStart()
onStart in class Behaviourpublic void setDataStore(DataStore ds)
setDataStore in class Behaviourds - the DataStore that this Behaviour
will use as its private data storeprotected java.lang.String createConvId(java.util.Vector msgs)
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.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||