jade.domain
Class AMSService

java.lang.Object
  |
  +--jade.domain.FIPAService
        |
        +--jade.domain.AMSService

public class AMSService
extends FIPAService

This class provides a set of static methods to communicate with a AMS Service that complies with FIPA specifications. Notice that JADE calls automatically the register and deregister methods with the default AMS respectively before calling Agent.setup() method and just after Agent.takeDown() method returns; so there is no need for a normal programmer to call them. However, under certain circumstances, a programmer might need to call its methods. To give some examples: when an agent wishes to register with the AMS of a remote agent platform, or when an agent wishes to modify its description by adding a private address to the set of its addresses, ...

It includes methods to register, deregister, modify and search with an AMS. 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 AMS 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 AMS). 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().

Version:
$Date: 2003/11/18 16:23:10 $ $Revision: 2.9 $
Author:
Fabio Bellifemine - CSELT S.p.A.

Constructor Summary
AMSService()
          Default constructor.
 
Method Summary
static void deregister(Agent a)
          A default AMSAgentDescription is used for this agent, where only AID and state are set.
static void deregister(Agent a, AID AMSName)
          A default AMSAgentDescription is used for this agent, where only AID and state are set (state is set to ACTIVE).
static void deregister(Agent a, AID AMSName, AMSAgentDescription amsd)
          Deregister a AMSAgentDescription from a AMS agent.
static void deregister(Agent a, AMSAgentDescription amsd)
          The AID of the AMS is defaulted to the AMS of this platform.
static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID amsName, java.lang.String actionName)
          the default SearchContraints are used.
static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID amsName, java.lang.String actionName, AMSAgentDescription amsd)
          the default AMS is used.
static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID AMSName, java.lang.String actionName, AMSAgentDescription amsd, SearchConstraints constraints)
          In some cases it is more convenient to execute this tasks in a non-blocking way.
static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName)
          the default AMS is used.
static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName, AMSAgentDescription amsd)
          the default AMS is used.
static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName, AMSAgentDescription amsd, SearchConstraints constraints)
          the default AMS is used.
static void modify(Agent a, AID AMSName, AMSAgentDescription amsd)
          Modifies data contained within a AMS agent.
static void modify(Agent a, AMSAgentDescription amsd)
          The AID of the AMS is defaulted to the AMS of this platform.
static void register(Agent a, AID AMSName, AMSAgentDescription amsd)
          Register a AMSAgentDescription with a AMS agent.
static void register(Agent a, AMSAgentDescription amsd)
          registers a AMSAgentDescription with the default AMS
static AMSAgentDescription[] search(Agent a, AID AMSName, AMSAgentDescription amsd)
          searches with the passed AMS by using the default SearchConstraints.
static AMSAgentDescription[] search(Agent a, AID AMSName, AMSAgentDescription amsd, SearchConstraints constraints)
          Searches for data contained within a AMS agent.
static AMSAgentDescription[] search(Agent a, AMSAgentDescription amsd)
          searches with the default AMS and the default SearchConstraints.
static AMSAgentDescription[] search(Agent a, AMSAgentDescription amsd, SearchConstraints constraints)
          searches with the default AMS
 
Methods inherited from class jade.domain.FIPAService
doFipaRequestClient, doFipaRequestClient
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AMSService

public AMSService()
Default constructor.

Method Detail

register

public static void register(Agent a,
                            AID AMSName,
                            AMSAgentDescription amsd)
                     throws FIPAException
Register a AMSAgentDescription with a AMS agent. However, since AMS registration and deregistration are automatic in JADE, this method should not be used by application programmers to register with the default AMS.

Parameters:
a - is the Agent performing the registration
AMSName - The AID of the AMS agent to register with.
amsd - A AMSAgentDescriptor object containing all data necessary to the registration. If the Agent name is empty, than it is set according to the a parameter. If the Agent state is empty, than it is set to ACTIVE.
Throws:
FIPAException - A suitable exception can be thrown when a refuse or failure messages are received from the AMS to indicate some error condition or when the method locally discovers that the amsdescription is not valid.

register

public static void register(Agent a,
                            AMSAgentDescription amsd)
                     throws FIPAException
registers a AMSAgentDescription with the default AMS

FIPAException
See Also:
register(Agent,AID,AMSAgentDescription)

deregister

public static void deregister(Agent a,
                              AID AMSName,
                              AMSAgentDescription amsd)
                       throws FIPAException
Deregister a AMSAgentDescription from a AMS agent. However, since AMS registration and deregistration are automatic in JADE, this method should not be used by application programmers to deregister with the default AMS.

Parameters:
AMSName - The AID of the AMS agent to deregister from.
amsd - A AMSAgentDescription 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 AMS to indicate some error condition or when the method locally discovers that the amsdescription is not valid.

deregister

public static void deregister(Agent a,
                              AMSAgentDescription amsd)
                       throws FIPAException
The AID of the AMS is defaulted to the AMS of this platform.

FIPAException
See Also:
deregister(Agent a, AID AMSName, AMSAgentDescription amsd)

deregister

public static void deregister(Agent a,
                              AID AMSName)
                       throws FIPAException
A default AMSAgentDescription is used for this agent, where only AID and state are set (state is set to ACTIVE).

