jade.domain
Class DFServiceCommunicator

java.lang.Object
  |
  +--jade.domain.FIPAServiceCommunicator
        |
        +--jade.domain.DFServiceCommunicator

public class DFServiceCommunicator
extends jade.domain.FIPAServiceCommunicator

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 blocks 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 by the DF). In some cases, instead, it is more convenient to execute this task in a non-blocking way. The method getNonBlockingBehaviour() returns a non-blocking behaviour of type RequestFIPAServiceBehaviour that can be added to the queue of the agent behaviours, as usual, by using Agent.addBehaviour().

Author:
Fabio Bellifemine (CSELT S.p.A.)

Constructor Summary
DFServiceCommunicator()
           
 
Method Summary
static void deregister(Agent a)
          The default DF of the platform is used.
static void deregister(Agent a, AID dfName)
          A default Agent Description is used which contains only the AID of this agent.
static void deregister(Agent a, AID dfName, DFAgentDescription dfd)
          Deregister a DFAgentDescription from a DF agent.
static void deregister(Agent a, DFAgentDescription dfd)
          The default DF of the platform is used.
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID dfName, java.lang.String actionName)
          the default SearchContraints are used.
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID dfName, java.lang.String actionName, DFAgentDescription dfd)
          the default SearchContraints are used.
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID dfName, java.lang.String actionName, DFAgentDescription dfd, SearchConstraints constraints)
          In some cases it is more convenient to execute this tasks in a non-blocking way.
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName)
          The default DF is used.
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName, DFAgentDescription dfd)
          The defautl DF is used.
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName, DFAgentDescription dfd, SearchConstraints constraints)
          The default DF is used.
static void modify(Agent a, AID dfName, DFAgentDescription dfd)
          Modifies data contained within a DF agent.
static void modify(Agent a, DFAgentDescription dfd)
          The default DF of the platform is used.
static void register(Agent a, AID dfName, DFAgentDescription dfd)
          Register a DFDescriptiont with a DF agent.
static void register(Agent a, DFAgentDescription dfd)
          registers a DFAgentDescription with the default DF
static java.util.List search(Agent a, AID dfName, DFAgentDescription dfd)
          The default SearchConstraints are used.
static java.util.List search(Agent a, AID dfName, DFAgentDescription dfd, SearchConstraints constraints)
          Searches for data contained within a DF agent.
static java.util.List search(Agent a, DFAgentDescription dfd)
          The default DF is used.
static java.util.List search(Agent a, DFAgentDescription dfd, SearchConstraints constraints)
          The default DF is used.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DFServiceCommunicator

public DFServiceCommunicator()
Method Detail

register

public static void register(Agent a,
                            AID dfName,
                            DFAgentDescription dfd)
                     throws FIPAException
Register a DFDescriptiont with a DF agent.
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 DFAgentDescriptor object containing all data necessary to the registration. If the Agent name is empty, than it is set according to the a parameter.
Throws:
FIPAException - A suitable exception can be thrown when a refuse or failure messages are received from the DF to indicate some error condition or when the method locally discovers that the DFDescription is not valid.

register

public static void register(Agent a,
                            DFAgentDescription dfd)
                     throws FIPAException
registers a DFAgentDescription with the default DF
See Also:
register(Agent,AID,DFAgentDescription)

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 - A suitable exception can be thrown when a refuse or failure messages are received from the DF to indicate some error condition.

deregister

public static void deregister(Agent a,
                              DFAgentDescription dfd)
                       throws FIPAException
The default DF of the platform is used.
See Also:
deregister(Agent a, AID dfName, DFAgentDescription dfd)

deregister

public static void deregister(Agent a,
                              AID dfName)
                       throws FIPAException
A default Agent Description is used which contains only the AID of this agent.
See Also:
deregister(Agent a, AID dfName, DFAgentDescription dfd)

deregister

public static void deregister(Agent a)
                       throws FIPAException
The default DF of the platform is used. A default Agent Description is used which contains only the AID of this agent.
See Also:
deregister(Agent a, AID dfName, DFAgentDescription dfd)

