Jadex is realized as pure reasoning engine. This means that Jadex agents can potentially run on any middleware platform that fulfills some basic services concerning agent management and messaging. Currently, adapters for Jadex have been realized for the agent platform JADE and for a Standalone platform.
There is currently no dedicated manual availabe explaining how to
build a new middleware adapter. If you are interested in developing a
new adapter consider looking into the jadex.adapter
package, which contains a handful of interfaces that every adapter has to implement.
If you have any problems feel free to contact us directly. The same applies
if you already developed a new adapter. We would be glad to know about it
and possibly getting the chance to announce/link it on the Jadex web site.
In the following it is explained how you can configure and start Jadex using the Standalone and the JADE adapter.
The Jadex Standalone adapter is a fast and efficient execution
environment for Jadex agents with a small memory footprint.
The Standalone adapter is already contained in the normal Jadex
distribution and needs to be put into the classpath (jadex_standalone.jar).
You can start the Standalone adapter via the following command line:
java jadex.adapter.standalone.Platform [-conf filename] [-transport classname:port] [-notransport] [-nogui] [-noamsagent] [-nodfagent] [-autoshutdown]
Alternatively you can also use the following command to start the platform directly from the jar:
java -jar jadex_standalone.jar [options]
-conf: The property -conf can be used to configure the Jadex system.
Per default it will search the current directory for the file jadex.properties
and if not found the classpath will be searched (in each adapter jar a configuration is contained).
-platformname: The unique platform name. If more than one Jadex platform should run on the same machine it is useful to start them with different platform names (and with transports at different ports).
-transport: The standard transport mechanism for remote
communication. As value the Java class name of a class that implements
jadex.adapter.standalone.ITransport
should be supplied. Optionally the port for this transport can also be
supplied. To start the "niotcp" (TCP/IP) based
transport layer at port 9876 use the setting:
-transport jadex.adapter.standalone.transport.niotcpmtp.NIOTCPTransport:9876
(Since the new I/O (NIO) is only provided in Java 1.4 or later, we also provide another
Java 1.3 compatible transport, which can be selected as follows:
-transport jadex.adapter.standalone.transport.tcpmtp.TCPTransport:9876)
-notransport: Starts the platform without a remote transport mechanism.
-nogui: Starts the platform without user interface and the corresponding Jadex Control Center agent.
-noamsagent: Starts the platform without creating an Agent Management Service (AMS) agent. Note, this does only prevent remote agent access to the AMS as the AMS service is always available.
-nodfagent: Starts the platform without creating a Directory Facilitator (DF) agent. Note, this does only prevent remote agent access to the DF as the DF service itself is always available.
-autoshutdown: Automatically shut down the platform when the last agent is killed.
To start an agent from the command line, the name and properties of the agent are given after the platform start command. The syntax for each agent is given below. This way an arbitrary number of agents can be started when launching the platform.
name:model[(configuration[, arg1name=arg1, ..., argNname=argN])]
name: The name of the agent instance, which can be freely chosen, as long as no two agents would get the same name.
model: The file name or logical name of the agent model
(e.g. jadex.examples.helloworld.HelloWorld or
jadex/examples/helloworld/HelloWorld.agent.xml).
configuration: The name of the configuration to use as defined in the agent model. If the configuration is omitted, the default configuration of the agent is used.
argNname=argN: Agent arguments can be supplied following
the configuration. Each argument is given as a name-value pair separated
by an equals sign. The value part can be an arbitrary Java expression
that is parsed before being given to the agent (e.g. new java.awt.Color(255,0,0)).
The following example starts the standalone platform and
instantly starts a hello world agent using a custom argument.
Note that the quotes for the string argument have to be escaped (using \"),
because the agent specification as a whole is enclosed in quotes.
java jadex.adapter.standalone.Platform "hello:jadex.examples.helloworld.HelloWorld(default, msg=\"Hi!\")"
The JADE adapter is not contained in the standard Jadex distribution and needs
to be downloaded separately from the Jadex sourceforge download page.
It contains the adapter jar (jadex_jadeadapter.jar)
that should be added to the classpath. In addition (compatibility tested)
official JADE jars (Base64.jar, http.jar,
iiop.jar, jade.jar, jadeTools.jar)
and additionally Crimson (crimson.jar) are contained.
These jars are found automatically if they reside in the same directory as the jadex_jadeadapter.jar.
The same is true for the other required Jadex jars (see Section 1.1, “Requirements and Installation”), i.e. you should copy
all jars (except jadex_standalone.jar) from the Jadex main distribution into the jadeadapter's lib directory.
The JADE adapter contains a helper class, which can be used to start the JADE platform and open the Jadex Control Center. To start the platform, use the command:
java jadex.adapter.jade.tools.Starter [JADE options] [JADE/Jadex agents]
Alternatively you can also start the platform from jar via:
java -jar jadex_jadeadapter.jar [JADE options] [JADE/Jadex agents]
JADE options: For the JADE options, all flags and configuration options of JADE can be used. E.g. -container, -host, -port, etc.
JADE/Jadex agents: Agents can be started from the command
line using the normal JADE syntax "agentname:classname(arg1 arg2 ...)". If you
want to start a Jadex agent from the command line, the classname needs to be
jadex.adapter.jade.JadeAgentAdapter, the first argument
to the agent must be the name of the agent model (the XML file) and
the second argument is the name of the configuration to be used.
The JCC is also a normal Jadex agent, which can be started in JADE as any other agent. Therefore, JADE and the JCC can also be started as follows:
java jade.Boot [JADE options] jcc:jadex.adapter.jade.JadeAgentAdapter(jadex.tools.jcc.JCC default) [other JADE/Jadex agents]
JADE does its own processing of argument values before handing them to Jadex. Therefore, one needs an extra layer of escaping characters, which would otherwise get mangled by JADE. The helloworld example described before therefore needs to be started like this (note the three backslashes before the quotes of the string argument):
java jade.Boot jcc:jadex.adapter.jade.JadeAgentAdapter(jadex.examples.helloworld.HelloWorld default msg=\\\"Hi!\\\")
The system property -Dconf can be used in all cases desribed above,
to configure the Jadex system (e.g. java -Dconf=myjadex.properties [...]).
Per default it will search the current directory for the jadex.properties
and if not found the classpath will be searched (in each adapter jar a configuration is contained).
This section assumes that you know how to use ontologies and content languages
in JADE. More information about this is provided in the document "Creating and using applications-specific ontologies"
available in the JADE distribution or from the JADE homepage at http://jade.tilab.com/doc/index.html.
In summary, the JADE content management requires that the message content object must be
instance of a jade.content.ContentElement.
The concrete class of the object should belong to some ontology, which
can be generated using the Beanynizer tool of Jadex (described in the tool guide)
or the JADE ontology beangenerator available from the JADE homepage.
Making JADE content management available to a Jadex agent is achieved by
a small helper class, that implements a JADE specific Jadex content codec.
An instance of this class JadeContentCodec (from package
jadex.adapter.jade) has to be created
for each pair of language and ontology that you want to support.
These instances are added to the properties section of an agent:
<properties>
<property name="contentcodec.fipa-management-sl0">
new JadeContentCodec(new SLCodec(0), FIPAManagementOntology.getInstance())
</property>
<property name="contentcodec.jade-management-sl0">
new JadeContentCodec(new SLCodec(0), JADEManagementOntology.getInstance())
</property>
</properties>
Among the nice features of JADE is the ability to migrate agents between hosts, and to persist the state of an agent such that it can later be restored. These features are based on Java's serialization mechanism. Jadex has been designed in order to support serialization of agents at runtime. Nevertheless, there are some issues, the application developer has to be aware of:
Only mobile plans are supported for agents which need to be serialized for migration or persistence. Standard plans are backed by separate threads for each plan, and therefore cannot be serialized.
All objects that are used from plans or stored as facts in the beliefbase or as parameters (e.g., in goals) also have to be serializable.
Due to a bug in JADE, you cannot use basic Java types such as int or arrays
(e.g. Object[] or String[]) as class of your beliefs or parameters.
For details on the bug or to see if it has been fixed, have a look at
its entry in the JADE bug database (bug 0000107).
A simple workaround is to use the wrapper types such as
java.lang.Integer instead of the basic types, and Object
instead of array types (or even better, use a belief set instead of an array).
<!-- This does not work. -->
<belief name="my_int_belief" class="int">
<fact>42</fact>
</belief>
<belief name="my_stringarray_belief" class="String[]">
<fact>new String[]{"value1", "value2"}</fact>
</belief>
<!-- This works. -->
<belief name="my_integer_belief" class="Integer">
<fact>42</fact>
</belief>
<belief name="my_arrayobject_belief" class="Object">
<fact>new String[]{"value1", "value2"}</fact>
</belief>
<beliefset name="my_string_beliefset" class="String">
<fact>"value1"</fact>
<fact>"value2"</fact>
</beliefset>
The Jadex distribution contains two larger examples which explicitly support
migration: Cleanerworld and Puzzle. See packages
jadex.examples.cleanerworld.multi.cleanermobile and
jadex.examples.puzzle.mobile.
For a simple example supporting migration see the ping example
(package jadex.examples.ping.mobile).
If you have some legacy JADE code that you want to use in a Jadex agent, but you do not
want to convert your JADE behaviours to Jadex plans, you can still use them in the old
fashioned way. From a plan, you can get a reference to the jade.core.Agent
which is executing the BDI reasoning engine. You may add your own additional JADE behaviours
to this agent, which will then be executed concurrent to your BDI goals and plans.
Note, that this programming style is meant for easy porting of legacy JADE applications.
In general, you should avoid hybrid JADE/Jadex agents, because the
these mixed-style agents may easily become incomprehensible.
Moreover, hybrid agents will not be portable to other middleware platforms.
To add a behaviour to a Jadex agent just call the addBehaviour() method
of the JADE agent, which is accessible
using getScope().getPlatformAgent(), and casting the
result to jade.core.Agent:
// Add a JADE behaviour to the agent from a plan. jade.core.Agent agent = (jade.core.Agent)getScope().getPlatformAgent(); agent.addBehaviour(new MyJADEBehaviour());
Per default all incoming messages are handled by Jadex. To enable custom JADE behaviours to handle incoming messages, these have to be ignored by the Jadex system. You can specify a message template as an agent property in the ADF to identify those messages that should not be handled by Jadex:
<agent ...>
...
<properties>
<!-- Setup a filter for messages which are handled by JADE behaviours. -->
<property name="jadefilter">
MessageTemplate.MatchPerformative(ACLMessage.QUERY_REF)
</property>
</properties>
...
</agent>