public class DFService extends FIPAService
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);
| Modifier and Type | Field and Description |
|---|---|
static java.lang.String |
DF_SEARCH_TIMEOUT_DEFAULT |
static java.lang.String |
DF_SEARCH_TIMEOUT_KEY |
| Constructor and Description |
|---|
DFService()
Default constructor.
|
| Modifier and Type | Method and Description |
|---|---|
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)
Process the content of the final
inform (Done) message
resulting from a register or deregister
action requested to a DF agent, extracting the
df-agent-description contained within. |
static DFAgentDescription[] |
decodeNotification(java.lang.String s)
Process the content of the
inform message resulting
from a subscription with a DF agent, extracting the array of
df-agent-description objects contained within. |
static DFAgentDescription[] |
decodeResult(java.lang.String s)
Process the content of the final
inform (result) message resulting
from a search action requested to a DF agent, extracting the array of
df-agent-description contained within. |
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 AID |
parseAID(SimpleSLTokenizer parser)
The parser content has the form:
agent-identifier ......)
|
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.
|
doFipaRequestClient, doFipaRequestClientpublic static final java.lang.String DF_SEARCH_TIMEOUT_KEY
public static final java.lang.String DF_SEARCH_TIMEOUT_DEFAULT
public static DFAgentDescription register(Agent a, AID dfName, DFAgentDescription dfd) throws FIPAException
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.
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.DFAgentDescription actually registered
by the DFFIPAException - 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.keepRegistered(Agent, AID, DFAgentDescription, Date)public static DFAgentDescription register(Agent a, DFAgentDescription dfd) throws FIPAException
DFAgentDescription with the default DFFIPAExceptionregister(Agent,AID,DFAgentDescription)public static void deregister(Agent a, AID dfName, DFAgentDescription dfd) throws FIPAException
dfName - The AID of the DF agent to deregister from.dfd - A DFAgentDescription object containing all
data necessary to the deregistration.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.public static void deregister(Agent a, DFAgentDescription dfd) throws FIPAException
DFAgentDescription from the default DFFIPAExceptionderegister(Agent a, AID dfName, DFAgentDescription dfd)public static void deregister(Agent a, AID dfName) throws FIPAException
FIPAExceptionderegister(Agent a, AID dfName, DFAgentDescription dfd)public static void deregister(Agent a) throws FIPAException
DFAgentDescription from the default DF.
A default DF-Description is used which contains only the AID
of this agent.FIPAExceptionderegister(Agent a, AID dfName, DFAgentDescription dfd)public static DFAgentDescription modify(Agent a, AID dfName, DFAgentDescription dfd) throws FIPAException
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.
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;DFAgentDescription actually registered
(after the modification) by the DFFIPAException - 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.keepRegistered(Agent, AID, DFAgentDescription, Date)public static DFAgentDescription modify(Agent a, DFAgentDescription dfd) throws FIPAException
DFAgentDescription from the default DF.FIPAExceptionmodify(Agent a, AID dfName, DFAgentDescription dfd)public static void keepRegistered(Agent a, AID df, DFAgentDescription dfd, java.util.Date deadline)
DFAgentDescription dfd = // fill DF-Description
try {
DFAgentDescription actualDfd = DFService.register(this, dfd);
DFService.keepRegistered(this, actualDfd, dfd.getLeaseTime());
}
catch (FIPAException fe) {
fe.printStackTarce();
}
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
timepublic static DFAgentDescription[] search(Agent a, AID dfName, DFAgentDescription dfd, SearchConstraints constraints) throws FIPAException
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 searchDFAgentDescription
containing all found
items matching the given
descriptor, subject to given search constraints for search depth
and result size.FIPAException - If a REFUSE,
FAILURE or NOT_UNDERSTOOD
message is received from the DF (to indicate some error condition)public static DFAgentDescription[] search(Agent a, DFAgentDescription dfd, SearchConstraints constraints) throws FIPAException
public static DFAgentDescription[] search(Agent a, DFAgentDescription dfd) throws FIPAException
public static DFAgentDescription[] search(Agent a, AID dfName, DFAgentDescription dfd) throws FIPAException
public static DFAgentDescription[] searchUntilFound(Agent a, AID dfName, DFAgentDescription dfd, SearchConstraints constraints, long timeout) throws FIPAException
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.null if the timeout expires.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.public static ACLMessage createRequestMessage(Agent a, AID dfName, java.lang.String action, DFAgentDescription dfd, SearchConstraints constraints)
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.
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.REGISTERFIPAManagementVocabulary.DEREGISTERFIPAManagementVocabulary.MODIFYFIPAManagementVocabulary.SEARCHdfd - 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.AchieveREInitiator,
decodeDone(String),
decodeResult(String)public static ACLMessage createSubscriptionMessage(Agent a, AID dfName, DFAgentDescription template, SearchConstraints constraints)
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.
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.SubscriptionInitiator,
createCancelMessage(Agent, AID, ACLMessage),
decodeNotification(String)public static ACLMessage getSubscriptionMessage(Agent a, AID dfName, DFAgentDescription template, SearchConstraints constraints) throws FIPAException
createSubscriptionMessage() insteadFIPAExceptionpublic static ACLMessage createCancelMessage(Agent a, AID dfName, ACLMessage subscribe)
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 DFSubscriptionInitiator,
createSubscriptionMessage(Agent, AID, DFAgentDescription, SearchConstraints),
decodeNotification(String)public static DFAgentDescription decodeDone(java.lang.String s) throws FIPAException
inform (Done) message
resulting from a register or deregister
action requested to a DF agent, extracting the
df-agent-description contained within.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.FIPAException - If some error occurs while decodingpublic static DFAgentDescription[] decodeResult(java.lang.String s) throws FIPAException
inform (result) message resulting
from a search action requested to a DF agent, extracting the array of
df-agent-description contained within.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.FIPAException - If some error occurs while decodingpublic static DFAgentDescription[] decodeNotification(java.lang.String s) throws FIPAException
inform message resulting
from a subscription with a DF agent, extracting the array of
df-agent-description objects contained within.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.FIPAException - If some error occurs while decodingpublic static AID parseAID(SimpleSLTokenizer parser) throws java.lang.Exception
java.lang.Exceptionpublic static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID dfName, java.lang.String actionName, DFAgentDescription dfd, SearchConstraints constraints) throws FIPAException
AchieveREInitiator insteadAgent.addBehaviour().
Several ways are available to get the result of this behaviour and the programmer can select one according to his preferred programming style:
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)FIPAException - A suitable exception can be thrown
to indicate some error condition
locally discovered (e.g.the agentdescription is not valid.)FIPAManagementOntologypublic static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName, DFAgentDescription dfd, SearchConstraints constraints) throws FIPAException
AchieveREInitiator insteadpublic static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName) throws FIPAException
AchieveREInitiator insteadpublic static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID dfName, java.lang.String actionName) throws FIPAException
AchieveREInitiator insteadpublic static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, java.lang.String actionName, DFAgentDescription dfd) throws FIPAException
AchieveREInitiator insteadpublic static RequestFIPAServiceBehaviour getNonBlockingBehaviour(Agent a, AID dfName, java.lang.String actionName, DFAgentDescription dfd) throws FIPAException
AchieveREInitiator instead