jade.domain
Class DFService

java.lang.Object
  |
  +--jade.domain.FIPAService
        |
        +--jade.domain.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: 2003/03/13 09:35:58 $ $Revision: 2.16 $
Author:
Fabio Bellifemine (CSELT S.p.A.), Elisabetta Cortese (TiLab S.p.A.), Giovanni Caire (TiLab S.p.A.)

Constructor Summary
DFService()
           
 
Method Summary
static ACLMessage createCancelMessage(Agent a, AID dfName, ACLMessage subscribe)
          Utility method that creates a suitable message to be used to CANCEL a subscription to a DF agent.
static ACLMessage createRequestMessage(Agent a, AID dfName, java.lang.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.
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.
static DFAgentDescription decodeDone(java.lang.String s)
           
static DFAgentDescription[] decodeNotification(java.lang.String s)
           
static DFAgentDescription[] decodeResult(java.lang.String s)
           
static void deregister(Agent a)
          Deregisters a DFAgentDescription from the default DF.
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)
          Deregisters a DFAgentDescription from the default DF
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID dfName, java.lang.String actionName)
          Deprecated. Use AchieveREInitiator instead
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID dfName, java.lang.String actionName, DFAgentDescription dfd)
          Deprecated. Use AchieveREInitiator instead
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID dfName, java.lang.String actionName, DFAgentDescription dfd, SearchConstraints constraints)
          Deprecated. Use AchieveREInitiator instead
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName)
          Deprecated. Use AchieveREInitiator instead
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName, DFAgentDescription dfd)
          Deprecated. Use AchieveREInitiator instead
static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName, DFAgentDescription dfd, SearchConstraints constraints)
          Deprecated. Use AchieveREInitiator instead
static ACLMessage getSubscriptionMessage(Agent a, AID dfName, DFAgentDescription template, SearchConstraints constraints)
          Deprecated. Use createSubscriptionMessage() instead
static void keepRegistered(Agent a, AID df, DFAgentDescription dfd, java.util.Date deadline)
          Add a suitable behaviour that ensures that a DF-Description currently registered with a DF is kept registered until a given deadline.
static DFAgentDescription modify(Agent a, AID dfName, DFAgentDescription dfd)
          Modifies a previously registered DF-Description within a DF agent.
static DFAgentDescription modify(Agent a, DFAgentDescription dfd)
          Modify a DFAgentDescription from the default DF.
static DFAgentDescription register(Agent a, AID dfName, DFAgentDescription dfd)
          Register a new DF-Description with a DF agent.
static DFAgentDescription register(Agent a, DFAgentDescription dfd)
          Registers a DFAgentDescription with the default DF
static DFAgentDescription[] search(Agent a, AID dfName, DFAgentDescription dfd)
          The default SearchConstraints are used.
static DFAgentDescription[] search(Agent a, AID dfName, DFAgentDescription dfd, SearchConstraints constraints)
          Searches for data contained within a DF agent.
static DFAgentDescription[] search(Agent a, DFAgentDescription dfd)
          The default DF is used.
static DFAgentDescription[] search(Agent a, DFAgentDescription dfd, SearchConstraints constraints)
          The default DF is used.
static DFAgentDescription[] searchUntilFound(Agent a, AID dfName, DFAgentDescription dfd, SearchConstraints constraints, long timeout)
          Searches the DF and remains blocked until a result is found or the specified timeout has expired.
 
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

DFService

public DFService()
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)

register

public static DFAgentDescription register(Agent a,
                                          DFAgentDescription dfd)
                                   throws FIPAException
Registers a DFAgentDescription with the default DF
Throws:
FIPAException -  
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 - 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.

deregister

public static void deregister(Agent a,
                              DFAgentDescription dfd)
                       throws FIPAException
Deregisters a DFAgentDescription from the default DF
Throws:
FIPAException -  
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.
Throws:
FIPAException -  
See Also:
deregister(Agent a, AID dfName, DFAgentDescription dfd)

deregister

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

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)

modify

public static DFAgentDescription modify(Agent a,
                                        DFAgentDescription dfd)
                                 throws FIPAException
Modify a DFAgentDescription from the default DF.
Throws:
FIPAException -  
See Also:
modify(Agent a, AID dfName, DFAgentDescription dfd)

keepRegistered

public static void keepRegistered(Agent a,
                                  AID df,
                                  DFAgentDescription dfd,
                                  java.util.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)

search

public static DFAgentDescription[] search(Agent a,
                                          DFAgentDescription dfd,
                                          SearchConstraints constraints)
                                   throws FIPAException
The default DF is used.
Throws:
FIPAException -  
See Also:
search(Agent a, AID dfName, DFAgentDescription dfd, SearchConstraints constraints)

search

public static DFAgentDescription[] 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.
Throws:
FIPAException -  
See Also:
search(Agent a, AID dfName, DFAgentDescription dfd, SearchConstraints constraints)

search

public static DFAgentDescription[] 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.
Throws:
FIPAException -  
See Also:
search(Agent a, AID dfName, DFAgentDescription dfd, SearchConstraints constraints)

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,
                                              java.lang.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)

getSubscriptionMessage

public static ACLMessage getSubscriptionMessage(Agent a,
                                                AID dfName,
                                                DFAgentDescription template,
                                                SearchConstraints constraints)
                                         throws FIPAException
Deprecated. Use createSubscriptionMessage() instead


createCancelMessage

public static ACLMessage createCancelMessage(Agent a,
                                             AID dfName,
                                             ACLMessage subscribe)
Utility method that creates a suitable message to be used to CANCEL a subscription to a DF agent.
Parameters:
a - The agent that wants to cancel its subscription to the DF
dfName - The AID of the DF agent.
subscribe - The subscription message previously sent to the DF
Returns:
the cancel message.
See Also:
SubscriptionInitiator, createSubscriptionMessage(Agent, AID, DFAgentDescription, SearchConstraints), decodeNotification(String)

decodeDone

public static DFAgentDescription decodeDone(java.lang.String s)
                                     throws FIPAException
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(java.lang.String s)
                                         throws FIPAException
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(java.lang.String s)
                                               throws FIPAException
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,
                                                                  java.lang.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:

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

getNonBlockingBehaviour

public static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a,
                                                                  java.lang.String actionName,
                                                                  DFAgentDescription dfd,
                                                                  SearchConstraints constraints)
                                                           throws FIPAException
Deprecated. Use AchieveREInitiator instead

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
Deprecated. Use AchieveREInitiator instead

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
Deprecated. Use AchieveREInitiator instead

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
Deprecated. Use AchieveREInitiator instead

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
Deprecated. Use AchieveREInitiator instead

the default SearchContraints are used.
See Also:
getNonBlockingBehaviour(Agent a, AID dfName, String actionName, DFAgentDescription dfd, SearchConstraints constraints)