jade.proto
Class SubscriptionResponder

java.lang.Object
  |
  +--jade.core.behaviours.Behaviour
        |
        +--jade.core.behaviours.CompositeBehaviour
              |
              +--jade.core.behaviours.FSMBehaviour
                    |
                    +--jade.proto.SubscriptionResponder

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

Inner Class Summary
static class SubscriptionResponder.Subscription
          Inner calss Subscription This class represents a subscription.
static interface SubscriptionResponder.SubscriptionManager
          Inner interface SubscriptionManager.
 
Inner classes inherited from class jade.core.behaviours.Behaviour
Behaviour.RunnableChangedEvent
 
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 static java.lang.String HANDLE_CANCEL
           
protected  SubscriptionResponder.SubscriptionManager mySubscriptionManager
          The SubscriptionManager used by this SubscriptionResponder to register subscriptions
protected static java.lang.String PREPARE_RESPONSE
           
protected static java.lang.String RECEIVE_SUBSCRIPTION
           
 java.lang.String RESPONSE_KEY
          key to retrieve from the DataStore of the behaviour the ACLMessage object sent as a response to the initiator.
protected static java.lang.String SEND_NOTIFICATIONS
           
protected static java.lang.String SEND_RESPONSE
           
 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.CompositeBehaviour
currentExecuted
 
Fields inherited from class jade.core.behaviours.Behaviour
myAgent, myEvent, NOTIFY_DOWN, NOTIFY_UP, parent, STATE_BLOCKED, STATE_READY, STATE_RUNNING
 
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 Subscription object managed by this SubscriptionResponder
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, 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, onStart, restart, setAgent
 
Methods inherited from class jade.core.behaviours.Behaviour
actionWrapper, block, getBehaviourName, getDataStore, isRunnable, 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.

RECEIVE_SUBSCRIPTION

protected static final java.lang.String RECEIVE_SUBSCRIPTION

PREPARE_RESPONSE

protected static final java.lang.String PREPARE_RESPONSE

HANDLE_CANCEL

protected static final java.lang.String HANDLE_CANCEL

SEND_RESPONSE

protected static final java.lang.String SEND_RESPONSE

SEND_NOTIFICATIONS

protected static final java.lang.String SEND_NOTIFICATIONS

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
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 SubscriptionManager used by this responder. Then it and 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.

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 Subscription object managed by this SubscriptionResponder