jade.proto
Class SubscriptionResponder

java.lang.Object
  |
  +--jade.core.behaviours.Behaviour
        |
        +--jade.core.behaviours.CompositeBehaviour
              |
              +--jade.core.behaviours.SerialBehaviour
                    |
                    +--jade.core.behaviours.FSMBehaviour
                          |
                          +--jade.proto.SubscriptionResponder
All Implemented Interfaces:
FIPANames.InteractionProtocol, java.io.Serializable, Serializable

public class SubscriptionResponder
extends FSMBehaviour
implements FIPANames.InteractionProtocol

This is a single homogeneous and effective implementation of the responder 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.

Author:
Elisabetta Cortese - TILAB, Giovanni Caire - TILAB
See Also:
SubscriptionInitiator, Serialized Form

Nested Class Summary
static class SubscriptionResponder.Subscription
          Inner calss Subscription This class represents a subscription.
static interface SubscriptionResponder.SubscriptionManager
          Inner interface SubscriptionManager.
 
Field Summary
 java.lang.String CANCEL_KEY
          key to retrieve from the DataStore of the behaviour the ACLMessage object sent by the initiator to cancel a subscription.
protected  SubscriptionResponder.SubscriptionManager mySubscriptionManager
          The SubscriptionManager used by this SubscriptionResponder to register subscriptions
 java.lang.String RESPONSE_KEY
          key to retrieve from the DataStore of the behaviour the ACLMessage object sent as a response to the initiator.
 java.lang.String SUBSCRIPTION_KEY
          key to retrieve from the DataStore of the behaviour the ACLMessage object sent by the initiator as a subscription.
 
Fields inherited from class jade.core.behaviours.FSMBehaviour
currentName, lastStates, previousName
 
Fields inherited from class jade.core.behaviours.Behaviour
myAgent
 
Fields inherited from interface jade.domain.FIPANames.InteractionProtocol
FIPA_BROKERING, FIPA_CONTRACT_NET, FIPA_DUTCH_AUCTION, FIPA_ENGLISH_AUCTION, FIPA_ITERATED_CONTRACT_NET, FIPA_PROPOSE, FIPA_QUERY, FIPA_RECRUITING, FIPA_REQUEST, FIPA_REQUEST_WHEN, FIPA_SUBSCRIBE
 
Constructor Summary
SubscriptionResponder(Agent a, MessageTemplate mt, SubscriptionResponder.SubscriptionManager sm)
          Constructor of the behaviour that creates a new empty DataStore
SubscriptionResponder(Agent a, MessageTemplate mt, SubscriptionResponder.SubscriptionManager sm, DataStore store)
          Constructor.
 
Method Summary
static MessageTemplate createMessageTemplate(int perf)
          This static method can be used to set the proper message Template (based on the performative of the subscription message) into the constructor of this behaviour.
 SubscriptionResponder.Subscription createSubscription(ACLMessage subsMsg)
          Utility method to correctly create a new Subscription object managed by this SubscriptionResponder
 SubscriptionResponder.Subscription getSubscription(ACLMessage msg)
          Utility method to correctly retrieve the Subscription object that is related to the conversation message msg belongs to.
protected  ACLMessage handleCancel(ACLMessage cancel)
          This method is called when a CANCEL message is received for a previous subscription.
protected  ACLMessage prepareResponse(ACLMessage subscription)
          This method is called when a subscription message is received that matches the message template specified in the constructor.
 void registerHandleCancel(Behaviour b)
          This method allows to register a user defined Behaviour in the HANDLE_CANCEL state.
 void registerPrepareResponse(Behaviour b)
          This method allows to register a user defined Behaviour in the PREPARE_RESPONSE state.
 void reset()
          Reset this behaviour
 void reset(MessageTemplate mt)
          This method resets the protocol and allows to change the MessageTemplate that defines what messages this SubscriptionResponder will react to.
 
Methods inherited from class jade.core.behaviours.FSMBehaviour
checkTermination, deregisterState, forceTransitionTo, getChildren, getCurrent, getLastExitValue, getName, getPrevious, getState, handleInconsistentFSM, handleStateEntered, onEnd, registerDefaultTransition, registerDefaultTransition, registerFirstState, registerLastState, registerState, registerTransition, registerTransition, resetStates, scheduleFirst, scheduleNext
 
Methods inherited from class jade.core.behaviours.CompositeBehaviour
action, block, done, resetChildren, restart, setAgent
 
Methods inherited from class jade.core.behaviours.Behaviour
block, getBehaviourName, getDataStore, getParent, isRunnable, onStart, root, setBehaviourName, setDataStore
 
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 ACLMessage object sent by the initiator as a subscription.


