jade.proto

Class SubscriptionInitiator

java.lang.Object

jade.core.behaviours.Behaviour

jade.core.behaviours.CompositeBehaviour

jade.core.behaviours.SerialBehaviour

jade.core.behaviours.FSMBehaviour

jade.proto.SubscriptionInitiator

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

DFSubscriber

public class SubscriptionInitiator
extends FSMBehaviour

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.

Author:

Giovanni Caire - TILab

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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.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

SUBSCRIPTION_KEY

public final 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.

ALL_SUBSCRIPTIONS_KEY

public final 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.

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

Constructor Detail

SubscriptionInitiator

public SubscriptionInitiator(Agent a,
                             ACLMessage msg)

Construct a SubscriptionInitiator with an empty DataStore

See Also:

SubscriptionInitiator(Agent, ACLMessage, DataStore)

SubscriptionInitiator

public SubscriptionInitiator(Agent a,
                             ACLMessage msg,
                             DataStore store)

Construct a SubscriptionInitiator with a given DataStore

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

prepareSubscriptions

protected java.util.Vector prepareSubscriptions(ACLMessage subscription)

This method must return the vector of subscription ACLMessage objects to be sent. It is called in the first state of this protocol. This default implementation just returns the ACLMessage object passed in the constructor. Programmers might prefer to override this method in order to return a vector of objects for 1:N conversations or also to prepare the messages during the execution of the behaviour.

Parameters:

subscription - the ACLMessage object passed in the constructor

Returns:

a Vector of ACLMessage objects. The values of the slot reply-with is ignored and a different value is assigned automatically by this class for each receiver.

handleAgree

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. This default implementation does nothing; programmers might wish to override the method in case they need to react to this event.

Parameters:

agree - the received agree message

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)

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

Parameters:

responses - the Vector of ACLMessage objects that have been received

registerPrepareSubscriptions

public void registerPrepareSubscriptions(Behaviour b)

This method allows to register a user defined 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.

Parameters:

b - the Behaviour that will handle this state

registerHandleAgree

public void registerHandleAgree(Behaviour b)

This method allows to register a user defined 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.

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

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

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

Parameters:

b - the Behaviour that will handle this state

cancel

public void cancel(AID receiver,
                   boolean ignoreResponse)

Cancel the subscription to agent 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.

Parameters:

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.

See Also:

fillCancelContent(ACLMessage, ACLMessage), cancellationCompleted(AID)

fillCancelContent

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. 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();
         }
         

See Also:

cancel(AID, boolean)

cancellationCompleted

public 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. This method has some effect only if a cancellation for agent receiver was previously activated by means of the cancel() method.

See Also:

cancel(AID, boolean)

reinit

protected void reinit()

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

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.