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.)
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 java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
DFService
public DFService()
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 modificationdfName
- 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 agentdfd
- The DF-Description that is currently registered with the DFdeadline
- 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 searchdfName
- 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 searchdfName
- 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 DFdfName
- 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 DFdfName
- 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 notifiedconstraints
- 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 DFdfName
- 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:
-
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 taskdfName
- is the AID of the DF that should perform the requested actionactionName
- is the name of the action (one of the constants defined
in FIPAManagementOntology: REGISTER / DEREGISTER / MODIFY / SEARCH).dfd
- is the agent descriptionconstraints
- 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)