How to upgrade user code to JADE 3.0
Author:
Giovanni Caire (TILAB S.p.A.), Filippo Quarta (TILAB S.p.A.)
Date: March,12 2003
Java
platform: Sun JDK 1.2
Windows
JADE
version 3.0
Compliance to FIPA 2002 STANDARD specifications required also a slight modification of the API's of JADE 3.0. In order to simplify the code we also decided to remove some deprecated classes that where there for backward compatibility only. As a consequence in some cases applications written for JADE2.x may not run or even compile with JADE3.0. This tutorial tries to help in this upgrading phase.
The modifications introduced in JADE3.0 that may lead to backward incompatibilities are listed below together with an explanation about how to upgrade your code.
- Accessing the Yellow Pages and White Pages services provided by the JADE DF and AMS agents
- The register() and modify() methods of the jade.domain.DFService class now return the DFAgentDescription that has actually been stored by the DF agent. In fact, due to the introduction of the lease time in the yellow pages service, this description may be different with respect to the requested one (typically because a shorter lease time has been granted).
If you used these methods a java.lang.IncompatibleClassChangeError may be thrown when running your old application on JADE3.0. In order to solve this problem you only need to recompile your old application with JADE3.0 in the classpath.
- When searching the DF a SerachConstraints object has to be specified indicating, among others, the maximum number of results that you would like to receive from the DF. When this limit is not specified the DF (according to the new FIPA specifications) now sets it to 1 while it used to set it to "infinite" in JADE2.x.
In order to make the DF behave as it used to do in JADE2.x when the max result limit is not specified, you should explicitly set it to -1 ("infinite").
- The old (already deprecated) classes to access the services of the AMS and DF agent jade.domain.AMSServiceCommunicator, jade.domain.DFServiceCommunicator and jade.domain.FIPAServiceCommunicator have been removed. You should use jade.domain.AMSService, jade.domain.DFService and jade.domain.FIPAService instead. Look at the javadoc and JADE Programmers Guide for details on these classes
- JADE-Agent-Management ontology
- The definition of the Agent Platform description (ap-description) has changed in the new FIPA specifications. As a consequence the classes of the jade.domain.FIPAAgentManagement package related to it have been modified accordingly.
More in details an ap-description definition now includes a name and a set of services represented each one by an object of the APService class. The ap-transport-description and related mtp-descriptions, on the other hand, are no longer part of an ap-description definition and, as a consequence, the ApTransportDescription and MTPDescription classes representing them have been removed.
- In the new FIPA specifications the quit action is no longer part of the FIPA Agent Management ontology. As a consequence the jade.domain.FIPAAgentManagement.Quit class has been removed.
- Content language and ontology support
- The old support for content language and ontology based on the jade.onto package and on the registerLanguage(), registerOntology(), fillContent() and extractContent() methods of the jade.core.Agent class has been removed. Programmers should migrate to the new support included into the jade.content package.
Details about how to use it and how to migrate code based on the old support to the new one are provided in JADE Support to application-defined ontologies and content languages
- In order to make the transition between the old and the new support for content language and ontologies as smooth as possible
you can still use previously written application
ontologies, with minimal modification of your
code, by means of the jade2xback add-on available
on the jade site. A brief description about the use of this add-on follows:
- change your
code replacing import jade.core.Agent
with import jade.backward.Agent
- add the
jade2xback.jar to the classpath before
other JADE libraries
- run your
application as usual
Programmers are in any case strongly encouraged to migrate to the new support since a proper maintenance of the jade2xback add-on is not guaranteed.
- JADE built-in ontologies
- All the ontologies included in JADE, i.e. jade.domain.FIPAAgentManagement.FIPAAgentManagementOntology, jade.domain.JADEAgentManagement.JADEAgentManagementOntology, jade.domain.MobilityOntology and jade.domain.introspection.JADEIntrospectionOntology, have been substituted with the following ontologies compliant to the new ontology support (see previous bullet):
jade.domain.FIPAAgentManagement.FIPAManagementOntology, jade.domain.JADEAgentManagement.JADEManagementOntology, jade.domain.mobility.MobilityOntology and jade.domain.introspection.IntrospectionOntology.
All classes representing elements in these ontologies have been modified removing the (already deprecated) methods get_0()/set_0(), get_1()/set_1()... required by the old support for ontologies.
- Interaction Protocols
- The (already deprecated) classes providing support for interaction protocols FipaRequestInitiatorBehaviour, FipaRequestResponderBehaviour, FipaQueryInitiatorBehaviour, FipaQueryResponderBehaviour, FipaContractNetInitiatorBehaviour, FipaContractNetResponderBehaviour included in the jade.proto package have been substituted by a set of new classes
that provide a better, more uniform and more flexible support. These classes are AchieveREInitiator and AchieveREResponder, that should be used to implement FIPA-REQUEST like protocols including FIPA-QUERY, and ContractNetInitiator and ContractNetResponder. They are all included in the jade.proto package too.
- In order to make the transition between the old and the new interaction protocols classes as smooth as possible
the old classes are still available in the jade2xback add-on (see bullet on content language and ontology support).
- Following to the modification of the fipa-subscribe interaction protocol introduced in the new FIPA specification, the signature of the deregister() method of the jade.proto.SubscriptionResponder.SubscriptionManager interface has slightly changed. Now it returns a boolean value (while it used to return void) and throws jade.domain.FIPAAgentManagement.FailureException instead of jade.domain.FIPAAgentManagement.RefuseException and jade.domain.FIPAAgentManagement.NotUnderstoodException
- Other deprecated classes and methods removed
- The jade.core.behaviours.NonDeterministicBehaviour class has been removed. Programmers should use jade.core.behaviours.ParallelBehaviour instead. The old class is still available in the jade2xback add-on (see bullet on content language and ontology support)
- The setArguments(String) method of the jade.core.Agent class has been removed. Programmers should explicitly call Object[] getArguments() from within the setup() method instead.
- The toText() method of the jade.core.AID class has been removed. Programmers should use toString() instead.
- The preAction() and postAction() methods of the jade.core.behaviours.CompositeBehaviour class have been removed. Programmers should use onStart() and onEnd() instead.
- The toText(), getAllPerformatives() and setReplyBy(String) methods of the jade.lang.acl.ACLMessage class have been removed. Programmers should use toString(), getAllPerformativeNames(), setReplyByDate(Date) instead.
- The MatchReceiver(java.util.List), MatchReplyTo(java.util.List) and MatchReplyBy(String) methods of the jade.lang.acl.MessageTemplate class have been removed. Programmers should use MatchReceiver(AID[]), MatchReplyTo(AID[]) and MatchReplyByDate(Date) instead.
- The delete() method of the jade.wrapper.Agent class has been removed. Programmers should use kill() instead.
- The createAgent() method of the jade.wrapper.AgentContainer class has been removed. Programmers should use createNewAgent() instead.
JADE
is a trademark of
TILAB. JADE
has been developed jointly by CSELT and
the Computer Engineering Group of
the University of Parma