How to upgrade user code to JADE 2.0
Author:
Fabio Bellifemine (CSELT S.p.A.), Tiziana Trucco (CSELT S.p.A.)
Date: January,17 2000
Java
platform: Sun JDK 1.2
Windows
JADE
version 2.1
Compliance to FIPA 2000 specifications required also a slight modification of the API's of JADE 2.0. At a first glance, the user might be discouraged on porting his code from JADE 1.X to JADE 2.X because of the high number of error that the JAVA compiler would report; however in all cases, it is just a question of automatic replacement of code. This tutorial tries to help in this upgrading phase.
The following are the most considerable modifications in FIPA and how they impact your user code.
- Command line options
- The -platform option has been now set to the default. Therefore the command "java jade.Boot" does not start any more an agent container, instead it launches an agent platform. This default behaviour is more intuitive than the old one.
- Agent class
- According to the new FIPA specifications, the agent name, that was previously a String, has been replaced by the class jade.core.AID and composed of several attributes (i.e. name, addresses, resolvers ).In particular the name attribute is the globally unique identifier of the agent and, conceptually, replaces the agent name of the previous version of JADE. The previous methods Agent.getLocalName() and Agent.getName() continue to exist and work at the same way; however the full name of an agent is no more composed of its local name and the IIOP address of the platform. On the other hand, FIPA specifications do not allow any more to decompose an agent name and distinguish between the local name and its home agent platform (HAP) address (i.e. the separator '@' is no more used). Further to these methods, a new method has been added in JADE, Agent.getAID(), that returns the Agent Identifier of the agent.
The constructor AID(String guid) is available to construct an Agent Identifier on the basis of the known string representing the name of the agent.
- All the methods to access the services of the DF and the AMS have been moved from this class into the classes DFServiceCommunicator and AMSServiceCommunicator, part of the package jade.domain. Therefore, it is necessary to replace any call to Agent.registerDF(..) with DFServiceCommunicator.register(...)
- The two methods getDefaultDF() and getAMS() have been added that return the AID of the default DF and AMS of the platform.
- Because the SL-0 language has been modified to represent t-uples, the two methods fillContent and extractContent require/return a List argument, where the List represents the t-uple. Each element of the t-uple is an expression of the content language.
- ACLMessage class
- The new FIPA specifications have added two new parameters reply-to and encoding to the ACL Message structure, the first representing the AID of the agents to which the reply should be sent, the second representing the encoding scheme of the content. The specs also removed the envelope parameter that is now treated separately. The sender and receiver parameters do not contain any more String's, but AID's. As a consequence of that, the user code must be modified as follows:
- replace the getSource() and setSource(String) with getSender() and setSender(myAgent.getAID())
- replace getDest(), getFirstDest(), addDest() with getAllReceiver() (that returns an Iterator over all the receivers), clearAllReceiver(), addReceiverAID(), removeReceiver(AID).
- replace setReplyTo() and getReplyTo() with setInReplyTo and getInReplyTo. This modification has been made to avoid ambiguity with the new reply-to parameter of FIPA.
- replace setEnvelope(String) and getEnvelope(String) with addUserDefinedParameters("X:-envelope",String), getUserDefinedParameter("X:-envelope") because envelope is no more a parameter of an ACLMessage in the FIPA specs.
- take care of replying to messages by using the AID's in the reply-to parameter, when present, instead of those in the sender parameter. The best practice is to use the method ACLMessage.createReply() that already takes care of that.
- Care must be taken because the getXXX() methods return null, while in the previous realase they returned an empty string, when the parameter has not been set.
- the deprecated method dump() has been removed, replace it with System.out.println(msg.toString()).
- the deprecated method setType(String) has been removed, replace it with setPerformative(ACLMessage.REQUEST).
- the methods fromText() and toText() have been removed and replaced by the methods decode and encode in jade.lang.acl.StringACLCodec.
- Message Template class
- this class has been updated by adding methods to match the two new parameters encoding and reply-to and by removing the method to match the envelope.
- just remind to rename MatchReplyTo with MatchInReplyTo.
- AgentGroup class
- this class has been removed because obsolete. No class has been provided to replace this one: infact, a group of agent identifiers can easly be represented by a java.util.ArrayList().
- Class jade.domain.FIPAAgentManagement and its inner classes
- This class in JADE 1.4 included a number of inner classes to represent the concepts of the FIPA-Agent-Management ontology, included concepts like DFAgentDescription, ServiceAgentDescription,...
All this classes have been update to the new FIPA specifications and have been moved into the package jade.domain.FIPAAgentManagement. There is now one class for each concept of the ontology. Every class is a simple collection of the attributes defined by FIPA, with public methods to read and write them.
- class jade.lang.SL0Codec and interface jade.lang.Codec
- because FIPA specifications have modified the SL-0 content language to allow only t-uple as content, the encode and decode methods have been modified to work with List rather than Object.
- Package jade.onto and support to user defined ontologies
- This support has been simplified and improved by fixing a bug and adding support for set, sequences, and values of undefined type. Its quality, unfortunately, is not very yet satisfactory because it suffers from a lack of standadization for FIPA of an abstract content language and an abstract ontology. There, it might be modified again in the future.
The modifications are the following:
- The class TermDescriptor has been renamed into SlotDescriptior. The constructor of a SlotDescriptor has 4 arguments. The first is the name of the slot and can be omitted for unnamed slots. The second is the category of thew slot (i.e. FRAME, SET, SEQUENCE, PRIMITIVE,ANY). The third identifies the type of the values of the slot (e.g. STRING_TYPE,LONG_TYPE,...). The last indicates if the presence of the slot is mandatory or optional.
- The class RoleFactory has been renamed into RoleEntityFactory.
- The class jade.onto.basic.BasicOntology represents an ontology with basic concepts, like Actions, TruePredicate, AID,... It can be joined to any user-defined ontology.
- Class FIPARequestResponderBehaviour
- The interface of this class and its inner classes (i.e. ActionHandler and Factory) has been modified.
- The method create() of the Factory has now an argument which is the received request ACLMessage.
- The inner class Action has been renamed into ActionHandler in order to avoid ambiguity with jade.onto.basic.Action.
- A second argument, that is the received request ACLMessage, has been added to the constructor.
- All the method sendRefuse, sendAgree, sendFailure, sendInform, sendNotUnderstood have been joined into a single method sendReply with two arguments: the performative and the content of the message.
- A new method getActionName has been added to the FIPARequestResponderBehaviour class. The default implementation works only if both the content language and the ontology of the received request message were registered with the agent; otherwise it throws an exception. In general, it is expected that the user have to override this method with their application-dependent implementation.
JADE
is a trademark of
CSELT. JADE
has been developed jointly by CSELT and
the Computer Engineering Group of
the University of Parma