modify

public static void modify(Agent a,
                          AID dfName,
                          DFAgentDescription dfd)
                   throws FIPAException
Modifies data contained within a DF agent.
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 DFAgentDescriptor object containing all new data values;
Throws:
FIPAException - A suitable exception can be thrown when a refuse or failure messages are received from the DF to indicate some error condition.

modify

public static void modify(Agent a,
                          DFAgentDescription dfd)
                   throws FIPAException
The default DF of the platform is used.
See Also:
modify(Agent a, AID dfName, DFAgentDescription dfd)

search

public static java.util.List search(Agent a,
                                    AID dfName,
                                    DFAgentDescription dfd,
                                    SearchConstraints constraints)
                             throws FIPAException
Searches for data contained within a DF agent.
Parameters:
a - is the Agent performing the request of 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:
A List containing all found DFAgentDescription objects matching the given descriptor, subject to given search constraints for search depth and result size.
Throws:
FIPAException - A suitable exception can be thrown when a refuse or failure messages are received from the DF to indicate some error condition.

search

public static java.util.List search(Agent a,
                                    DFAgentDescription dfd,
                                    SearchConstraints constraints)
                             throws FIPAException
The default DF is used.
See Also:
search(Agent a, AID dfName, DFAgentDescription dfd, SearchConstraints constraints)

search

public static java.util.List search(Agent a,
                                    DFAgentDescription dfd)
                             throws FIPAException
The default DF is used. The default SearchConstraints are used. According to FIPA they are defaulted to null value for all slots.
See Also:
search(Agent a, AID dfName, DFAgentDescription dfd, SearchConstraints constraints)

search

public static java.util.List search(Agent a,
                                    AID dfName,
                                    DFAgentDescription dfd)
                             throws FIPAException
The default SearchConstraints are used. According to FIPA they are defaulted to null value for all slots.
See Also:
search(Agent a, AID dfName, DFAgentDescription dfd, SearchConstraints constraints)

getNonBlockingBehaviour

public static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                  AID dfName,
                                                                  java.lang.String actionName,
                                                                  DFAgentDescription dfd,
                                                                  SearchConstraints constraints)
                                                           throws FIPAException
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:

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 FIPAAgentManagementOntology: 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:
FIPAAgentManagementOntology

getNonBlockingBehaviour

public static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                  java.lang.String actionName,
                                                                  DFAgentDescription dfd,
                                                                  SearchConstraints constraints)
                                                           throws FIPAException
The default DF is used.
See Also:
getNonBlockingBehaviour(Agent a, AID dfName, String actionName, DFAgentDescription dfd, SearchConstraints constraints)

getNonBlockingBehaviour

public static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                  java.lang.String actionName)
                                                           throws FIPAException
The default DF is used. the default SearchContraints are used. a default AgentDescription is used, where only the agent AID is set.
See Also:
getNonBlockingBehaviour(Agent a, AID dfName, String actionName, DFAgentDescription dfd, SearchConstraints constraints)

getNonBlockingBehaviour

public static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                  AID dfName,
                                                                  java.lang.String actionName)
                                                           throws FIPAException
the default SearchContraints are used. a default AgentDescription is used, where only the agent AID is set.
See Also:
getNonBlockingBehaviour(Agent a, AID dfName, String actionName, DFAgentDescription dfd, SearchConstraints constraints)

getNonBlockingBehaviour

public static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                  java.lang.String actionName,
                                                                  DFAgentDescription dfd)
                                                           throws FIPAException
The defautl DF is used. the default SearchContraints are used.
See Also:
getNonBlockingBehaviour(Agent a, AID dfName, String actionName, DFAgentDescription dfd, SearchConstraints constraints)

getNonBlockingBehaviour

public static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                  AID dfName,
                                                                  java.lang.String actionName,
                                                                  DFAgentDescription dfd)
                                                           throws FIPAException
the default SearchContraints are used.
See Also:
getNonBlockingBehaviour(Agent a, AID dfName, String actionName, DFAgentDescription dfd, SearchConstraints constraints)