Package jade.domain

Class DFService

  • public class DFService
extends FIPAService
    This class provides a set of static methods to communicate with a DF Service that complies with FIPA specifications. It includes methods to register, deregister, modify and search with a DF. Each of this method has version with all the needed parameters, or with a subset of them where, those parameters that can be omitted have been defaulted to the default DF of the platform, the AID of the sending agent, the default Search Constraints.

    Notice that all these methods block every activity of the agent until the action (i.e. register/deregister/modify/search) has been successfully executed or a jade.domain.FIPAException exception has been thrown (e.g. because a FAILURE message has been received from the DF).

    In some cases, instead, it is more convenient to execute these tasks in a non-blocking way. In these cases a jade.proto.AchieveREInitiator or jade.proto.SubscriptionInitiator should be used in conjunction with the createRequestMessage(), createSubscriptionMessage(), decodeDone(), decodeResult() and decodeNotification() methods that facilitate the preparation and decoding of messages to be sent/received to/from the DF. The following piece of code exemplifies that in the case of an agent subscribing to the default DF. 

     DFAgentDescription template = // fill the template
 Behaviour b = new SubscriptionInitiator(
 this, 
 DFService.createSubscriptionMessage(this, getDefaultDF(), template, null)) 
 {
 protected void handleInform(ACLMessage inform) {
 try {
 DFAgentDescription[] dfds = DFService.decodeNotification(inform.getContent());
 // do something
  }
  catch (FIPAException fe) {
  fe.printStackTrace();
  }
  }
  };
  addBehaviour(b);
    Version:
    $Date$ $Revision$
    Author:
    Fabio Bellifemine (CSELT S.p.A.), Elisabetta Cortese (TiLab S.p.A.), Giovanni Caire (TiLab S.p.A.)

    • Constructor Detail

      • DFService

        public DFService()
        Default constructor.

    • Method Detail

      • register

        public static DFAgentDescription register​(Agent a,
                                          AID dfName,
                                          DFAgentDescription dfd)
                                   throws FIPAException
        Register a new DF-Description with a DF agent.

        It should be noted that, depending on the policy adopted by the DF, the granted lease time for the registration can be shorter than the requested one. This can be checked by looking at the DF-Description actually registered by the DF that is made available as the return value of this method. The keepRegistered() method can be used to keep the registration valid until a given time.

        Parameters:
        a - is the Agent performing the registration (it is needed in order to send/receive messages)
        dfName - The AID of the DF agent to register with.
        dfd - A DFAgentDescription object containing all data necessary to the registration. If the Agent name is empty, than it is set according to the a parameter.
        Returns:
        the DFAgentDescription actually registered by the DF
        Throws:
        FIPAException - If a REFUSE, FAILURE or NOT_UNDERSTOOD message is received from the DF (to indicate some error condition) or if the supplied DF-Description is not valid.
        See Also:
        keepRegistered(Agent, AID, DFAgentDescription, Date)

      • deregister

        public static void deregister​(Agent a,
                              AID dfName,
                              DFAgentDescription dfd)
                       throws FIPAException
        Deregister a DFAgentDescription from a DF agent.
        Parameters:
        dfName - The AID of the DF agent to deregister from.
        dfd - A DFAgentDescription object containing all data necessary to the deregistration.
        Throws:
        FIPAException - If a REFUSE, FAILURE or NOT_UNDERSTOOD message is received from the DF (to indicate some error condition) or if the supplied DF-Description is not valid.

      • modify

        public static DFAgentDescription modify​(Agent a,
                                        AID dfName,
                                        DFAgentDescription dfd)
                                 throws FIPAException
        Modifies a previously registered DF-Description within a DF agent.

        It should be noted that, depending on the policy adopted by the DF, the granted lease time for the modified registration can be shorter than the requested one. This can be checked by looking at the DF-Description actually registered by the DF that is made available as the return value of this method. The keepRegistered() method can be used to keep the registration valid until a given time.

        Parameters:
        a - is the Agent performing the request of modification
        dfName - The AID of the DF agent holding the data to be changed.
        dfd - A DFAgentDescription object containing all new data values;
        Returns:
        the DFAgentDescription actually registered (after the modification) by the DF
        Throws:
        FIPAException - If a REFUSE, FAILURE or NOT_UNDERSTOOD message is received from the DF (to indicate some error condition) or if the supplied DF-Description is not valid.
        See Also:
        keepRegistered(Agent, AID, DFAgentDescription, Date)

      • keepRegistered

        public static void keepRegistered​(Agent a,
                                  AID df,
                                  DFAgentDescription dfd,
                                  Date deadline)
        Add a suitable behaviour that ensures that a DF-Description currently registered with a DF is kept registered until a given deadline. This method is particularly useful when dealing with a DF agent that grants limited lease time for agent registrations. The following piece of code exemplifies how to use it. 
                 DFAgentDescription dfd = // fill DF-Description
         try {
         DFAgentDescription actualDfd = DFService.register(this, dfd);
         DFService.keepRegistered(this, actualDfd, dfd.getLeaseTime());
         }
         catch (FIPAException fe) {
         fe.printStackTarce();
         }
        Parameters:
        a - The agent that is registerd with the DF.
        df - The DF agent
        dfd - The DF-Description that is currently registered with the DF
        deadline - The time until which the currenlty registered DF-Description must be kept valid. Use null to indicate an infinite time

      • search

        public static DFAgentDescription[] search​(Agent a,
                                          AID dfName,
                                          DFAgentDescription dfd,
                                          SearchConstraints constraints)
                                   throws FIPAException
        Searches for data contained within a DF agent.
        Parameters:
        a - is the Agent requesting the search
        dfName - The AID of the DF agent to start search from.
        dfd - A DFAgentDescription object containing data to search for; this parameter is used as a template to match data against.
        constraints - of the search
        Returns:
        An array of DFAgentDescription containing all found items matching the given descriptor, subject to given search constraints for search depth and result size.
        Throws:
        FIPAException - If a REFUSE, FAILURE or NOT_UNDERSTOOD message is received from the DF (to indicate some error condition)

      • searchUntilFound

        public static DFAgentDescription[] searchUntilFound​(Agent a,
                                                    AID dfName,
                                                    DFAgentDescription dfd,
                                                    SearchConstraints constraints,
                                                    long timeout)
                                             throws FIPAException
        Searches the DF and remains blocked until a result is found or the specified timeout has expired.
        Parameters:
        a - The agent that is performing the search
        dfName - The AID of the DF agent where to search into.
        template - A DFAgentDescription object that is used as a template to identify the DF descriptions to search for.
        constraints - The constraints to limit the number of results to be sent back.
        timeout - The maximum amount of time that we want to remain blocked waiting for results.
        Returns:
        The DF agent descriptions matching the specified template or null if the timeout expires.
        Throws:
        FIPAException - If a REFUSE, FAILURE or NOT_UNDERSTOOD message is received from the DF (to indicate some error condition) or if the supplied DF-Description template is not valid.

      • createRequestMessage

        public static ACLMessage createRequestMessage​(Agent a,
                                              AID dfName,
                                              String action,
                                              DFAgentDescription dfd,
                                              SearchConstraints constraints)
        Utility method that creates a suitable message to be used to REQUEST a DF agent to perform a given action of the FIPA-Management-ontology.

        This method can be fruitfully used in combination with the jade.proto.AchieveREInitiator protocol and with the decodeDone() and decodeResult() methods to interact with a DF in a non-blocking way.

        Parameters:
        a - The agent that is requesting the DF
        dfName - The AID of the DF agent to send the request to.
        action - The name of the requested action. This must be one of
        • FIPAManagementVocabulary.REGISTER
        • FIPAManagementVocabulary.DEREGISTER
        • FIPAManagementVocabulary.MODIFY
        • FIPAManagementVocabulary.SEARCH
        dfd - A DFAgentDescription object. Depending on the requested action, this is the description to register/deregister/modify or a template to match data against during a search.
        constraints - The constraints to limit the number of results to be notified. This is meaningful only if the requested action is SEARCH.
        Returns:
        the request message.
        See Also:
        AchieveREInitiator, decodeDone(String), decodeResult(String)

      • createSubscriptionMessage

        public static ACLMessage createSubscriptionMessage​(Agent a,
                                                   AID dfName,
                                                   DFAgentDescription template,
                                                   SearchConstraints constraints)
        Utility method that creates a suitable message to be used to SUBSCRIBE to a DF agent in order to receive notifications when a new DF-Description matching the indicated template is registererd with that DF.

        This method can be fruitfully used in combination with the jade.proto.SubscriptionInitiator protocol and with the createCancelMessage() and decodeNotification() methods to interact with a DF in a non-blocking way.

        Parameters:
        a - The agent that is subscribing to the DF
        dfName - The AID of the DF agent to subscribe to.
        template - A DFAgentDescription object that is used as a template to identify DF description that will be notified
        constraints - The constraints to limit the number of results to be notified.
        Returns:
        the subscription message.
        See Also:
        SubscriptionInitiator, createCancelMessage(Agent, AID, ACLMessage), decodeNotification(String)

      • decodeDone

        public static DFAgentDescription decodeDone​(String s)
                                     throws FIPAException
        Process the content of the final inform (Done) message resulting from a register or deregister action requested to a DF agent, extracting the df-agent-description contained within.
        Returns:
        The DFAgentDescription object included in the "done" expression used as the content of the INFORM message send back by the DF in response to a REQUEST to perform a register, deregister or modify action.
        Throws:
        FIPAException - If some error occurs while decoding

      • decodeResult

        public static DFAgentDescription[] decodeResult​(String s)
                                         throws FIPAException
        Process the content of the final inform (result) message resulting from a search action requested to a DF agent, extracting the array of df-agent-description contained within.
        Returns:
        The DFAgentDescription objects (as an array) included in the "result" expression used as the content of the INFORM message send back by the DF in response to a REQUEST to perform a search action.
        Throws:
        FIPAException - If some error occurs while decoding

      • decodeNotification

        public static DFAgentDescription[] decodeNotification​(String s)
                                               throws FIPAException
        Process the content of the inform message resulting from a subscription with a DF agent, extracting the array of df-agent-description objects contained within.
        Returns:
        The DFAgentDescription objects (as an array) included in the "(= (iota...) ...)" expression used as the content of an INFORM message sent back by the DF as a subscription notification.
        Throws:
        FIPAException - If some error occurs while decoding

      • getNonBlockingBehaviour

        public static RequestFIPAServiceBehaviour getNonBlockingBehaviour​(Agent a,
                                                                  AID dfName,
                                                                  String actionName,
                                                                  DFAgentDescription dfd,
                                                                  SearchConstraints constraints)
                                                           throws FIPAException
        Deprecated.
        Use AchieveREInitiator instead
        In some cases it is more convenient to execute this tasks in a non-blocking way. This method returns a non-blocking behaviour that can be added to the queue of the agent behaviours, as usual, by using Agent.addBehaviour().

        Several ways are available to get the result of this behaviour and the programmer can select one according to his preferred programming style:

        • call getLastMsg() and getSearchResults() where both throw a NotYetReadyException if the task has not yet finished;
        • create a SequentialBehaviour composed of two sub-behaviours: the first subbehaviour is the returned RequestFIPAServiceBehaviour, while the second one is application-dependent and is executed only when the first is terminated;
        • use directly the class RequestFIPAServiceBehaviour by extending it and overriding all the handleXXX methods that handle the states of the fipa-request interaction protocol.
        Parameters:
        a - is the agent performing the task
        dfName - is the AID of the DF that should perform the requested action
        actionName - is the name of the action (one of the constants defined in FIPAManagementOntology: REGISTER / DEREGISTER / MODIFY / SEARCH).
        dfd - is the agent description
        constraints - are the search constraints (can be null if this is not a search operation)
        Returns:
        the behaviour to be added to the agent
        Throws:
        FIPAException - A suitable exception can be thrown to indicate some error condition locally discovered (e.g.the agentdescription is not valid.)
        See Also:
        FIPAManagementOntology