CANCEL_KEY

public final java.lang.String CANCEL_KEY
key to retrieve from the DataStore of the behaviour the ACLMessage object sent by the initiator to cancel a subscription.


RESPONSE_KEY

public final java.lang.String RESPONSE_KEY
key to retrieve from the DataStore of the behaviour the ACLMessage object sent as a response to the initiator.


mySubscriptionManager

protected SubscriptionResponder.SubscriptionManager mySubscriptionManager
The SubscriptionManager used by this SubscriptionResponder to register subscriptions

Constructor Detail

SubscriptionResponder

public SubscriptionResponder(Agent a,
                             MessageTemplate mt,
                             SubscriptionResponder.SubscriptionManager sm)
Constructor of the behaviour that creates a new empty DataStore

See Also:
SubscriptionResponder(Agent,MessageTemplate,SubscriptionResponder.SubscriptionManager,DataStore)

SubscriptionResponder

public SubscriptionResponder(Agent a,
                             MessageTemplate mt,
                             SubscriptionResponder.SubscriptionManager sm,
                             DataStore store)
Constructor.

Parameters:
a - is the reference to the Agent performing this behaviour.
mt - is the MessageTemplate that must be used to match subscription messages sent by the initiators. Take care that if mt is null every message is consumed by this protocol.
sm - The SubscriptionManager object that manages subscriptions.
store - the DataStore for this protocol
Method Detail

createMessageTemplate

public static MessageTemplate createMessageTemplate(int perf)
This static method can be used to set the proper message Template (based on the performative of the subscription message) into the constructor of this behaviour.

Parameters:
perf - The performative of the subscription message

reset

public void reset()
Reset this behaviour

Overrides:
reset in class FSMBehaviour

reset

public void reset(MessageTemplate mt)
This method resets the protocol and allows to change the MessageTemplate that defines what messages this SubscriptionResponder will react to.


prepareResponse

protected ACLMessage prepareResponse(ACLMessage subscription)
                              throws NotUnderstoodException,
                                     RefuseException
This method is called when a subscription message is received that matches the message template specified in the constructor. The default implementation creates an new Subscription object and registers it to the SubscriptionManager used by this responder. Then it returns null which has the effect of sending no reponse. Programmers in general do not need to override this method, but just implement the register() method of the SubscriptionManager used by this SubscriptionResponder. However they could override it in case they need to react to the reception of a subscription message in a different way, e.g. by sending back an AGREE.

Parameters:
subscription - the received message
Returns:
the ACLMessage to be sent as a response (i.e. one of agree, refuse, not-understood. Remind to use the method createReply of the class ACLMessage in order to create a good response message
NotUnderstoodException
RefuseException
See Also:
ACLMessage.createReply()

handleCancel

protected ACLMessage handleCancel(ACLMessage cancel)
                           throws FailureException
This method is called when a CANCEL message is received for a previous subscription. The default implementation retrieves the Subscription object the received cancel message refers to and deregisters it from the SubscriptionManager used by this responder. Then it returns null which has the effect of sending no reponse. Programmers in general do not need to override this method, but just implement the deregister() method of the SubscriptionManager used by this SubscriptionResponder. However they could override it in case they need to react to the reception of a cancel message in a different way, e.g. by sending back an INFORM.

Parameters:
cancel - the received CANCEL message
Returns:
the ACLMessage to be sent as a response to the cancel operation (i.e. one of inform and failure.
FailureException

registerPrepareResponse

public void registerPrepareResponse(Behaviour b)
This method allows to register a user defined Behaviour in the PREPARE_RESPONSE state. This behaviour overrides 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 response (if any) to be sent back into the datastore at the RESPONSE_KEY key. The incoming subscription message can be retrieved from the datastore at the SUBSCRIPTION_KEY key

Parameters:
b - the Behaviour that will handle this state

registerHandleCancel

public void registerHandleCancel(Behaviour b)
This method allows to register a user defined Behaviour in the HANDLE_CANCEL state. This behaviour overrides 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 response (if any) to be sent back into the datastore at the RESPONSE_KEY key. The incoming CANCEL message can be retrieved from the datastore at the CANCEL_KEY key

Parameters:
b - the Behaviour that will handle this state

createSubscription

public SubscriptionResponder.Subscription createSubscription(ACLMessage subsMsg)
Utility method to correctly create a new Subscription object managed by this SubscriptionResponder


getSubscription

public SubscriptionResponder.Subscription getSubscription(ACLMessage msg)
Utility method to correctly retrieve the Subscription object that is related to the conversation message msg belongs to.



JADE