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

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

Nested Classes

Modifier and Type	Class and Description
static class	SubscriptionResponder.Subscription Inner calss Subscription This class represents a subscription.
static interface	SubscriptionResponder.SubscriptionManager Inner interface SubscriptionManager.

Field Summary

Fields

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

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

Constructor Summary

Constructors

Constructor and Description
SubscriptionResponder(Agent a, MessageTemplate mt) Construct a SubscriptionResponder behaviour that handles subscription messages matching a given template.
SubscriptionResponder(Agent a, MessageTemplate mt, SubscriptionResponder.SubscriptionManager sm) Construct a SubscriptionResponder behaviour that handles subscription messages matching a given template and notifies a given SubscriptionManager about subscription/un-subscription events.
SubscriptionResponder(Agent a, MessageTemplate mt, SubscriptionResponder.SubscriptionManager sm, DataStore store) Construct a SubscriptionResponder behaviour that handles subscription messages matching a given template, notifies a given SubscriptionManager about subscription/un-subscription events and uses a given DataStore.

Method Summary

Modifier and Type	Method and Description
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.
SubscriptionResponder.Subscription	getSubscription(java.lang.String convId) Utility method to correctly retrieve the Subscription object that is related a given conversation.
java.util.Vector	getSubscriptions() Utility method that retrieves all Subscription-s managed by this SubscriptionResponder
java.util.Vector	getSubscriptions(AID subscriber) Utility method that retrieves all Subscription-s done by a given agent
protected ACLMessage	handleCancel(ACLMessage cancel) This method is called when a CANCEL message is received for a previous subscription.
protected ACLMessage	handleSubscription(ACLMessage subscription) This method is called when a subscription message is received that matches the message template specified in the constructor.
protected ACLMessage	prepareResponse(ACLMessage subscription) Deprecated. Use handleSubscription() instead
void	registerHandleCancel(Behaviour b) This method allows to register a user defined Behaviour in the HANDLE_CANCEL state.
void	registerHandleSubscription(Behaviour b) This method allows to register a user defined Behaviour in the HANDLE_SUBSCRIPTION state.
void	registerPrepareResponse(Behaviour b) Deprecated. Use registerHandleSubscription() instead.
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, 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, onStart, restart, 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)

Construct a SubscriptionResponder behaviour that handles subscription messages matching a given template.

See Also:

SubscriptionResponder(Agent,MessageTemplate,SubscriptionResponder.SubscriptionManager,DataStore)

SubscriptionResponder

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

Construct a SubscriptionResponder behaviour that handles subscription messages matching a given template and notifies a given SubscriptionManager about subscription/un-subscription events.

See Also:

SubscriptionResponder(Agent,MessageTemplate,SubscriptionResponder.SubscriptionManager,DataStore)

SubscriptionResponder

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

Construct a SubscriptionResponder behaviour that handles subscription messages matching a given template, notifies a given SubscriptionManager about subscription/un-subscription events and uses a given DataStore.

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 is notified about subscription/un-subscription events

store - the DataStore that will be used by 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.

handleSubscription

protected ACLMessage handleSubscription(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, stores it internally and notify the SubscriptionManager used by this responder if any. Then it returns null which has the effect of sending no response. Programmers in general do not need to override this method. In case they need to manage Subscription objects in an application specific way they should rather use a SubscriptionManager with the register() method properly implemented. 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 message.

Parameters:

subscription - the received message

Returns:

the ACLMessage to be sent as a response: typically one of agree, refuse, not-understood or null if no response must be sent back.

Throws:

NotUnderstoodException

RefuseException

prepareResponse

protected ACLMessage prepareResponse(ACLMessage subscription)
                              throws NotUnderstoodException,
                                     RefuseException

Deprecated. Use handleSubscription() instead

Throws:

NotUnderstoodException

RefuseException

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, notifies the SubscriptionManager used by this responder if any and remove the Subscription from its internal structures. Then it returns null which has the effect of sending no response. Programmers in general do not need to override this method. In case they need to manage Subscription objects in an application specific way they should rather use a SubscriptionManager with the deregister() method properly implemented. 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: typically one of inform and failure or null if no response must be sent back.

Throws:

FailureException

registerHandleSubscription

public void registerHandleSubscription(Behaviour b)

This method allows to register a user defined Behaviour in the HANDLE_SUBSCRIPTION 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

registerPrepareResponse

public void registerPrepareResponse(Behaviour b)

Deprecated. Use registerHandleSubscription() instead.

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.

Parameters:

msg - The message whose conversation-id indicates the conversation

Returns:

the Subscription object related to the conversation the given message belongs to

getSubscription

public SubscriptionResponder.Subscription getSubscription(java.lang.String convId)

Utility method to correctly retrieve the Subscription object that is related a given conversation.

Parameters:

convId - The id of the conversation

Returns:

the Subscription object related to the given conversation

getSubscriptions

public java.util.Vector getSubscriptions(AID subscriber)

Utility method that retrieves all Subscription-s done by a given agent

Parameters:

subscriber - The AID of the agent whose subscriptions must be retrieved

Returns:

A Vector including all Subscription-s made by the given agent

getSubscriptions

public java.util.Vector getSubscriptions()

Utility method that retrieves all Subscription-s managed by this SubscriptionResponder

Returns:

A Vector including all Subscription-s managed by this SubscriptionResponder