To develop applications with Jadex, the programmer has to create two types of files: XML agent definition files (ADF) and Java classes for the plan implementations. The ADF can be seen as a type specification for a class of instantiated agents. For example Buyer agents (from the booktrading example) are defined by the Buyer.agent.xml file, and use plans implemented, e.g. in the file PurchaseBookPlan.java. The user guide describes both aspects of agent programming, the XML based ADF declaration and the plan programming Java API, and highlights the interrelations between them. Detailed reference documentation for the XML definition as well as the plan programming API is also separately available in form of the generated XML schema documentation and the generated Javadocs. Figure 3.1, “ Components of a Jadex agent ” depicts how XML and Java files together define the functionality of an agent. To start an agent, first the ADF is loaded, and the agent is initialized with beliefs, goals, and plans as specified.

Figure 3.1.  Components of a Jadex agent

The head of an ADF looks like shown in Figure 3.2, “Header of an agent definition file”. First, the agent tag specifies that the XML document follows the jadex-0.96.xsd schema definition which allows to verify that the document is not only well formed XML but also a valid ADF. The name of the agent type is specified in the name attribute of the agent tag, which should match the file name without suffix (.agent.xml). It is also used as default name for new agent instances, when the ADF is loaded in the starter panel of the Jadex Control Center (see [Jadex Tool Guide]). The package declaration specifies where the agent first searches for required classes (e.g., for plans or beliefs) and should correspond to the directory, the XML file is located in. Additionally required packages can be specified using the <imports> tag (see Chapter 4, Imports). The Jadex engine requires some properties for initialization, which are by default taken from the file jadex/config/runtime.properties.xml. Normally, this is not of interest for agent developers, as it is only concerned with system internals, but developers who whish to change the behavior of the Jadex engine can use the properties attribute to provide their own property XML file with customized settings (see Chapter 12, Properties for a detailed description).

<agent xmlns="http://jadex.sourceforge.net/jadex"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://jadex.sourceforge.net/jadex
                           http://jadex.sourceforge.net/jadex-0.96.xsd"
       name="Buyer"
       package="jadex.examples.booktrading.buyer">
       ...
</agent>

Figure 3.3, “ Jadex agent XML schema ” shows which elements can be specified inside an agent definition file (please refer also to the commented schema documentation generated from the schema itself in docs/schemadoc). The <imports> tag is used to specify, which classes and packages can be used by expressions throughout the ADF. To modularize agent functionality, agents can be decomposed into so called capabilities. The capability specifications used by an agent are referenced in the <capabilities> tag. The core part of the agent specification regards the definition of the beliefs, goals, and plans of the agent, which are placed in the <beliefs>, <goals>, and <plans> tag, respectively. The events known by the agent are defined in the <events> section. The <expressions> tag allows to specify expressions and conditions, which can be used as predefined queries from plans. The <properties> tag is used for custom settings such as debugging and logging options. Finally, in the <configurations> section, predefined configurations containing, e.g., initial beliefs, goals, and plans, as well as end goals and plans are specified.

Figure 3.3.  Jadex agent XML schema

It should be noted that, unless otherwise stated, the order of occurrence of the elements is prescribed by the underlying XML Schema. Therefore, you cannot, e.g., declare plans before beliefs. Throughout this user guide figure like Figure 3.3, “ Jadex agent XML schema ” will always denote the correct order of element appearence (from top to bottom). Of course, it is possible to omit those elements, which are not required for your agent.

When an ADF is loaded, Java objects are created for the XML elements (e.g., beliefs, goals, plans) defined in the ADF. The interfaces for these so called model elements reside in the package jadex.model. Examples are IMBelief, IMGoal, IMPlan. In most cases, you do not need to access these elements. When the agent is executed, instances of the model elements are created; so called runtime elements (package jadex.runtime, e.g., IBelief, IGoal, IPlan). This ensures that for modelled elements (e.g., IMPlan objects) at runtime several instances (IPlan objects) can be created. For example, the buyer agent will instantiate new purchase book plans (IPlan) for each book to be bought, based on the plan specification in the ADF (IMPlan). Think of the relation between model elements and runtime elements as corresponding to the relation between java.lang.Class and java.lang.Object. When programming plans, you are mostly concerned with the runtime elements, unless the agent model should be changed dynamically at runtime. In this case you can fetch model elements by calling getModelElement() on a runtime element.