AMSService (JADE v4.5.0 API)

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().
The MIDP version of this class only includes the getFailedReceiver() method.

Version:

$Date: 2012-09-10 10:53:21 +0200 (lun, 10 set 2012) $ $Revision: 6588 $

Author:

Fabio Bellifemine - CSELT S.p.A.

Constructor Summary

Constructors
Constructor and Description

AMSService()
Default constructor.

Constructors
Constructor and Description
`AMSService()` Default constructor.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`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 AID`	`getFailedReceiver(Agent a, ACLMessage failure)` Extracts the receiver a message could not be delivered to from a FAILURE message received by the AMS.
`static java.lang.String`	`getFailureReason(Agent a, ACLMessage failure)`
`static RequestFIPAServiceBehaviour`	`getNonBlockingBehaviour(Agent a, AID amsName, java.lang.String actionName)` the default SearchContraints are used.
`static RequestFIPAServiceBehaviour`	`getNonBlockingBehaviour(Agent a, AID amsName, java.lang.String actionName, AMSAgentDescription amsd)` the default AMS is used.
`static 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 RequestFIPAServiceBehaviour`	`getNonBlockingBehaviour(Agent a, java.lang.String actionName)` the default AMS is used.
`static RequestFIPAServiceBehaviour`	`getNonBlockingBehaviour(Agent a, java.lang.String actionName, AMSAgentDescription amsd)` the default AMS is used.
`static 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, parseAID

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
    
    Throws:
    
    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.
    
    Throws:
    
    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).
    
    Throws:
    
    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.
    
    Throws:
    
    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.
    
    Throws:
    
    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
    
    Throws:
    
    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.
    
    Throws:
    
    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.
    
    Throws:
    
    FIPAException
    
    See Also:
    
    search(Agent,AID,AMSAgentDescription,SearchConstraints)
  - getNonBlockingBehaviour
```
public static 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:
    - 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
    
    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 RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                  java.lang.String actionName,
                                                                  AMSAgentDescription amsd,
                                                                  SearchConstraints constraints)
                                                           throws FIPAException
```
    the default AMS is used.
    
    Throws:
    
    FIPAException
    
    See Also:
    
    getNonBlockingBehaviour(Agent a, AID AMSName, String actionName, AMSAgentDescription amsd, SearchConstraints constraints)
  - getNonBlockingBehaviour
```
public static 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.
    
    Throws:
    
    FIPAException
    
    See Also:
    
    getNonBlockingBehaviour(Agent a, AID AMSName, String actionName, AMSAgentDescription amsd, SearchConstraints constraints), search(Agent,AID,AMSAgentDescription)
  - getNonBlockingBehaviour
```
public static 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.
    
    Throws:
    
    FIPAException
    
    See Also:
    
    getNonBlockingBehaviour(Agent a, AID AMSName, String actionName, AMSAgentDescription amsd, SearchConstraints constraints), search(Agent,AID,AMSAgentDescription)
  - getNonBlockingBehaviour
```
public static 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.
    
    Throws:
    
    FIPAException
    
    See Also:
    
    getNonBlockingBehaviour(Agent a, AID AMSName, String actionName, AMSAgentDescription amsd, SearchConstraints constraints), search(Agent,AID,AMSAgentDescription)
  - getNonBlockingBehaviour
```
public static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                  AID amsName,
                                                                  java.lang.String actionName,
                                                                  AMSAgentDescription amsd)
                                                           throws FIPAException
```
    the default AMS is used. the default SearchContraints are used.
    
    Throws:
    
    FIPAException
    
    See Also:
    
    getNonBlockingBehaviour(Agent a, AID AMSName, String actionName, AMSAgentDescription amsd, SearchConstraints constraints), search(Agent,AID,AMSAgentDescription)
  - getFailedReceiver
```
public static AID getFailedReceiver(Agent a,
                                    ACLMessage failure)
                             throws FIPAException
```
    Extracts the receiver a message could not be delivered to from a FAILURE message received by the AMS.
    
    Parameters:
    
    a - The agent that is calling this method.
    
    failure - The FAILURE message received by thye AMS.
    
    Returns:
    
    the receiver a message could not be delivered to.
    
    Throws:
    
    FIPAException
  - getFailureReason
```
public static java.lang.String getFailureReason(Agent a,
                                                ACLMessage failure)
                                         throws FIPAException
```
    Throws:
    
    FIPAException

Class AMSService

Constructor Summary

Method Summary

Methods inherited from class jade.domain.FIPAService

Methods inherited from class java.lang.Object

Constructor Detail

AMSService

Method Detail

register

register

deregister

deregister

deregister

deregister

modify

modify

search

search

search

search

getNonBlockingBehaviour

getNonBlockingBehaviour

getNonBlockingBehaviour

getNonBlockingBehaviour

getNonBlockingBehaviour

getNonBlockingBehaviour

getFailedReceiver

getFailureReason