Package jade.proto

Class SimpleAchieveREInitiator

  • All Implemented Interfaces:
    Serializable, Serializable
    Direct Known Subclasses:
    RequestFIPAServiceBehaviour
    public class SimpleAchieveREInitiator
extends SimpleBehaviour
    This is simple implementation of the AchieveREInitiator. This implementation in particular is 1:1 and does not allow the possibility to add Handler. This is a single homogeneous and effective implementation of all the FIPA-Request-like interaction protocols defined by FIPA, that is all those protocols where the initiator sends a single message (i.e. it performs a single communicative act) within the scope of an interaction protocol in order to verify if the RE (Rational Effect) of the communicative act has been achieved or not.

    FIPA has already specified a number of these interaction protocols, like FIPA-Request, FIPA-query, FIPA-Request-When, FIPA-recruiting, FIPA-brokering, FIPA-subscribe, that allows the initiator to verify if the expected rational effect of a single communicative act has been achieved.

    The structure of these protocols is equal. The initiator sends a message (in general it performs a communicative act).

    The responder can then reply by sending a not-understood, or a refuse to achieve the rational effect of the communicative act, or also an agree message to communicate the agreement to perform (possibly in the future) the communicative act. This first category of reply messages has been here identified as a response.

    The responder performs the action and, finally, must respond with an inform of the result of the action (eventually just that the action has been done) or with a failure if anything went wrong. This second category of reply messages has been here identified as a result notification.

    Notice that we have extended the protocol to make optional the transmission of the agree message. Infact, in most cases performing the action takes so short time that sending the agree message is just an useless and uneffective overhead; in such cases, the agree to perform the communicative act is subsumed by the reception of the following message in the protocol.

    Read carefully the section of the JADE programmer's guide that describes the usage of this class.

    Known bugs: The handler handleAllResponses is not called if the agree message is skipped and the inform message is received instead.

    Version:
    $Date$ $Revision$
    Author:
    Tiziana Trucco - TILab
    See Also:
    SimpleAchieveREResponder, AchieveREInitiator, AchieveREResponder, Serialized Form

    • Field Detail

      • REQUEST_KEY

        public final String REQUEST_KEY
        key to retrive from the datastore the ACLMessage passed in the constructor

      • REQUEST_SENT_KEY

        public final String REQUEST_SENT_KEY
        key to retrive from the datastore the ACLMessage that has been sent.

      • SECOND_REPLY_KEY

        public final String SECOND_REPLY_KEY
        key to retrive the second reply received.

      • ALL_RESPONSES_KEY

        public final String ALL_RESPONSES_KEY
        key to retrive all the responses received.

      • ALL_RESULT_NOTIFICATIONS_KEY

        public final String ALL_RESULT_NOTIFICATIONS_KEY
        key to retrive the result notification received.

    • Constructor Detail

      • SimpleAchieveREInitiator

        public SimpleAchieveREInitiator​(Agent a,
                                ACLMessage msg,
                                DataStore store)
        Constructs a SimpleAchieveREInitiator behaviour
        Parameters:
        a - The agent performing the protocol
        msg - The message that must be used to initiate the protocol. Notice that in this simple implementation, the prepareMessage method returns a single message.
        s - The DataStore that will be used by this SimpleAchieveREInitiator

    • Method Detail

      • action

        public final void action()
        Description copied from class: Behaviour
        Runs the behaviour. This abstract method must be implemented by Behavioursubclasses to perform ordinary behaviour duty. An agent schedules its behaviours calling their action() method; since all the behaviours belonging to the same agent are scheduled cooperatively, this method must not enter in an endless loop and should return as soon as possible to preserve agent responsiveness. To split a long and slow task into smaller section, recursive behaviour aggregation may be used.
        Specified by:
        action in class Behaviour
        See Also:
        CompositeBehaviour

      • onStart

        public void onStart()
        Description copied from class: Behaviour
        This method is just an empty placeholders for subclasses. It is executed just once before starting behaviour execution. Therefore, it acts as a prolog to the task represented by this Behaviour.
        Overrides:
        onStart in class Behaviour

      • done

        public boolean done()
        Description copied from class: Behaviour
        Check if this behaviour is done. The agent scheduler calls this method to see whether a Behaviour still need to be run or it has completed its task. Concrete behaviours must implement this method to return their completion state. Finished behaviours are removed from the scheduling queue, while others are kept within to be run again when their turn comes again.
        Specified by:
        done in class Behaviour
        Returns:
        true if the behaviour has completely executed.

      • prepareRequest

        protected ACLMessage prepareRequest​(ACLMessage msg)
        This method must return the ACLMessage to be sent. This default implementation just return the ACLMessage object passed in the constructor. Programmer might override the method in order to return a different ACLMessage. Note that for this simple version of protocol, the message will be just send to the first receiver set.
        Parameters:
        msg - the ACLMessage object passed in the constructor.
        Returns:
        a ACLMessage.

      • handleAgree

        protected void handleAgree​(ACLMessage msg)
        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 msg)
        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

      • handleNotUnderstood

        protected void handleNotUnderstood​(ACLMessage msg)
        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

      • handleInform

        protected void handleInform​(ACLMessage msg)
        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

      • handleFailure

        protected void handleFailure​(ACLMessage msg)
        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

      • handleAllResponses

        protected void handleAllResponses​(Vector msgs)
        This method is called when all the responses have been collected or when the timeout is expired. By response message we intend here all the agree, not-understood, refuse received messages, which are not 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

      • handleAllResultNotifications

        protected void handleAllResultNotifications​(Vector msgs)
        This method is called when all the result notification messages have been collected. By result notification message we intend here all the inform, failure received messages, which are not 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:
        resultNodifications - the Vector of ACLMessage object received

      • reset

        public void reset()
        This method resets this behaviour so that it restarts from the initial state of the protocol with a null message.
        Overrides:
        reset in class SimpleBehaviour

      • reset

        public void reset​(ACLMessage msg)
        This method resets this behaviour so that it restarts the protocol with another request message.
        Parameters:
        msg - updates message to be sent.