FIPAException
See Also:
deregister(Agent a, AID AMSName, AMSAgentDescription amsd)

deregister

public static void deregister(Agent a)
                       throws FIPAException
A default AMSAgentDescription is used for this agent, where only AID and state are set. The AID of the AMS is defaulted to the AMS of this platform.

FIPAException
See Also:
deregister(Agent a, AID AMSName, AMSAgentDescription amsd)

modify

public static void modify(Agent a,
                          AID AMSName,
                          AMSAgentDescription amsd)
                   throws FIPAException
Modifies data contained within a AMS agent.

Parameters:
AMSName - The GUID of the AMS agent holding the data to be changed.
amsd - The new AMSAgentDescriptor object that should modify the existing one.
Throws:
FIPAException - A suitable exception can be thrown when a refuse or failure messages are received from the AMS to indicate some error condition or when the method locally discovers that the amsdescription is not valid.

modify

public static void modify(Agent a,
                          AMSAgentDescription amsd)
                   throws FIPAException
The AID of the AMS is defaulted to the AMS of this platform.

FIPAException
See Also:
modify(Agent a, AID AMSName, AMSAgentDescription amsd)

search

public static AMSAgentDescription[] search(Agent a,
                                           AID AMSName,
                                           AMSAgentDescription amsd,
                                           SearchConstraints constraints)
                                    throws FIPAException
Searches for data contained within a AMS agent.

Parameters:
a - is the Agent performing the search
AMSName - The GUID of the AMS agent to start search from.
amsd - A AMSAgentDescriptor 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 AMSAgentDescription containing all found items 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 AMS to indicate some error condition.

search

public static AMSAgentDescription[] search(Agent a,
                                           AMSAgentDescription amsd,
                                           SearchConstraints constraints)
                                    throws FIPAException
searches with the default AMS

FIPAException
See Also:
search(Agent,AID,AMSAgentDescription,SearchConstraints)

search

public static AMSAgentDescription[] search(Agent a,
                                           AMSAgentDescription amsd)
                                    throws FIPAException
searches with the default AMS and the default SearchConstraints. The default constraints specified by FIPA are max_results and max_depth both unspecified and left to the choice of the responder AMS.

FIPAException
See Also:
search(Agent,AID,AMSAgentDescription,SearchConstraints)

search

public static AMSAgentDescription[] search(Agent a,
                                           AID AMSName,
                                           AMSAgentDescription amsd)
                                    throws FIPAException
searches with the passed AMS by using the default SearchConstraints. The default constraints specified by FIPA are max_results and max_depth both unspecified and left to the choice of the responder AMS.

FIPAException
See Also:
search(Agent,AID,AMSAgentDescription,SearchConstraints)

getNonBlockingBehaviour

public static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                              AID AMSName,
                                                                              java.lang.String actionName,
                                                                              AMSAgentDescription amsd,
                                                                              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
AMSName - is the AID that should perform the requested action
actionName - is the name of the action (one of the constants defined in FIPAManagementOntology: REGISTER / DEREGISTER / MODIFY / SEARCH).
amsd - 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 amsdescription is not valid.)
See Also:
FIPAManagementOntology

getNonBlockingBehaviour

public static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                              java.lang.String actionName,
                                                                              AMSAgentDescription amsd,
                                                                              SearchConstraints constraints)
                                                                       throws FIPAException
the default AMS is used.

FIPAException
See Also:
getNonBlockingBehaviour(Agent a, AID AMSName, String actionName, AMSAgentDescription amsd, SearchConstraints constraints)

getNonBlockingBehaviour

public static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                              java.lang.String actionName)
                                                                       throws FIPAException
the default AMS is used. the default SearchContraints are used. a default AgentDescription is used, where only the agent AID is set.

FIPAException
See Also:
getNonBlockingBehaviour(Agent a, AID AMSName, String actionName, AMSAgentDescription amsd, SearchConstraints constraints), search(Agent,AID,AMSAgentDescription)

getNonBlockingBehaviour

public static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                              AID amsName,
                                                                              java.lang.String actionName)
                                                                       throws FIPAException
the default SearchContraints are used. a default AgentDescription is used, where only the agent AID is set.

FIPAException
See Also:
getNonBlockingBehaviour(Agent a, AID AMSName, String actionName, AMSAgentDescription amsd, SearchConstraints constraints), search(Agent,AID,AMSAgentDescription)

getNonBlockingBehaviour

public static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                              java.lang.String actionName,
                                                                              AMSAgentDescription amsd)
                                                                       throws FIPAException
the default AMS is used. the default SearchContraints are used. a default AgentDescription is used, where only the agent AID is set.

FIPAException
See Also:
getNonBlockingBehaviour(Agent a, AID AMSName, String actionName, AMSAgentDescription amsd, SearchConstraints constraints), search(Agent,AID,AMSAgentDescription)

getNonBlockingBehaviour

public static jade.domain.RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                              AID amsName,
                                                                              java.lang.String actionName,
                                                                              AMSAgentDescription amsd)
                                                                       throws FIPAException
the default AMS is used. the default SearchContraints are used.

FIPAException
See Also:
getNonBlockingBehaviour(Agent a, AID AMSName, String actionName, AMSAgentDescription amsd, SearchConstraints constraints), search(Agent,AID,AMSAgentDescription)


JADE