If you want to run the Jadex examples to get a quick overview of the system, you may download one of the read-to-run installer bundles available from the project homepage, or run the system directly from the web.

If you intend to develop agent software with Jadex it is necessary to set up Jadex on your system Only few steps are necessary. It is recommended to do these steps by hand to see how the required components fit together.

Software.  The following describes the 3rd party software required to run Jadex.

Installation.  If you have not already done so, download the Jadex distribution .zip and unpack it to a directory of your choice. Afterwards, add at least the libraries described below to your class path. The following assumes for simplicity, that you are running Jadex from the console. If you prefer, you can also use your favourite IDE to enter classpath settings and run configurations.

Besides these standard libraries, which are needed for the execution of agents, some extra libraries are included for certain features. The control center uses the JavaHelp system, which requires the jhall.jar. The Jadex tracer tool requires additionally the also contained GraphLayout.jar. The introspector detail view output can be visually improved (html instead of plain text) by also using a velocity.jar (not included, see http://jakarta.apache.org/velocity).

This chapter describes how to run the examples provided with the Jadex distribution. Following the instructions below you can test if your Jadex installation works correctly.

Rational agents have an explicit representation of their environment (sometimes called world model) and of the objectives they are trying to achieve. Rationality means that the agent will always perform the most promising actions (based on the knowledge about itself and the world) to achieve its objectives. As it usually does not know all of the effects of an action in advance, it has to deliberate about the available options. For example a game playing agent may choose between a safe action or an action, which is risky, but has a higher reward in case of success.

To realise rational agents, numerous deliberative agent architectures exist (e.g. BDI [Bratman 1987], AOP [Shoham 1993], 3APL [Hindriks et al. 1999] and SOAR [Lehman et al. 1996] to mention only the most prominent ones). In these architectures, the internal structure of an agent and therefore its capability of choosing a course of action is based on mental attitudes. The advantage of using mental attitudes in the design and realisation of agents and multi-agent systems is the natural (human-like) modelling and the high abstraction level, which simplifies the understanding of systems [McCarthy et al. 1979].

Regarding the theoretical foundation and the number of implemented and successfully applied systems, the most interesting and widespread agent architecture is the Belief-Desire-Intention (BDI) architecture, introduced by Bratman as a philosophical model for describing rational agents ([Bratman 1987]). It consists of the concepts of belief, desire and intention as mental attitudes, that generate human action. Beliefs capture informational attitudes, desires motivational attitudes, and intentions deliberative attitudes of agents. [Rao and Georgeff 1995] have adopted this model and transformed it into a formal theory and an execution model for software agents, based on the notion of beliefs, goals, and plans.

Jadex facilitates using the BDI model in the context mainstream programming, by introducing beliefs, goals and plans as first class objects, that can be created and manipulated inside the agent. In Jadex, agents have beliefs, which can be any kind of Java object and are stored in a beliefbase. Goals represent the concrete motivations (e.g. states to be achieved) that influence an agent's behavior. To achieve its goals the agent executes plans, which are procedural recipes coded in Java. The abstract architecture of a Jadex agent is depicted in Figure 2.1, “Jadex Abstract Architecture”.

Figure 2.1. Jadex Abstract Architecture

Reasoning in Jadex is a process consisting of two interleaved components. On the one hand, the agent reacts to incoming messages, internal events and goals by selecting and executing plans (means-end reasoning). On the other hand, the agent continuously deliberates about its current goals, to decide about a consistent subset, which should be pursued.

The main concepts of Jadex are beliefs, goals and plans. The beliefs, goals and plans of the agent are defined by the programmer and prescribe the behavior of the agent. E.g., the current beliefs influence the deliberation and means-end reasoning processes of the agent, and the plans may change the current beliefs while they are executed. Changed beliefs in turn may cause internal events, which may lead to the adoption of new goals and the execution of further plans. In the following the realisation of each of these main concepts in Jadex will be shortly described.

2.1.2. The Goal Structure

Unlike traditional BDI systems, which treat goals merely as a special kind of event, goals are a central concept in Jadex. Jadex follows the general idea that goals are concrete, momentary desires of an agent. For any goal it has, an agent will more or less directly engage into suitable actions, until it considers the goal as being reached, unreachable, or not desired any more. Unlike most other systems, Jadex does not assume that all adopted goals need to be consistent to each other. To distinguish between just adopted (i.e. desired) goals and actively pursued goals, a goal lifecycle is introduced which consists of the goal states option, active, and suspended (see Figure 2.2, “Goal Lifecycle”). When a goal is adopted, it becomes an option that is added to the agent's desire structure. Application specific goal deliberation mechanisms are responsible for managing the state transitions of all adopted goals (i.e. deciding which goals are active and which are just options). In addition, some goals may only be valid in specific contexts determined by the agent's beliefs. When the context of a goal is invalid it will be suspended until the context is valid again.

Figure 2.2. Goal Lifecycle

Four types of goals are supported by the Jadex system: Perform, achieve, query, and maintain goals as introduced by JAM [Huber 1999]. A perform goal states that something should be done but may not necessarily lead to any specific result. For example, a waste-pickup robot may have a generic goal to wander around and look for waste, which is done by a specific plan for this functionality. The achieve goal describes an abstract target state to be reached, without specifying how to achieve it. Therefore, an agent can try out different alternatives to reach the goal. Consider a player agent that needs certain resources in a strategy game: It could choose to negotiate with other players or try to find the required resources itself. The query goal represents a need for information. If the information is not readily available, plans are selected and executed to gather the needed information. For example a cleaner robot that has picked up some waste needs to know where the next waste bin is located. If it already knows the location it can directly head towards the waste bin, otherwise it has to find one, e.g by executing a search plan. The maintain goal specifies a state that should be kept (maintained) once it is achieved. It is the most abstract goal in Jadex. Not only does it abstract from the concrete actions required to achieve the goal, but also it decouples the creation and adoption of the goal from the timepoint when it is executed. For example the goal to keep a reactor temperature below a certain level is a maintain goal that gets triggered whenever the temperature exceeds the normal operating level. As with achieve and query goals, to (re)establish the desired target state of a maintain goal, the agent may try out several plans, until the state is reached.

In the Jadex System, goals are represented as objects with several attributes. The target state of achieve goals can be explicitly specified by an expression (e.g., referring to beliefs), which is evaluated to check if the goal is achieved. Attributes of the goal, such as the name, facilitate plan selection, e.g. by specifying that a plan can handle all goals of a given name. Additional (user-defined) goal parameters guide the actions of executing plans. For example in a goal to search for services (e.g. using the FIPA directory facilitator service), additional search constraints could be specified (such as the maximum cardinality of the result set). The structure of currently adopted goals is stored in the goalbase of an agent. The agent has a number of top-level goals, which serve as entry points in the goalbase. Goals in turn may have subgoals, forming a hierarchy or tree of goals.

The complete definition of an agent is captured in a so called agent definition file (ADF). The ADF is an XML file, which contains all relevant properties of an agent (e.g. the beliefs, goals and plans). In addition to the XML tags for the agent elements, the developer can use expressions in a Java-like syntax for specifying belief values and goal parameters. The ADF is kind of a class description for agents: From the ADF agents get instantiated like Objects get instantiated from their class. For example, the different player agents from BlackJack (src/jadex/examples/blackjack) share Player.agent.xml as their definition file.

For each element ADF in the all important properties can be defined as attributes or subtags. For example, plans are declared by specifying how to instantiate them from their Java class (body tag), and a trigger (e.g. event) can be stated, that determines under which conditions a plan gets executed. Moreover, in the ADF, the initial state of an agent (how the agent should look like, when it is born) is determined in a so called configuration, which defines the initial beliefs, initial goals, and initial plans.

This sections shows the operation of the reasoning component, given the Jadex BDI concepts (see Figure 2.3, “Jadex Execution Model”). Since version 0.93 Jadex does not employ the classical BDI-interpreter cycle as described in the literature [Rao and Georgeff 1995] but uses a new agenda based execution scheme (described more extensive and formally in [Pokahr et al. 2005b]). The interpreter consists of an agenda component holding the scheduled meta-actions to execute. The basic mode of operation is simple: The agent selects a meta-action from its agenda and executes it when the the action's preconditions hold. Otherwise the action is simply dropped. The execution of the action may produce further actions that are added to the agenda following a customizable insertion strategy. Currently, the insertion strategy mainly distinguishes between related and unrelated actions, whereby related actions are added as child nodes to the current node.

Figure 2.3. Jadex Execution Model

Besides the creation of new agenda entries, the execution of actions can have further side-effects that are of importance for the agent, e.g. when a belief is changed or a goal is dropped. These occurrences are captured within jadex.runtime.SystemEvents and may cause system changes which are computed by a change determination component accordingly. To determine which effects certain SystemEvents have, the component evaluates affected conditions. If a condition triggers, new agenda actions may be produced in turn and are added to the agenda.

Having outlined the mode of operation the question arises which kinds of actions are contained within the agenda? These action are not application level actions, but are inter alia derived from the classical BDI interpreter cycle and represent BDI-meta actions. Two typical BDI-meta actions are displayed at the top of Figure 2.3, “Jadex Execution Model” namely the ProcessEventAction and the ExecutePlanStepAction. The ProcessEventAction encapsulates the well-known BDI plan finding process. The meta action searches for applicable plans matching to an event or goal occurence, selects candidates from the list and schedules them for execution by creating ExecutePlanStepActions for each candidate. An ExecutePlanStepAction simply execute one step of its plan and produces a new ExecutePlanStepAction when further steps for this plan are necessary. (All meta-actions are implemented in the jadex.runtime.impl.agenda package).

Advantages of the new approach are that the new mechanism offers a much higher degree of extensibility and flexibility as new BDI-meta actions can be easily added to the system if desired. One concrete effect already contained in this version is the support for goal deliberation via the "Easy Deliberation" strategy Section 7.7, “ Goal Deliberation with "Easy Deliberation" ” which is realized with extended meta-actions.

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.

A capability is basically the same as an agent, but without its own reasoning process. On the other hand, an agent can be seen as a collection (i.e. subcapability hierarchy) of capabilities plus a separate reasoning process shared by all its capabilities. Each agent has at least one capability (sometimes called “root capability”) which is given by the beliefs, goals, plans, etc. contained in the agent's XML file. To create additional capabilities for reuse in different agents, the developer has to write capability definition files. A capability definition file is similar to an agent definition file, but with the <agent> tag replaced by <capability>. The <capability> tag has the same substructure as the <agent> tag described in Section 3.2, “Structure of Agent Definition Files (ADFs)”. Note that the <capability> tag has name and package attributes, but no propertyfile attribute. As there are so many similarities between agent definition files and capability definition files, we commonly use the term “ADF” to denote both.

<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="MyCapability"
       package="mypackage">
    
       <beliefs> ... </beliefs>
       <goals> ... </goals>
       <plans> ... </plans>
       ...
</capability>

Agents and capabilities may be composed of any number of subcapabilities which are referenced in a <capabilities> tag. To reference a capability, a local name and the location of the capability definition has to be supplied in the file attribute as absolute or relative file name or capability type name. Type names are resolved using the package and import declarations, and can therefore be unqualified or fully qualified. Capabilities from the jadex.planlib package, such as the DF capability, which have platform-specific implementations, must always be referenced using a fully qualified type name.

<agent ...>
    <capabilities>
        <!-- Referencing a capability using a filename. -->
        <capability name="mysubcap" file="mypackage/MyCapability.capability.xml"/>
        
        <!-- Referencing a capability using a fully qualified type name. -->
        <capability name="dfcap" file="jadex.planlib.DF"/>
        ...
    </capabilities>
    ...
</agent>

The capability introduces a scoping of the BDI concepts. By default all beliefs, goals, and plans have local scope (i.e., are not exported), that is they can only be used in the capability where they have been defined. This restriction can be relaxed by declaring elements as exported or abstract for making them accessible from the outer capability (cf. Figure 5.1, “Capability concept”). In the outer capability such elements can be used when an explicit reference (with its own possibly different name) to those elements is established. In Figure 5.4, “Jadex references XML schema elements” this reference mechanism, which applies to all elements in the same manner, is exemplarily depicted for beliefs. In the following the possible use cases are described.

Figure 5.4.  The Jadex references XML schema elements (using beliefs as example)

<belief name="myexportedbelief" exported="true" class="MyFact"/>

<beliefref name="mysubbelief">
    <concrete ref="mysubcap.myexportedbelief"/>
</beliefref>

<beliefref name="myabstractbelief" exported="true" class="MyFact">
    <abstract/>
</beliefref>

<belief name="mybelief" class="MyFact">
    <assignto ref="mysubcap.myabstractbelief"/>
</belief>

By default, elements of an outer capability behave the same, regardless if they are references to concrete inner elements or concrete elements assigned to abstract inner elements. Sometimes one wants to distinguish between e.g. goals, created inside a capability and goals created from the outside. When using concrete elements in the inner capability (and therefore references in the outer capability) you can choose between strong export (exported="true") and weak export (exported="shielded"). When a weakly exported element is instantiated inside a capability references in the outer capability will not be created. The strong export, on the other hand, will always instantiate the complete reference structure of an element. For most use cases, the strong export will be appropriate.

The beliefbase is the container for the facts known by the agent. Beliefs are usually defined in the ADF and accessed and modified from plans. To define a single valued belief or a multi-valued belief set in the ADF the developer has to use the corresponding <belief> or <beliefset> tags (Figure 6.1, “The Jadex beliefs XML schema part”) and has to provide a name and a class. The name is used to refer to the fact(s) contained in the belief. The class specifies the (super) class of the fact objects that can be stored in the belief. The default fact(s) of a belief may be supplied in enclosed <fact> tags. Alternatively, for belief sets a collection of initial facts can be directly specified using a <facts> tag. This is useful, when you do not know the number of initial facts in advanvce, e.g., when invoking a static method or retrieving values from a database (see Figure 6.2, “Example belief definition”). References to beliefs and belief sets from inner capabilities can be defined using the <beliefref> and <beliefsetref> tags (cf. Section 5.3, “Elements of a Capability”).

Figure 6.1. The Jadex beliefs XML schema part

<agent ...>
    ...
    <beliefs>
        <belief name="my_location" class="Location">
            <fact>new Location("Hamburg")</fact>
        </belief>
        <beliefset name="my_friends" class="String">
            <fact>"Alex"</fact>
            <fact>"Blandi"</fact>
            <fact>"Charlie"</fact>
        </beliefset>
        <beliefset name="my_opponents" class="String">
            <facts>Database.getOpponents()</facts>
        </beliefset>
        ...
    </beliefs>
    ...
</agent>

From within a plan, the programmer has access to the beliefbase (class IBeliefbase) using the getBeliefbase() method. The beliefbase provides getBelief() / getBeliefSet() methods to get the current beliefs and belief sets by name, as well as methods to create new beliefs and belief sets or remove old ones. The content of a belief (class IBelief) can be accessed by the getFact() method. A belief set (class IBeliefSet) is accessed through the getFacts() method and will return an appropriately typed array of facts. To check if a fact is contained in a belief set the containsFact() method can be used.

The contents of a single fact belief are modified using the setFact() method. Setting a fact on a belief will result in overwriting the previous value, if any. For deleting the fact of a single fact belief, you can set the belief value to null. Belief sets are manipulated using the addFact(fact) / removeFact(fact) methods. When removing facts that do not exist from the belief set, the belief set remains unchanged and a warning message will be produced. For the remove operation, the beliefbase relies on the implementation of the equals() method of the fact objects. Additionally, updateFact(fact) can be used to replace an existing fact value.

public void body {
    ...
    IBelief hungry = getBeliefbase().getBelief("hungry");
    hungry.setFact(new Boolean(true));
    ...
    Food[] food = (Food[])getBeliefbase().getBeliefSet("food").getFacts();
    ...
}

In the ADF the initial facts of beliefs are specified using expressions. Normally, the fact expressions are evaluated only once: When the agent is born. The evaluation behavior of the fact expression can be adjusted using the evaluationmode attribute as further described in Section 10.2, “Expression Properties”. Additionally, an updaterate may be specified as attribute of the belief that will cause the fact to be continuously evaluated and updated in the given time interval (in milliseconds).

In the example, the first belief "time" is evaluated on access, and will therefore always contain the exact current time as returned by the Java function System.currentTimeMillis(). The second belief "timer" is not only evaluated on access (i.e., when accessed), but also every 10 seconds (10000 milliseconds). The advantage of using an updaterate for continuously evaluating a belief is that the fact value changes even when it is not accessed, and therefore may trigger conditions referring to that belief. For example, using the "timer" belief you could define a condition to invoke a plan that has to be executed in continuous intervals. Both options also provide an easy and effective way for making an agent aware of external input (e.g., sensory data available through a Java API).

<beliefs>
    <!-- A belief holding the current time (re-evaluated on every access). -->
    <belief name="time" class="long">
        <fact evaluationmode="dynamic"> 
            System.currentTimeMillis() 
        </fact>
    </belief>

    <!-- A belief continuously updated every 10 seconds. -->
    <belief name="timer" class="long" updaterate="10000">
        <fact> System.currentTimeMillis() </fact>
    </belief>
</beliefs>

To monitor conditions (cf. Chapter 11, Conditions), an agent observes the beliefs and automatically reacts to changes of these beliefs, as necessary. Jadex is aware of manipulation operations that are executed directly on beliefs, e.g., by setting the fact of a belief, and of changes due to belief dependencies (i.e., a dynamically evaluated fact expression referencing another belief).

On the other hand, when you retrieve a complex fact object from a belief or belief set and perform operations on it subsequently, the system cannot detect the changes made. To enable the system detecting these changes the standard Java beans event notification mechanism can be used. This means that the bean has to implement the add/removePropertyChangeListener() methods and has to fire property change events, whenever an important change has occurred. The belief will automatically add and remove itself as a property change listener on its facts. An example how to implement this functionality inside a Java bean is shown below.

import java.beans.PropertyChangeSupport;
import java.beans.PropertyChangeListener;

public class Location {
    private int x, y;
    private PropertyChangeSupport pcs;

    public Location(int x, int y) {
        this.x = x;
        this.y = y;
        this.pcs = new PropertyChangeSupport(this);
    }

    public int getX() {
        return this.x;
    }
    public void setX(int x) {
        int old = this.x;
        this.x = x;
        this.pcs.firePropertyChange("X", old, this.x);
    }

    public int getY() {
        return this.y;
    }
    public void setY(int y) {
        int old = this.y;
        this.y = y;
        this.pcs.firePropertyChange("Y", old, this.y);
    }

    public void addPropertyChangeListener(PropertyChangeListener listener) {
        pcs.addPropertyChangeListener(listener);
    }
    public void removePropertyChangeListener(PropertyChangeListener listener) {
        pcs.removePropertyChangeListener(listener);
    }
}

In Figure 7.2, “The Jadex common goal features” the base type of all four goal kinds is depicted to illustrate the shared goal features. In Jadex, goals are strongly typed in the sense that all goal types can be identified per name and all parameters of a goal have to be declared in the XML. The declaration of parameters resembles very much the specification of beliefs. Therefore it is distinguished between single-valued parameters and multi-valued parameter sets. As with beliefs, arbitrary expressions can be supplied for the parameter values. The system distingiushes in, out, and inout, parameters, specified using the direction attribute. in parameters are set before the goal is dispatched, while out parameters are set by the plan processing the goal, and can be read when the goal returns. Additionally, it can be specified that a parameter is not mandatory by using the optional attribute. Whenever a goal instance of the declared type is created and dispatched to the system it will be checked with respect to its parameters, and when no value has been supplied for a mandatory in parameter or parameter set a runtime exception will be thrown. The creation of new goals can be further influenced by using binding options for parameters via the <bindingoptions> tag instead of the <value> tag. All possible combinations of assignments of binding parameters will be calculated when the creation condition is affected from a change. For those bindings that fullfil the creation condition new goals are instantiated. The bound variables can be referenced in the creation condition directly via their name attribute.

Figure 7.2. The Jadex common goal features

The <unique> settings influence if a goal is adopted or ignored. When the unique tag is present, the agent does not adopt two equal instances of the goal at once. By default two goal instances of the same type are equal, when all parameters and parameter sets have the same values. Using the <exclude> tag this default behavior can be overriden by specifying which parameter(set)s should not be considered in the comparison. When a plan tries to adopt a goal that already exists and is declared as unique, a goal failure exception is thrown (see Section 8.2.1, “Plan Success or Failure and BDI Exceptions”.

To describe the situations in which a new goal of the declared user type will be automatically instantiated, the <creationcondition> may be used. For adopted goals, it can be specified under which conditions such a goal has to be suspended or dropped using the <contextcondition> and <dropcondition> respectively. The suspension of a goal means that all currently executing plans for that goal and all subgoals are terminated at once. If the suspension is cancelled, new means for achieving the goal will be inited. On the other hand, when a goal is dropped it is removed from the agent, and cannot be reactivated.

The <deliberation> settings, which influence which of the possible (i.e., not suspended) goals get pursued, will be explained in Section 7.7, “ Goal Deliberation with "Easy Deliberation" ”.

<achievegoal name="eat_food">
    <parameter name="$food" class="Food">
        <bindingoptions>$beliefbase.food</bindingoptions>
    </parameter>
    <unique/>
    <creationcondition>
         $beliefbase.eating_allowed
    </creationcondition>
    <deliberation>
        <inhibits ref="wander_around"/>
    </deliberation>
</achievegoal>

Perform goals are conceived to be used when certain activities have to be done. Below, an example declaration from the cleaner world example is shown. You can see that the perform goal "patrol" refines some BDI flags to obtain the desired behavior. By allowing the goal to redo activities (retry="true"), it is assured that the agent does not conclude to knock off after having performed one patrol round, but instead patrols as long as it is night and it does not need to recharge its battery as described in the context condition. Even when the agent only knows one patrol plan, it will reuse this plan and perform the same patrol rounds, because it is not allowed to exclude a plan (exclude="never"). Note that in the example the "&" entity is used to escape the AND character ( "&") in XML.

<performgoal name="patrol" retry="true" exclude="never">
    <contextcondition>
        !$beliefbase.is_loading &amp;&amp; !$beliefbase.daytime
    </contextcondition>
</performgoal>

Achieve goals are used to reach some desired world state. Therfore, they extend the presented common goal features by adding a <targetcondition> and a <failurecondition>. With the target condition it can be specified in what cases a goal can be considered as achieved, whereas the failure condition is useful to describe the opposite. Therefore the failure condition is very similar to the drop condition that can be found in all goal types. In contrast to the drop condition the final state of the achieve goal is guaranteed to be failed when the failure condition triggers. If target and failure condition are not specified, the results of the plan executions are used to decide if the goal is achieved. In contrast to a perform goal, an achieve goal without target condition is completed when the first plan completes without error, while the perform goal would continue to execute as long as more applicable plans are available. Below another goal specification from the cleaner world example is shown. The "moveto" goal tries to bring the agent to a target position as specified in the location parameter. The goal has been reached, when the agent's position is near the target position as described in the target condition.

<achievegoal name="moveto">
    <parameter name="location" class="Location"/>
    <targetcondition>
        $beliefbase.my_location.isNear($goal.location)
    </targetcondition>
</achievegoal>

Query goals can be used to retrieve specified information. From the specification and runtime behavior's point of view they are very similar to achieve goals with one exception. Query goals exhibit an implicit target condition by requesting all out parameters to have a value other than null and out parameter sets to contain at least one value. Therefore, a query goal automatically succeeds, when all out parameter(set)s contain a value. The agent will engage into actions by performing plans only, when the required information is not available. Below, the "query_wastebin" example realizes a query goal to find the nearest not full waste bin. It defines an out parameter, which contains a query expression. If one or more not full waste bins are already known by the agent and therefore contained in the wastebins belief set, the result will be set to the nearest waste bin calculated from the agent's current position (as described in the order by clause). Otherwise the agent does not know any not full waste bin and will try to reach the goal by using matching plans.

<querygoal name="query_wastebin" exclude="never">
    <parameter name="result" class="Wastebin" direction="out">
        <value evaluationmode="dynamic">
            select one $wastebin from $beliefbase.wastebins
            where !$wastebin.isFull()
            order by $beliefbase.my_location.getDistance($wastebin.getLocation())
        </value>
    </parameter>
</querygoal>

Maintain goals allow a specific state to be monitored and whenever this state gets violated, the goal has the purpose to reestablish its original maintain state. Hence it adds a mandatory <maintaincondition> tag for the specification of the state to observe. Sometimes it is desirable to be able to refine the maintain state for being able to define more accurately what state should be achieved on a violation of the maintained state. Therefore the optional <targetcondition> can be declared.

Note that maintain goals differ from the other kinds of goals in that they do not necessary lead to actions at once, but start processing automatically on demand. In addition, maintain goals are never finished according to actions or state, so the only possibility to get rid of a maintain goal, is to drop it either by specifying a drop condition or by dropping it from a plan.

The maintain goal "battery_loaded" shown below, makes sure that the cleaner agent recharges its battery whenever the charge state drops under 20%. To avoid the agent moving to the charging station and loading only until 21% (which satisfies the maintain condition), the extra target condition is used. It ensures that the agent stays loading until the battery is fully recharged. Note that in the example the ">" entity is used to escape the greater-than character (">") in XML.

<maintaingoal name="battery_loaded">
    <maintaincondition>
        $beliefbase.my_chargestate &gt; 0.2
    </maintaincondition>
    <targetcondition>
        $beliefbase.my_chargestate == 1.0
    </targetcondition>
</maintaingoal>

Jadex distinguishes between top-level goals and subgoals. Subgoals are created in the context of a plan, while top-level goals exist independently from any plans. When a plan terminates or is aborted, all its not yet finished subgoals are dropped automatically. There are four ways to create and dispatch new goals: Goals can be contained in the configuration of an agent or capability, and are directly created and dispatched as top-level goals when an agent is born or terminated (cf. Section 13.3, “Goals”). In addition, goals are automatically created and dispatched as top-level goals, when the goal's creation condition triggers. Subgoals may be created inside plans only, while top-level goals may be created manually from plans, as well as from external interactions (cf. Chapter 15, External Interactions).

When a plan wants to dispatch a subgoal or make the agent adopt a new top-level goal it also has to create an instance of some IMGoal. For convenience a method createGoal() is provided in jadex.runtime.AbstractPlan that automatically performs the necessary goal lookup for the model element of the new goal instance. The name therefore specifies the IMGoal to use as basis for the new IGoal.

A subgoal is dispatched as child of the root goal of the plan, and remains in the goal hierarchy until it is finished or aborted. To start processing of a subgoal, the plan has to dispatch the goal using the dispatchSubgoal() method. When the subgoal is finished (e.g., failed or succeeded), an appropriate goal event (type info) will be generated, which can be handled by the plan that created the subgoal. A dispatchSubgoalAndWait() method is provided in the Plan class, which dispatches the goal an waits until the goal is completed. Alternatively to subgoals, the plan can make the agent adopt a new top-level goal by using the dispatchTopLevelGoal() method. Further on, a plan may at any time decide to abort one of its subgoals or a top-level goal by using the drop() method of the goal. Note, that a goal cannot be dropped when it is already finished.

public void body() {
    // Create new top-level goal.
    IGoal goal1 = createGoal("mygoal");
    dispatchTopLevelGoal(goal1);
    ...
    // Create subgoal and wait for result.
    IGoal goal2 = createGoal("mygoal");
    IGoalEvent ge = dispatchSubgoalAndWait(goal2);
    ...
    // Drop top-level goal.
    goal1.drop();
}			

When dispatching and waiting for a subgoal from a standard plan, a goal failure will be indicated by a GoalFailureException being thrown. Normally, this exception need not be catched, because most plans depend on all of their subgoals to succeed. If the plan may provide alternatives to failed subgoals, you can use try/catch statements to recover from goal failures (see also Section 8.2.1, “Plan Success or Failure and BDI Exceptions”):

public void body() {
    ...
    // Goal failure will cause plan to fail.
    dispatchSubgoalAndWait(goal1);

    // Goal failure will not cause plan to fail.
    try {
        dispatchSubgoalAndWait(goal2);
    }
    catch(GoalFailureException e) {
        // Recover from goal failure.
        ...
    }
}			

One aspect of rational behavior is that agents can pursue multiple goals in parallel. Unlike other BDI systems, Jadex provides an architectural framework for deciding how goals interact and how an agent can autonomously decide which goals to pursue. This process is called goal deliberation, and is facilitated by the goal lifecycle (cf. Figure 2.2, “Goal Lifecycle”), which introduces the active, option, and suspended states. The context condition of a goal specifies which goals can possibly be pursued, and which goals have to be suspended. A goal deliberation strategy then has the task to choose among the possible (i.e., not suspended) goals by activating some of them, while leaving the others as options (for later processing).

The current release of Jadex includes a goal deliberation strategy called Easy Deliberation, which is designed to allow agent developers to specify the relationships between goals in an easy and intuitive manner. It is based on goal cardinalities, which restrict the number of goals of a given type that may be active at once, and goal inhibitions, which prohibit certain others goal to be pursued in parallel. More details and scientific background about the Easy Deliberation strategy and goal deliberation in general can be found in [Pokahr et al. 2005a].

The goal deliberation settings are included in the goal specification in the ADF Using the <deliberation> tag. The cardinality is specified as an integer value in the cardinality attribute of the <deliberation> tag. The default is to allow an unlimited number of goals of a type to be processed at once. Inhibition arcs between goal types are specified using the ref attribute of the <inhibits> tag, which specifies the name of the goal to inhibit. Per default, any instance of the inhibiting goal type inhibits any instance of the referenced goal type. An expression can be included as content of the inhibits tag, in which case the inhibition only takes effect when the expression evaluates to true. Using the expression variables $goal and $ref, fine-grained instance-level inhibition releationships may be specified. Some goals, such as idle maintain goals, might not alway be in conflict with other goals, therefore it is sometimes required to restrict the inhibition to only take effect when the goal is in process. This can be specified with the inhibit attribute of the <inhibits> tag, using "when_active" (default) or "when_in_process" as appropriate. For a better understanding of the goal deliberation mechanism in the following the deliberation settings of the cleanerworld example will be explained.

Figure 7.10, “Example goal dependencies (taken from Cleanerworld scenario)” shows the dependencies between the goals of a cleaner agent (cf. package jadex.examples.cleanerworld. The basic idea is that the cleaner agent (being an autonomous robot) has at daytime the task to look for waste in some environment and clean up the located pieces by bringing them to a near waste-bin. At night it should stop cleaning and instead patrol around to guard its environment. Additionally, it always has to monitor its battery state and reload it at a charging station when the energy level drops below some threshold.

Figure 7.10. Example goal dependencies (taken from Cleanerworld scenario)

The dependencies can be naturally mapped to the goal specifications in the ADF (see Figure 7.11, “Example goals (taken from Cleanerworld scenario)”). <inhibits> tags are used to specify that the “maintainbatteryloaded” goal is more important than the other goals. As the “maintainbatteryloaded” is a maintain goal, it only needs to precede the other goals when it is in process, i.e., the cleaner is currently recharging its battery. The cardinality of the “achievecleanup” goal specifies, that the agent should only pursue one cleanup goal at the same time. The goal inhibits the “performlookforwaste” goal and additionally introduces a runtime inhibition relationship to other goals of its type. The expression contained in the inhibits declaration means that one “achievecleanup” goal should inhibit other instances of the “achievecleanup” goal, when its waste location is nearer to the agent.

<maintaingoal name="maintainbatteryloaded">
    <!-- Omitted conditions for brevity. -->
    <deliberation>
        <inhibits ref="performlookforwaste" inhibit="when_in_process"/>
        <inhibits ref="achievecleanup" inhibit="when_in_process"/>
        <inhibits ref="performpatrol" inhibit="when_in_process"/>
    </deliberation>
</maintaingoal>

<achievegoal name="achievecleanup" retry="true" exclude="when_failed">
    <parameter name="waste" class="Waste" />
    <!-- Omitted conditions for brevity. -->
    <deliberation cardinality="1">
        <inhibits ref="performlookforwaste"/>
        <inhibits ref="achievecleanup">
            $beliefbase.my_location.getDistance($goal.waste.getLocation())
            &amp;lt; $beliefbase.my_location.getDistance($ref.waste.getLocation())
        </inhibits>
    </deliberation>
</achievegoal>

Meta Goals are used for meta-level reasoning. This means, whenever an event or goal is executed and it is determined that meta-level resoning needs to be done (i.e., because there are multiple matching plans) the corresponding meta-level goal of the goal or event is created and dispatched. Corresponding meta-level plans are then executed to achieve the meta goal (i.e., find a plan to execute). When the meta goal is finished the result contains the selected plans, which are afterwards scheduled for execution.

With the trigger tag, it is specified for which kind of event or goal the meta goal should be activated. Possible meta goal triggers are shown in Figure 7.12, “Meta goal trigger tag”. As can be seen, meta goals can be used to select among applicable plans for an internal event, message event, a goal finished event, and a new goal to process. Any number of these triggers can appear inside a meta goal specification, i.e., a meta goal can be used to control meta-level reasoning of more than one event type. Each triggering element can be further described using a match expression, which can be used, e.g., to match only elemens with given parameter values. For backwards compatibility it is also possible to specify the triggering events in form of a single filter expression. This should only be needed in very special cases and should otherwise be avoided, because support for filter expressions might be dropped in future releases of Jadex.

Figure 7.12. Meta goal trigger tag

Besides the declaration of a triggering goal or event, the specification of a meta goal requires including the in parameter set "applicables" and the out parameter set "result" (both of type jadex.runtime.ICandidateInfo). The applicables are filled in by the system, while the result is set by the meta-level plan executed to achieve the meta goal. Furthermore, a failure condition can specified (similar to query goals) as meta goals are also used for information retrieval (to find a plan to execute for a goal resp. event). Meta-goals are only created internally by the system when the demand for meta-level reasoning arises. Therefore, in contrast to the query goal and the other goal types presented here, meta-goals exhibit several restrictions, as for these kinds of goals creation condition, unique settings and binding parameters are not allowed. On the other hand, meta-plans do not differ from other plans (there is no a separate tag for meta plans). A plan is a meta plan, when its plan trigger contains a meta goal.

In the example below, adapted from the jadex.examples.puzzle example, for every “makemove” goal a large number of plan instances might be applicable, as the “move_plan” has a binding option which always contains all possible moves. Therefore, the “choosemove” meta goal is used to decide which of the applicable “move_plan” instances should be executed. In turn, handling the “choosemove” meta goal another plan is executed (“choose_move_plan”). As you can see in Figure 7.14, “Body of the ChooseMovePlan”, the “choose_move_plan” has access to the parameters of applicable plans and may use this informations to decide which plan(s) to execute. The selected plans are placed in the “result” parameter of the “choose_move_plan” goal.

<goals>
    <achievegoal name="makemove">
        ...
    </achievegoal>

    <metagoal name="choosemove">
        <parameterset name="applicables" class="ICandidateInfo"/>
        <parameterset name="result" class="ICandidateInfo" direction="out"/>
        <trigger>
            <goal ref="makemove"/>
        </trigger>
    </metagoal>
</goals>

<plans>
    <plan name="move_plan">
        <parameter name="move" class="Move">
            <bindingoptions>$beliefbase.board.getPossibleMoves()</bindingoptions>
        </parameter>
        ...
        <trigger>
            <goal ref="makemove"/>
        </trigger>
    </plan>
    
    <plan name="choose_move_plan">
        <parameterset name="applicables" class="ICandidateInfo">
            <goalmapping ref="choosemove.applicables"/>
        </parameterset>
        <parameterset name="result" class="ICandidateInfo" direction="out">
            <goalmapping ref="choosemove.result"/>
        </parameterset>
        <body>new ChooseMovePlan()</body>
        <trigger>
            <goal ref="choosemove"/>
        </trigger>
    </plan>
</plans>

public void body()
{
    ICandidateInfo[] apps = (ICandidateInfo[])getParameterSet("applicables").getValues();

    ICandidateInfo sel = null;
    
    for(int i=0; i<apps.length; i++)
    {
        // Decide which plan to select, e.g. using the move parameter of the move_plan.
        Move move = (Move)apps[i].getPlan().getParameter("move").getValue();
        ...
    }

    getParameterSet("result").addValue(sel);
}

Figure 8.1. The Jadex plans XML schema part

In Figure 8.1, “The Jadex plans XML schema part” the XML schema part for the plans section is shown. Inside the <plans> tag an arbitrary number of plan heads denoted by the <plan> tag can be declared. For each plan head several attributes (as shown in Table Table 8.1, “Important attributes of the plan and the body tag”) and contained elements can be defined. For each plan a name has to be provided. The priority of a plan describes its preference in comparison to other plans. Therefore it is used to determine which candidate plan will be chosen for a certain event occurence, favouring higher priority plans (random selection, if activated, applies only to plans of equal priority). Per default all applicable plans have a default priority of 0 and are selected in order of appearance (or randomly when the corresponding BDI flag is set).

For each plan the corresponding plan body has to be declared using the <body> element. Within this element a Java expression has to be provided for the creation of the plan body (in most cases a simple constructor call like new PingPlan() is used). The type attribute determines which kind of plan body is used. Currently, the options are standard vs. mobile plan bodies as further described in Section 8.2, “Implementing a Plan Body in Java”. To clarify things, a simple example ADF is given below that shows the declaration of a plan reacting on a ping message.

<agent ...>
    ...
    <plans>
        <plan name="ping">
            <body>new PingPlan()</body>
            <trigger>
                <messageevent ref="query_ping"/>
            </trigger>
        </plan>
    </plans>
    ...
    <events>
        <messageevent name="query_ping" type="fipa">
            ...
        </messageevent>
    </events>
    ...
</agent>

8.1.1. Plan Triggers

To indicate in what cases a plan is applicable and a new plan instance shall be created the <trigger> tag can be used (see Figure 8.3, “The Jadex plan trigger XML schema part”). Its subtags specify the internal-, message, or goal events for which the plan is applicable. For goals, it is distinguished between plans triggered for handling a goal (<goal> tag) and plans reacting on the completion of a goal (<goalfinished> tag). The <goal> tag indicates that a goal has been newly activated, while the <goalfinished> tag corresponds to a goal that has been dropped. These events or goals can be further restricted, by specifying a match expression. When a match expression is included in the trigger element, the plan will only be selected for those goal or event instances, for which the expression evaluates to true. For backwards compatibility to older Jadex versions, additionally, a filter instance can be used, although its use is discouraged, because of the lack of declarativeness and readability.

Figure 8.3. The Jadex plan trigger XML schema part

In addition to the reaction on certain event or goal types, it is also possible to define data-driven plan execution by using the <condition> tag. A trigger condition can consist of arbitrary boolean Jadex expressions, which may refer to certain beliefs when their states needs to be supervised. If only some specific belief needs to be monitored the <beliefchange> tag can be used. In this respect a belief change is reported whenever the belief's new fact value is different from the value held before. Similarly, belief sets can be monitored with the <beliefsetchange> tag, or more specifically for addition or removal of facts by using the tags <factadded> and <factremoved> respectively.

<plans>
    <plan name="repair">
        <body> new RepairPlan() </body>
        <trigger>
            <condition> $beliefbase.out_of_order </condition>
        </trigger>
        <contextcondition> $beliefbase.repairable </contextcondition>
    </plan>
</plans>

8.1.4. Parameters, Binding, and Parameter Mapping

Similar to goals, plans may have parameters and parameter sets, which can store local values, required or produced during the execution of the plan. Plan parameters can be accessed from plan bodies for read and write access depending on the parameter direction attribute: in parameters (cf. Section 7.1, “Common Goal Features”) allow only read access, out parameters can only be written, while inout parameters allow both kinds of access. Default values for any of these parameters and parameter sets can be provided in the ADF. Just like facts for belief sets, initial values for parameter sets can be either specified as a sequence of <value> tags, or as a single <values> tag. The parameter(set)s of a plan can also be accessed from the body tag or the context condition, by referencing the plan via the reserved variable $plan concatenated with the parameter(set) name, e.g. $plan.result. The precondition and the trigger condition are evaluated before the plan is instantiated, therefore from these conditions no parameters and parameter sets can be accessed with exception of the binding parameters. As binding parameters are evaluated before plan instantiation the value of a binding parameter can be accessed directly via its name (without prepending $plan).

Figure 8.5. The Jadex plan parameters XML schema part

For (single valued) parameters it is possible to use binding options instead of an initial value. A binding option is an expression, that will be evaluated to a collection of values (supported are arrays or an object implementing Iterator, Enumeration, Collection, or Map). The binding options of a parameter therefore represent a set of possible initial values for that parameter. The cartesian product ^[1] of all binding parameters (if there is more than one parameter with binding otpions) determines the number of candidate plans that is considered in the event dispatching process. Please note that the calculation of the cartesian product can easily lead to large numbers of applicable plans so that binding options should always be used with care. For example Figure 8.6, “ Example binding parameter (from the puzzle example) Example binding parameter ” shows a plan from the “puzzle” example, where for each possible move a plan instance is created. In addition to accessing the binding values like other parameters by writing $plan.paramname, it is also possible to access the binding value directly via its name via paramname. This allows binding values also to be considered for evaluating the pre- and trigger condition, before the plan instance is created.

<plan name="move_plan">
    <parameter name="move" class="Move">
        <bindingoptions>$beliefbase.board.getPossibleMoves()</bindingoptions>
    </parameter>
    ...
</plan>

Figure 8.6.  Example binding parameter (from the puzzle example) Example binding parameter

A common use case for plan parameter(set)s is to capture parameter(set)s from a goal or event that triggered the plan. To make this relationship between event and plan parameters explicit, the <internaleventmapping>, <messageeventmapping>, and <goalmapping> tags can be used. A mapping definition contains a ref attribute denoting the event or goal parameter to be mapped. The reference is given in the form type.param, where type is the name of the goal or event, and param is the name of the goal or event parameter. When a plan parameter is mapped, the parameter properties like class and direction are ignored, as the values from the mapped parameter are used. Depending on the direction of the parameter, the default values of the plan parameter are automatically assigned from the event or goal (direction in, inout), and can also automatically be written back to a goal (direction out, inout), when the plan has finished. Note that when a plan reacts to more than one goal or event, you cannot just provide a mapping for one of these events. If you want to use a mapping for a parameter, you have to provide mappings for all events or goals handled by the plan.

A plan body represents a part of the agent's functionality and encapsulates a recipe of actions. In Jadex, plan bodies are written in pure Java and therfore it is easily possible to write plans that access any available Java libraries, and to develop plans in your favourite Java Integrated Development Environment (IDE). The connection between a plan body and a plan head is established in the plan head, thus plan bodies can be reused within different plan declarations. For developing reusable plans, plan parameters in combination with parameter mappings from some triggering event or goal to/from the plan should be used.

As mentioned earlier, currently two types of plan bodies are supported in Jadex, which are both implemented as conventional Java classes. The standard plans inherit from jadex.runtime.Plan. The mobile plans inherit from jadex.runtime.MobilePlan and allow agents to be migrating, even while plans are executing (e.g., supported by the JADE platform). The code of standard plans is placed in the body() method, while the code of mobile plans goes into the action(IEvent) method.

Plans that are ready to run are executed by the main interpreter (cf. Section 2.3, “Execution Model of a Jadex Agent”). The system takes care that only one plan step is running at a time. The length of a plan step depends on the plan itself. For mobile plans the action() method is always executed as a whole, for the first and again for all subsequent steps. The body() method of standard plans is called only once for the first step, and runs until the plan explicitly ends its step by calling one of the waitFor() methods, or the execution of the plan triggers a condition (e.g., by changing belief values). For subsequent steps the body() method is continued, where the plan was interrupted.

The API of both plan types is very similar (both inherit from the same super class jadex.runtime.AbstractPlan), the only difference regards the waiting for events. Both plans provide several variations of the waitFor...() method, but only the standard plan will block when it is called. The different execution style is shown in a code example implementing the initiator side of a FIPA-request protocol. Remember, the body() method of a standard plan is called only once, while the action() method of a mobile plan is called for each event. The standard plan can use nested if-then-else blocks to naturally handle all cases of the protocol, while the mobile plan has no state information of previous messages, and has to handle all events at the top level of the action() method in one large if-then-else statement.

public void body() {
    // Send request.
    ...
    
    // Wait for agree/refuse.
    IEvent e1 = waitFor(...);
    boolean agreed = ...;    
    ...
    
    // Wait for inform/failure.
    if(agreed) {
        IEvent e2 = waitFor(...);
        boolean informed = ...;
    
        ...
        if(informed) {
            ...
        }
        else {
            ...
        }
    }
    else {
        ...
    }
}

public void action(IEvent e) {
    boolean agreed, refused;
    boolean informed, failed;
    ...
    if(initial_event) {
        // Send request.
        ...
        // Wait for agree/refuse.
        waitFor(...);
    }
    else if(agreed) {
        ...
        // Wait for inform/failure.
        waitFor(...);
    }
    else if(refused) {
        ...
    }
    else if(informed) {
        ...
    }
    else if(failed) {
        ...
    }
}

public class MyPlan extends Plan {

    public void body() {
        // Application code goes here.
        ...
    }

    public void passed() {
        // Clean-up code for plan success.
        ...
    }

    public void failed() {
        // Clean-up code for plan failure.
        ...
        getException().printStackTrace();
    }

    public void aborted() {
        // Clean-up code for an aborted plan.
        ...
        System.out.println("Goal achieved? "+isAbortedOnSuccess());
    }
}

public void body() {
    ...
    startAtomic();    
    // Atomic code goes here.
    ...    
    endAtomic();
    ...
}

Internal events are the typical way in Jadex for explicit one-way communication of an interesting occurrence inside the agent. The usage of internal events is characterized by the fact that an information should be passed from a source to some consumers (similar to the object oriented observer pattern). Hence, if an internal event occurs within the system, e.g., because some plan dispatches one, it is distributed to all plans that have declared their interest in this kind of event by using a corresponding trigger or by waiting for this kind of internal event. The internal event can transport arbitrary information to the consumers if custom parameter(set)s are defined in the type for that purpose. A typical use case for resorting to internal events is, e.g., updating a GUI.

<!-- ADF snippet showing the internal event declaration. -->
...
<events>
    <!-- Specifies an internal event for updating the gui.-->
    <internalevent name="gui_update">
        <parameter name="content" class="String"/>
    </internalevent>
</events>
...

// Plan snippet showing the creation and dispatching of the internal event.
...
public void body() {
    String update_info;
    ...
    // "gui_update" internal event type must be defined in the ADF
    IInternalEvent event = createInternalEvent("gui_update");
    // Setting the content parameter to the update info
    event.getParameter("content").setValue(update_info);
    dispatchInternalEvent(event);
    ...
}

In addition to user-defined internal events there are also some already predefined internal events used by the Jadex system itself. In Table 9.2, “Predefined Internal Event Types” these types are explained shortly. They should not be of much importance for most agent developers. Only, if you intend to write mobile plans you may need to know them, because they will be passed to the plan body's action method (information about mobile plans can be found in Section 8.2, “Implementing a Plan Body in Java”)

All message types an agent wants to send or receive need to be specified within the ADF. The message event (class jadex.runtime.IMessageEvent) denotes the arrival or sending of a message. The direction of the message (arrived or to be sent) can be checked with the isIncoming() method. Note, that only incoming messages are handled by the event dispatching mechanism, while outgoing messages are just sent. The native underlying message object (which is platform dependent) can be retrieved using the getMessage() method. In addition, the message content, which may be a String or some content object, can be retrieved using the getContent() method.

The message passing mechanism is based on using jadex.adapter.fipa.AgentIdentifiers for the unambiguous identification of agents. An agent identifier hence contains an agents globally unique name which consists of a local part followed by the "@" character and the platforms name (schema: <agentname>@<platformname>, example: ams@lars). In addition to the name an agent identifier can contain additional information. On the one hand arbitrary many transport addresses might be present. These addresses can be used to contact the agent from a remote platform and normally represent the address of platform wide transport mechanisms (schema: <transportname>://<address>, example: nio-mtp://mypc18:9876). Besides the transport addresses also so called resolvers can be part of an agent identifier. An agent resolver is itself another agent identifier which can be used for name resolution, i.e. if an agent wishes to send a message to another agent and wants to fetch up-to-date transport addresses of the receiving agent it can query the resolver(s) for additional transport addresses. Please refer to the FIPA Agent Management Specification. An agent identifier of another agent can be obtained in two ways. If all details about the agent are known an agent identifier can directly be created using a local or global name. E.g., new AgentIdentifier("Heinz", true) would create an identifier to contact agent "Heinz" on the local platform. If the details of an agent are not known in advance, an agent may search for other agents using either the AMS listing all agents on a platform or the DF, which allows to search for agents providing a given service. Searching AMS and DF is explained in detail in Chapter 16, Using Predefined Capabilities

Templates for message events are defined in the ADF in the <events> section. The direction attribute can be used to declare whether the agent wants to receive, send or do both (default) for a given event. Possible values for that attribute are "send", "receive" and "send_receive" respectively. The type of the message constrains the available parameters of a message. Currently, the only available type is "fipa" which automatically creates parameter(set)s according to the FIPA message specification (e.g., parameters for the receivers, content, sender, etc. are introduced). Through this message typing Jadex does not require that only FIPA messages are being sent, as other options may be added in future. In the following Table 9.3, “Reserved FIPA message event parameters”, all available parameter(set)s are itemized. For details about the meaning of the FIPA parameters, see the FIPA specifications available at FIPA ACL Message Structure Specification. In addition to the FIPA parameters, Jadex introduces the content-start, content-class, and action-class parameters. The meanings of all of these parameters are explained in the following subsections.

<imports>
    <import>jadex.adapter.fipa.SFipa</import>
</imports>
...
<events>
    <!-- A query-ref message with content "ping" -->
    <messageevent name="query_ping" type="fipa" direction="receive">
        <parameter name="performative" class="String" direction="fixed">
            <value>SFipa.QUERY_REF</value>
        </parameter>
        <parameter name="content" class="String" direction="fixed">
            <value>"ping"</value>
        </parameter>
    </messageevent>
    
    <!-- An inform message where content contains the word "hello" -->
    <messageevent name="inform_hello" type="fipa" direction="receive">
        <parameter name="performative" class="String" direction="fixed">
            <value>SFipa.INFORM</value>
        </parameter>
        <match>((String)$content).indexOf("hello")!=-1</match>
    </messageevent>
</events>

<imports>
    <import>jadex.adapter.fipa.SFipa</import>
</imports>
...
<events>
    <!-- A query-ref message with content "ping" -->
    <messageevent name="query_ping" type="fipa" direction="send">
        <parameter name="performative" class="String">
            <value>SFipa.QUERY_REF</value>
        </parameter>
        <parameter name="content" class="String">
            <value>"ping"</value>
        </parameter>
    </messageevent>
</events>

// Plan snippet showing the creation and sending of the message.
public void body() {
    IMessageEvent me = createMessageEvent("query_ref");
    me.getParameterSet(SFipa.RECEIVERS).addValue(new AgentIdentifier("Ping", true));
    // me.setContent("ping 2"); // Set/change content if necessary
    sendMessage(me);
}

<!-- Message declaration in the ADF -->
<messageevent name="inform_target" type="fipa" direction="send">
    <parameter name="performative" class="String" direction="fixed">
        <value>SFipa.INFORM</value>
    </parameter>
    <parameter name="language" class="String" direction="fixed">
        <value>SFipa.NUGGETS_XML</value>
    </parameter>
    <parameter name="ontology" class="String" direction="fixed">
        <value>MarsOntology.ONTOLOGY_NAME</value>
    </parameter>
</messageevent>

public void body() {
    // Message sending in the plan.
    AgentIdentifier receiver = ...
    Target target = ...
    IMessageEvent me = createMessageEvent("inform_target");
    me.getParameterSet(SFipa.RECEIVERS).addValue(receiver);
    me.setContent(target); // The Java object is directly used as content.
    sendMessage(me);
}

<!-- Message declaration in the ADF -->
<messageevent name="target_inform" type="fipa" direction="receive">
    <parameter name="performative" class="String" direction="fixed">
        <value>SFipa.INFORM</value>
    </parameter>
    <parameter name="content-class" class="Class" direction="fixed">
        <value>Target.class</value>
    </parameter>
    <parameter name="ontology" class="String" direction="fixed">
        <value>MarsOntology.ONTOLOGY_NAME</value>
    </parameter>
</messageevent>

public void body() {
    // Message receiving in the plan.
    IMessageEvent msg = (IMessageEvent)getInitialEvent();
    Target target = (Target)msg.getContent();
    ...
}

<properties>
    <property name="contentcodec.my_codec">new MyContentCodec()</property>
</properties>

<events>
    <messageevent name="request" type="fipa" direction="send">
        <parameter name="performative" class="String">
            <value>SFipa.REQUEST</value>
        </parameter>
        <parameter name="conversation-id" class="String">
            <value>SFipa.createUniqueId($scope.getAgentName())</value>
        </parameter>
    </messageevent>
    <messageevent name="inform" type="fipa" direction="receive">
        <parameter name="performative" class="String" direction="fixed">
            <value>SFipa.INFORM</value>
        </parameter>
    </messageevent>
<events>

public void body() {
    IMessageEvent me = createMessageEvent("request");
    ... // Set other parameters as desired
    IMessageEvent reply = sendMessageAndWait(me);
    ... // Handle reply message
}

<events>
    <messageevent name="request" type="fipa" direction="receive">
        <parameter name="performative" class="String" direction="fixed">
            <value>SFipa.REQUEST</value>
        </parameter>
    </messageevent>
    <messageevent name="inform" type="fipa" direction="send">
        <parameter name="performative" class="String">
            <value>SFipa.INFORM</value>
        </parameter>
    </messageevent>
<events>

public void body() {
    // Message receiving in the plan.
    IMessageEvent msg = (IMessageEvent)getInitialEvent();
    Object content = ... // Prepare content for reply
    IMessageEvent reply = msg.createReply("inform", content);
    sendMessage(reply); // Take care to send 'reply' and not 'msg'!
}

Besides internal and message events, there is a third kind of event in Jadex, that is sometimes of interest to an agent developer. So called goal events (IGoalEvent) are used to manage the processing of goals. For standard plans, goal events can usually be ignored, but when developing mobile plans, the results of goal processing are passed as goal events to the action() method of the plan. Therefore, understanding goal events is quite important, if you want to develop mobile plans.

Goal events are not declared in the ADF, as they are used only internally for the processing of goals. This means that the agent will automatically create a goal event in response to an active goal it wants to perform (process event) and for a goal that finished its processing (info event). To explicitly decide which kind of event has happened (as commonly necessary inside mobile plans) the IGoalEvent.isInfo() method can be used. Below, an excerpt of the PickUpWastePlan from the cleanerworld mobile example is shown to illustrate the usage of goal events. In contrast to standard plans a mobile plan will be always be invoked through calling its action() method regardless of the state of that plan. Hence the programmer has to supply case distinction for the different plan steps and can use the event provided parameter for this decision. In the example in the first step a moveto subgoal is dispatched and in the second step (when the position has been reached) the desired clean-up operation can be performed.

public void action(IEvent event)
{
    Waste waste = (Waste)getParameter("waste").getValue();

    // First event is a process event (=!isInfo)
    if(event instanceof IGoalEvent && !((IGoalEvent)event).isInfo())
    {
        IGoal moveto = createGoal("achievemoveto");
        moveto.getParameter("location").setValue(waste.getLocation());
        dispatchSubgoalAndWait(moveto);
    }

    // Second event is info event from achievemoveto goal dispatched above.
    else if(event instanceof IGoalEvent
        && ((IGoalEvent)event).getGoal().getType().equals("achievemoveto"))
    {
       ...
    }
}

The expression language follows a Java-like syntax. In general, all of the operators of the Java language are supported (with the exception of assignment operators), while no other constructs can be used. Operators are, for example, math operators (+-*/%), logical operators (&&, ||, !), and method, or constructor invocations. Other unsupported constructs are loops, class declarations, variable declarations, if-then-else blocks, etc. As a rule you can use every Java code that can be contained in the right hand side of a variable assignment (e.g., var = <expression>). There are just two exceptions to this rule: Declarations of anonymous inner classes are not supported. Assignment operators (=, +=, *=...) as well as de- and increment operators (++, --) are not allowed, because they would violate declarativeness.

In addition to the Java-like syntax, the language has some extensions: Parameters give access to specific elements depending on the context of the expression. OQL-like select statements allow to create complex queries, e.g., for querying the beliefbase. To simplify the Java statements in the expressions, imports can be declared in the ADF (see Chapter 4, Imports) that allow to use unqualified class names. The imports are defined once, and can be used for all expressions throughout the ADF.

Expressions have properties which can be specified as attributes of the enclosing XML tag. The optional class attribute can be specified for any expression, and is used for cross checking the expression string against the expected return type. This allows to detect errors in the ADF already at load time, which could otherwise only be reported at runtime. The evaluation mode influences when and how often the expression is evaluated at runtime. A "static" expression caches the value once the expression created, while the value of a "dynamic" expression is reevaluated for ervery access. The default values of these properties depend on the context in which the expression is used. E.g. initial facts of beliefs are usually static, while conditions are dynamic.

Expressions that are derived from other elements as well as traced conditions (see below) need to know, which changes inside the agent affect the value of the expression. For example, an expression referring to a belief would have to be updated, when the belief has changed. The expression parser is able to autodetect most of these dependencies: References of belief(set)s, to goal parameters, and to the content of the goalbase (e.g., to react to the addition or removal of a goal). But sometimes you may want to react to changes that cannot be detected automatically. The <relevant...> tags (see Figure 10.1, “The Jadex expressions relevant settings XML schema part”) allow to specify an arbitrary number of elements on which an expression depends. These tags require the specification of a reference to an element, i.e., a belief(set), goal, or parameter(set) by using the "ref" attribute. Parameter references take the form "goalname.parametername" unless the goal can be determined from the expression context (e.g., in a goal condition). In this case and for the other references, the name of the element suffices. Optionally, a system event type can be given (see interface jadex.model.ISystemEventTypes for available event types) to further restrict the dependency to only specific changes, such as BSFACT_ADDED using the "eventtype" attribute.

Figure 10.1. The Jadex expressions relevant settings XML schema part

In Figure 10.2, “Example expressions”, two example expressions are shown. Here the expressions are used to specifiy the facts of some beliefs. In fact there are many places besides beliefs in the ADF where expressions can be used. In the first case, the "starttime" fact expression is evaluated only once when the agent is born. The second belief represents the agent's lifetime and is recalculated on every access.

<belief name="starttime" class="long">
    <fact>
        System.currentTimeMillis()
    </fact>
</belief>
    
<belief name="lifetime" class="long">
    <fact evaluationmode="dynamic">
        System.currentTimeMillis() - $beliefbase.starttime
    </fact>
</belief>

The expression language cannot only be used to specify values for beliefs, plans, etc. in the ADF but also for dynamic evaluation, e.g., to perform queries on the state of the agent, most notably the current beliefs. Expressions (jadex.runtime.IExpression) can be created at runtime by providing an expression string. A better way is to predefine expressions in the ADF in the expression base (see Figure 10.3, “The Jadex expressions XML schema part”). Because predefined expressions only have to be parsed and precompiled once and can be reused by different plans, they are more efficient. The following example shows a predefined expression for searching the beliefbase for a certain person contained in the belief persons, using the OQL-like language extension described in more detail below. Moreover, this example uses a custom parameter $surname to specify which person to retrieve from the belief set.

Figure 10.3. The Jadex expressions XML schema part

Primary usage of predefined expression is to perform queries, when executing plans. The getExpression(String name) method creates an expression object based on the predefined expression with the given name. In addition, the createExpression(String exp [, String[] paramnames, Class[] paramtypes]) method is used to create an expression directly by parsing the expression string (without referring to a predefined expression). Custom parameters can be optionally be defined for such queries by additionally providing the parameter names and classes. Values for these parameters have to be supplied when executing the query. The expression object provides several execute() methods to evaluate a query specifying either no parameters, a single parameter as name/value pair, or a set of parameters that are defined as a String and an Objectarray containing parameter names and values separately. You can also pre-set parameters before executing the query using the setParameter() method. For example, one can execute the person query with a given surname.

<agent ...>
    ...
    <expressions>
        <expression name="find_person" class="Person">
            select one Person $person
            from $person in $beliefbase.persons
            where $person.getSurname().equals($surname)
            
            <parameter name="$surname" class="String"/>
        </expression>
        ...
    </expressions>
    ...
</agent>

public void body {
    IExpression query = getExpression("find_person");
    ...
    Person person = (Person)query.execute("$surname", "Miller");
    ...
}

Jadex provides an OQL-like query syntax, which can be used in conjunction with any other expression statements. OQL (Object-Query-Language) is an extension of SQL (Structured-Query-Language) for object-oriented databases. The generic query syntax as supported by Jadex is very similar to OQL (note that until now only select statements are supported). The syntax is shown in Figure 10.6, “Syntax of OQL-like select statements”.

select (one)? <class>? <result-expression>
from (<class>? <element> in)? <collection-expression>
    (, <class>? <element> in <collection-expression>)*
(where <where-expression>)?
(order by <ordering-expression> (asc | desc)? )?

Unlike OQL and SQL, the keywords (select etc.) are currently case sensitive and have to be written in lower case. The <collection-expression> has to evaluate to an object that can be iterated (an array or an object implementing Iterator, Enumeration, Collection, or Map). In the other expressions (result, where, ordering) the query variables can be accessed using <element>. When using "<element>" as result expression, the second "<element> in" part can be omitted for readability. While you are free to use any expression for the result and the ordering, the where clause, of course, has to evaluate to a boolean value.

Some simple example queries (assuming that the beliefbase contains a belief set "persons", where each person has attributes "forename", "surname", "age", and "address") are shown in Figure 10.7, “Examples of OQL-like select statements”. The first query returns a java.util.List of all persons in the order they are contained in the belief set. The second query only returns persons that are older than 21. In this case a cast is used to invoke the getAge() method. The third example orders the returned list by the addresses of the persons, using a type declaration at the beginning of the query, and therefore does not need a cast for accessing the getAddress() method. The order-by implementation relies on the java.lang.Comparable interface. In the example, the addresses have to be comparable for the query to work. The next query shows that it is possible to use complex expressions to create the result elements. Note, that in this case, the "$person in" part cannot be ommited. The last example shows how to do a join. The expression returns a list of strings of any two (distinct) persons, which have the same address.

select $person from $beliefbase.persons

select $person from $beliefbase.persons where ((Person)$person).getAge()>21

select Person $person from $beliefbase.persons order by $person.getAddress()

select $person.getSurname()+", "+$person.getForename()
from Person $person in $beliefbase.persons

select $p1+", "+$p2 from Person $p1 in $beliefbase.persons,
                         Person $p2 in $beliefbase.persons
where $p1!=$p2 && $p1.getAddress().equals($p2.getAddress())

An extension to OQL is the support of the "one" keyword. The default (without "one") is standard OQL semantics to return all objects matching the query. The "one" keyword is used to select a single element. For queries without ordering, this returns the first found element that matches the query. When using ordering, the query is evaluated for all input elements and returns the first element after having applied the ordering. In both cases null is returned, when no element matches the query. Without the "one" keyword, an empty collection is returned, when no element matches the query.

Figure 11.1. The Jadex conditions XML schema part

When programming plans, it is also possible to explicitly wait for certain conditions using the waitForCondition(ICondition cond) method. Conditions are obtained in a similar fashion to expressions, either by instantiating a predefined condition from the ADF (see Figure 11.1, “The Jadex conditions XML schema part”), or by creating a new condition from an expression string. When waiting for a condition, the plan will be blocked until the condition triggers, which by default means that its value changes to true. The condition is monitored automatically by the agent, by considering all internal state changes that may affect the condition value, e.g., when some other plan changes a belief. The following example uses the "timer" belief from Section 6.3, “Dynamically Evaluated Beliefs” to execute some action when the alarmtime has reached (belief not shown here).

<agent ...>
    ...
    <expressions>
        <condition name="alarmtime_reached">
            $beliefbase.timer >= $beliefbase.alarmtime
        </condition>
        ...
    </expressions>
    ...
</agent>

public void body {
    ICondition condition = getCondition("alarmtime_reached");
    ...
    // Wakeup every full hour.
    IEvent event = waitForCondition(condition);
    ...
}

The <capabilities> tag allows to configure included capabilities. For this purpose a reference to an included <initialcapability> must be declared. The reference to the capability is established by setting the ref attribute to the symbolic name of the capability specified within the <capabilities> section of the agent/capability (i.e., not the type name but the instance name). The configuration to be used by the included capability can be set by using the configuration attribute of the initial capability tag.

Figure 13.2. The Jadex initial capabilities XML schema part

In Figure 13.3, “Initial capability configuration” an example is shown how the initial state can be used to declare two different initial states. In state "one" the included capability "mycap" is configured to use its initial state "a", while in state "two" "b" is used. Per default the agent would start using initial state "two" as it is declared as default.

<agent ...>
    ...
    <capabilities>
        <capability name="mycap" file="SomeCapability"/>
    </capabilities>
    ...
    <configurations default="two">
        <configuration name="one">
            <capabilities>
                <initialcapability ref="mycap" configuration="a"/>
            </capabilities>
        </configuration>
        <configuration name="two">
            <capabilities>
                <initialcapability ref="mycap" configuration="b"/>
            </capabilities>
        </configuration>
    </configurations>
</agent>

In the <beliefs> section the initial facts of beliefs and belief sets can be altered or newly introduced. In order to set the initial fact(s) of a belief or belief set an <initialbelief> resp. an <initialbelief set> tag should be used. The connection to the "real" belief is again established via the ref attribute and the facts can be declared in the same way as default values of beliefs and belief sets. The initial state does not distinguish between original beliefs and references to beliefs from other capabilities, therefore the same tags can also be used to change initial facts of belief references and belief set references as well.

Figure 13.4. The Jadex initial beliefs XML schema part

The example in Figure 13.5, “Initial belief configuration” shows how a configuration can be used to change belief facts. Belief "name" has a default value of "Jim" which is overridden by the initial belief fact "John". The belief set "names" has no default values. In the initial state it is filled with some data from a database. This means that for all results that the method DB.queryNames() produces, a new fact is added to the belief set.

<agent ...>
    ...
    <beliefs>
        <belief name="name" class="String">
            <fact>"Jim"</fact>
        </belief>
        <beliefset name="names" class="String"/>
    </beliefs>
    ...
    <configurations>
        <configuration name="one">
            <beliefs>
                <initialbelief ref="name">
                    <fact>"John"</fact>
                </initialbelief>
                <initialbelief set ref="names">
                    <facts>DB.queryNames()</facts>
                </initialbelief set>
            </beliefs>
        </configuration>
    </configurations>
</agent>

In the <goals> section initial and end goals can be specified. Initial goals will be instantiated when an agent is born whereas end goals are created when an agent is beginning the termination phase. This means that a new goal instance is created for each declared initial resp. end goal at the mentioned points in time. The specification of an <initialgoal> and an <endgoal> requires the connection to the underlying goal template which is used for instantiation. For this purpose the ref attribute is used. Optionally, further parameter(set) values can be declared by using the corresponding <parameter> and <parameterset> tags.

Figure 13.6. The Jadex initial and end goals XML schema part

In Figure 13.7, “Initial and end goals” an example is depicted how an initial and end goal can be created. Both, the initial and end goal refer to the declared "play_song" perform goal of the agent and provides a new parameter value for the song parameter. When the agent is started in this initial state it creates the initial goal and pursues it. So, given that the agent has some plan to play an mp3 file, it will play a welcome song in this example. On the other hand the agent will also play a good bye jingle when it is terminated by creating the corresponding end goal.

<agent ...>
    ...
    <goals>
        <performgoal name="play_song">
            <parameter name="song" class="URL"/>
        </performgoal>
    </goals>
    ...
    <configurations>
        <configuration name="one">
            <goals>
                <initialgoal name="welcome" ref="play_song">
                    <parameter ref="song">
                        <value>new URL("http://someserver/welcome.mp3")</value>
                    </parameter>
                </initialgoal>
                <endgoal name="goodbye" ref="play_song">
                    <parameter ref="song">
                        <value>new URL("http://someserver/goodbye.mp3")</value>
                    </parameter>
                </endgoal>
            </goals>
        </configuration>
    </configurations>
</agent>

In the <plans> section initial and end plans can be specified. This means that a new plan instance is created for each declared initial and end plan. The specification of an <initialplan> and <endplan> requires the connection to the underlying plan template which is used for instantiation. For this purpose the ref attribute is used. Optionally, further parameter(set) values can be declared by using the corresponding <parameter> and <parameterset> tags.

Figure 13.8. The Jadex initial and end plans XML schema part

In Figure 13.9, “Initial and end plans” an example is depicted how an initial and end plan can be used. In this case an initial "print_hello" plan is declared which refers to the "print_hello" plan template of the agent. As result the agent will print "Hello World!" to the console on start-up. On the contrary it will also print "Goodbye World" when the agent gets terminated by creating the corresponding end plan.

<agent ...>
    ...
    <plans>
        <plan name="print_plan">
            <parameter name="text" class="String"/>
            <body class="PrintOnConsolePlan" />
        </plan>
    </plans>
    ...
    <configurations>
        <configuration name="one">
            <plans>
                <initialplan ref="print_hello">
                	<parameter name="text">"Hello World!"</parameter>
                </initialplan>
                <endplan ref="print_goodbye">
                	<paramter name="text">"Goodbye World!"</parameter>
                </endplan>
            </plans>
        </configuration>
    </configurations>
</agent>

Finally, in the <events> section initial and end events can be specified. This means that a new event instance is created for each declared initial event after startup of the agent. Additionally, new event instances are created for all declared end events whenever the agent is shutdowned. It is possible to define initial/end internal and initial/end message events (goal events are not necessary as initial goals can be declared). The specification of an <initialinternalevent> resp. an <endinternalevent> or an <initialmessageevent> resp. an <endmessageevent> requires the connection to the underlying event template which is used for instantiation. For this purpose the ref attribute is used. Optionally, further parameter(set) values can be declared by using the corresponding <parameter> and <parameterset> tags.

Figure 13.10. The Jadex initial and end events XML schema part

In Figure 13.11, “Initial events” an example is shown how an initial and end message event can be created. The intial/end message events refer to the underlying message event template "inform_state" and set the parameter values for the content as well as for the receiver accordingly. When an agent named "Harry" is started, it sends an initial message event with the content "Harry is born" to an agent named "Uncle" on the same platform. Likewise it sends the message "Harry is terminating" to "Uncle" when the agent shuts down.

<events>
    <messageevent name="inform_state" type="fipa" direction="send">
        <parameter name="performative" class="String" direction="fixed">
            <value>SFipa.INFORM</value>
        </parameter>
    </messageevent>
</events>
...
<configurations>
    <configuration name="one">
        <events>
            <initialmessageevent ref="inform_state">
                <parameter ref="content">
                    <value>$agent.getAgentName()+" is born."</value>
                </parameter>
                <parameterset ref="receivers">
                    <value>new AgentIdentifier("Uncle", true)</value>
                </parameterset>
            </initialmessageevent>
            <endmessageevent ref="inform_state">
                <parameter ref="content">
                    <value>$agent.getAgentName()+" is terminating."</value>
                </parameter>
                <parameterset ref="receivers">
                    <value>new AgentIdentifier("Uncle", true)</value>
                </parameterset>
            </endmessageevent>
        </events>
    </configuration>
</configurations>

Using the model API (package jadex.model) plans can dynamically load and unload capabilities. To load a capability, you first have to create a so called capability reference in the agent (or capability) model. The createCapabilityReference() method works the same as the <capability> tag shown in Figure 5.3, “Including subcapabilities”, and therefore expects the local name of the subcapability and a filename. After creating the reference, which also loads the given XML file, you can register the new capability at runtime (this will initialize the capability by creating initial goals, plans, etc.). To use the features of the capability you can also dynamically add references to the exported beliefs and goals of the capability. Figure 14.1, “Adding a capability at runtime” shows how to include a capability at runtime.

public void body() {
    // Create reference in the model.
    IMCapability model = (IMCapability)getScope().getModelElement();
    IMCapabilityReference subcap = model.createCapabilityReference("dfcap",
        "jadex.planlib.DF");

    // Register capability at runtime.
    getScope().registerSubcapability(subcap);
    ...
}

The removal of a capability can be done likewise. In Figure 14.2, “Removing a capability at runtime” an example code is depicted.

public void body() {
    ...
    IMCapabilityReference subcap = ((IMCapability)getScope().getModelElement())
        .getCapabilityReference("subcap_name");

    // Deregister subcapability at runtime.
    getScope().deregisterSubcapability(subcap);

    // Delete subcapability from the model.
    ((IMCapability)getScope().getModelElement()).deleteCapabilityReference(subcap);
    ...
}

Usually all agent beliefs are defined in the ADF. At runtime only the facts contained in the beliefs change, not the beliefs themselves. The model API (package jadex.model) allows to dynamically create new beliefs and belief sets at runtime, if this self-modifying functionality is required. To create a new belief, it first has to be defined in the agent or capability model. The createBelief...() methods of the IMBeliefbase work the same as the belief/set/reference tags shown in Figure 6.1, “The Jadex beliefs XML schema part”. For beliefs and belief sets a name, class, update rate and exported flag have to be specified. For belief(set) references instead of an update rate the path of the referenced belief(set) has to be provided.

After creating a belief(set) or reference in the model, you have to register the new element at runtime (this will also evaluate the initial facts, if you have supplied some in the model). Figure 14.3, “Creating a belief at runtime” shows how to create a belief at runtime.

public void body() {
    ...
    // Create belief in the model.
    IMBeliefbase model = (IMBeliefbase)getBeliefbase().getModelElement();
    IMBelief belief = model.createBelief("name", String.class, -1, false);

    // Register belief at runtime.
    getBeliefbase().registerBelief(belief);
    ...

    // Access the belief as usual.
    getBeliefbase().getBelief("name").setFact("Hugo");
    ...
}

In Figure 14.4, “Deleting a belief at runtime” it is shown how a belief can be deleted at runtime.

public void body() {
    ...
    IBelief belief = getBeliefbase().getBelief("belief_name");
    IMBelief mbelief = (IMBelief)belief.getModelElement();

    // Deregister the belief at runtime.
    getBeliefbase().deregisterBelief(mbelief);

    // Delete the belief in the model.
    IMBeliefbase model = (IMBeliefbase)getBeliefbase().getModelElement();
    model.deleteBelief(mbelief);
    ...
}

Usually all goal types (like, e.g., “performpatrol”) are defined in the ADF. At runtime instances of these types are created, but the set of available goal types remains the same. The model API (package jadex.model) allows to dynamically create new goal types and goal references at runtime, if this self-modifying functionality is required. To create a new goal type, it first has to be defined in the agent or capability model. The create...Goal() and create...GoalReference() methods of the IMGoalbase work the same as the tags shown in Figure 7.1, “The Jadex goals XML schema part”. For goals, a name, exported flag, retry, retry delay, and exclude mode are required. Maintain goals require in addition the specification of recur and recur delay. For references, the name, the exported flag, and the path to the referenced goal have to be specified.

After creating a goal or reference in the model, you have to register the new element at runtime (this will also activate the creation condition, if you have supplied one in the model). Figure 14.5, “Creating a new goal type at runtime” shows how to create a new goal type at runtime.

public void body() {
    ...
    // Create goal type in the model.
    IMGoalbase model = (IMGoalbase)getGoalbase().getModelElement();
    IMGoal goal = model.createPerformGoal("performpatrol", false, true, -1,
        IMGoal.EXCLUDE_NEVER);
    goal.createContextCondition("!$beliefbase.is_loading && !$beliefbase.daytime");

    // Register goal at runtime.
    getGoalbase().registerGoal(goal);
    ...
}

An example for the deletion of a goal type at runtime is shown in Figure 14.6, “Deleting a goal type at runtime”.

public void body() {
    ...
	// Assuming that mgoal is the model of the element to be deleted

    // Deregister goal at runtime.
    getGoalbase().deregisterGoal(mgoal);

    // Delete goal type from the model.
    IMGoalbase model = (IMGoalbase)getGoalbase().getModelElement();
    model.deleteAchieveGoal((IMAchieveGoal)mgoal);
    ...
}

Adding new plan specifications to the agent or capability at runtime is similar to what has already been described for beliefs and goals. First the plan head has to be created using the API of the jadex.model package. Afterwards, the plan has to be registered at runtime, mainly for activating the plan trigger.

public void body() {
    ...
    // Create plan type in the model.
    IMPlanbase model = (IMPlanbase)getPlanbase().getModelElement();
    IMPlan plan = model.createPlan("ping", 0, "new PingPlan()", IMPlanBody.BODY_STANDARD);
    plan.createTrigger().createMessageEvent("query_ping");

    // Register plan at runtime.
    getPlanbase().registerPlan(plan);
    ...
}

In the following the deletion of a plan type is sketched (see Figure 14.8, “Deleting a plan type at runtime”).

public void body() {
    ...
	// Assuming that mplan is the model of the element to be deleted

    // Deregister plan at runtime.
    getPlanbase().deregisterPlan(mplan);

    // Delete plan type in the model.
    IMPlanbase model = (IMPlanbase)getPlanbase().getModelElement();
    model.deletePlan(mplan);
    ...
}

In general it is possible to create custom events at runtime. This applies for goal, message as well as internal events. Nevertheless, as goal events are used only internally creating message and internal events should be the only relevant use case.

In Figure 14.9, “Creating a new internal event type at runtime” an example is depicted how a new internal event can be created and registered.

public void body() {
    ...
    // Create event type in the model.
    IMEventbase model = (IMEventbase)getEventbase().getModelElement();
    IMInternalEvent ievent = model.createInternalEvent("new_ievent", false);
    ievent.createParameter("param1", String.class, IMParameter.DIRECTION_IN, 0, null, null);

    // Register event at runtime.
    getEventbase().registerEvent(ievent);
    ...
}

In Figure 14.10, “Deleting an internal event type at runtime” the removal of an internal event at runtime is outlined.

public void body() {
    ...
    // Assuming that imevent is the model of the event to be deleted

    // Deregister event at runtime.
    getEventbase().deregisterEvent(imevent);

    // Delete event type in the model.
    IMEventbase model = (IMEventbase)getEventbase().getModelElement();
    model.deleteInternalEvent(imevent);
    ...
}

A Jadex agent is synchronized in the sense, that only one plan step at a time is executed (or none, if the agent is busy performing internal reasoning processes). Sometimes one may want to access agent internals from external threads. A good example is when your agent provides a graphical user interface (GUI) to accept user input. When the user clicks a button your Java AWT/Swing event handler method is called, which is executed on the Java AWT-Thread (there is one AWT Thread for each Java virtual machine instance). To force that such external threads are properly synchronized with the internal agent execution, you are not allowed to call Jadex methods directly from those threads. If you try to do so, a runtime exception “Wrong thread calling plan interface” will be thrown. On the contrary, it is allowed to call the external access from any thread (including plan resp. agent threads).

The AbstractPlan class provides a method getExternalAccess() which returns an accessor which automatically does the necessary thread synchronization. This accessor implements the ICapability interface, providing access to all features of the capability (beliefbase, goalbase, etc.). In addition, some convenience methods are provided to wait for goals to be completed or messages to be received. These methods should be used with caution, as they could easily lead to deadlocks. To avoid at least one source of deadlocks, it is not possible to call blocking methods on this accessor from the plan thread. Whenever you call the wrong object from the wrong thread, a RuntimeException will immediately identify the problem. The following code presents an example where a belief is changed when the user presses a button.

public void body() {
    ...
    JButton button = new JButton("Click Me");
    button.addActionListener(new ActionListener() {
        public void actionPerformed(ActionEvent e) {
            // This code is executed on the AWT thread (not on the plan thread!)
            IBeliefbase bb = getExternalAccess().getBeliefbase();
            bb.getBelief("button_pressed").setFact(new Boolean(true));
        }
    });
    ...
}

Agent listeners can be used to get informed whenever agent state changes happen. Normally, listeners will be employed in agent external components such as a GUI for getting information about declared elements. A GUI e.g. could use a listener to update its view with respect to belief changes in the agent. Generally, for all important agent attitudes such as belief, plans and goals as well as the agent itself different listener types exist (see Table 15.1, “Available listeners”).

Depending on the listener type different callback methods are provided that are automatically invoked when relevant changes happen. Whenever a callback method is invoked a so called AgentEvent is passed and contains relevant information about the change that happened. It basically offers the two methods getSource() and getValue(). The source here is the originating element of the change event. For belief and beliefset changes, the agent event additionally contains the changed fact object, accessible by getValue().

The invocation of listener methods can happen either on the agent thread or on a separate thread. If the notification is performed on the agent thread it is not possible to use blocking calls such as dispatchTopLevelGoalAndWait(). This is only allowed if asynchronous listeners are used. The decision to use a synchronous or an asynchronous listener is made when the listener is added.

The addition and removal of listeners can be done either on the instance elements themselves (e.g. a goal) or on the bases (e.g. the goalbase). In case the listener shall be added on an instance element it is only necessary to pass the listener object itself and the asynchronous flag as parameters of the call (e.g. addBeliefListener( IBeliefListener listener, boolean async)). In case a type-based listener shall be used e.g. for getting informed about new goal instances in addition to the parameters aforementioned also the type needs to be declared (e.g. addGoalListener( String type, IGoalListener listener, boolean async)).

In the listener example below (see Figure 15.2, “Agent listener example”) it is shown how a belief listener can be directly added to a "name" belief via the external access interface. It is used to update the value of a textfeld whenever the belief value changes.

IExternalAccess agent = ...
agent.getBeliefbase().getBelief("name").addBeliefListener(new IBeliefListener() {
    public void beliefChanged(AgentEvent ae) {
        textfield.setText("Name: ["+ae.getValue()+"]");
    }
}, false);

The Agent Management System (AMS) capability provides goals, that allow the application programmer to use functionalties of the local or some remote AMS. Basically the AMS is responsible for managing the agent lifecycle and for interacting with the platform. Concretely this means the AMS capability can be used for

...
<capabilities>
    <capability name="amscap" file="jadex.planlib.AMS" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="ams_create_agent">
        <concrete ref="amscap.ams_create_agent" />
    </achievegoalref>
    ...
</goals>
...

public void body() {
    ...
    IGoal ca = createGoal("ams_create_agent");
    ca.getParameter("type").setValue("mypackage.MyAgent");
    dispatchSubgoalAndWait(ca);
    AgentIdentifier createdagent = (AgentIdentifier)
        ca.getParameter("agentidentifier").getValue();
    ...
}

public void body() {
    AgentIdentifier ams = new AgentIdentifier("ams@remoteplatform",
        new String[]{"nio-mtp://134.100.11.232:5678"});
    IGoal ca = createGoal("ams_create_agent");
    ca.getParameter("type").setValue("mypackage.MyAgent");
    ca.getParameter("ams").setValue(ams);
    dispatchSubgoalAndWait(ca);
    AgentIdentifier createdagent = (AgentIdentifier)
        ca.getParameter("agentidentifier").getValue();
   ...
}

...
<capabilities>
    <capability name="amscap" file="jadex.planlib.AMS" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="ams_start_agent">
        <concrete ref="amscap.ams_start_agent" />
    </achievegoalref>
    ...
</goals>
...

public void body() {
    // Fetching the agent identifier after creating
    AgentIdentifier createdagent = (AgentIdentifier)
         ca.getParameter("agentidentifier").getValue();

    IGoal sa = createGoal("ams_start_agent");
    // sa.getParameter("ams").setValue(ams);  // Set ams in case of remote platform
    sa.getParameter("agentidentifier").setValue(createdagent);
    dispatchSubgoalAndWait(sa);
    ...
}

...
<capabilities>
    <capability name="amscap" file="jadex.planlib.AMS" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="ams_destroy_agent">
        <concrete ref="amscap.ams_destroy_agent" />
    </achievegoalref>
    ...
</goals>
...

public void body() {
    IGoal da = createGoal("ams_destroy_agent");
    da.getParameter("agentidentifier").setValue(createdagent);
    // da.getParameter("ams").setValue(ams);  // Set ams in case of remote platform
    dispatchSubgoalAndWait(da);
    ...
}

...
<capabilities>
    <capability name="amscap" file="jadex.planlib.AMS" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="ams_suspend_agent">
        <concrete ref="amscap.ams_suspend_agent" />
    </achievegoalref>
    ...
</goals>
...

public void body() {
    AgentIdentifier agent;  // The agent to suspend
    ...
    IGoal sa = createGoal("ams_suspend_agent");
    sa.getParameter("agentidentifier").setValue(agent);
    // sa.getParameter("ams").setValue(ams);  // Set ams in case of remote platform
    dispatchSubgoalAndWait(sa);
    ...
}

...
<capabilities>
    <capability name="amscap" file="jadex.planlib.AMS" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="ams_resume_agent">
        <concrete ref="amscap.ams_resume_agent" />
    </achievegoalref>
    ...
</goals>
...

public void body() {
    AgentIdentifier agent;  // The agent to resume
    ...
    IGoal ra = createGoal("ams_resume_agent");
    ra.getParameter("agentidentifier").setValue(agent);
    // ra.getParameter("ams").setValue(ams);  // Set ams in case of remote platform
    dispatchSubgoalAndWait(ra);
    ...
}

...
<capabilities>
    <capability name="amscap" file="jadex.planlib.AMS" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="ams_search_agents">
        <concrete ref="amscap.ams_search_agents" />
    </achievegoalref>
    ...
</goals>
...

public void body() {
    AMSAgentDescription desc = new AMSAgentDescription(new AgentIdentifier("a1", true));
    IGoal search	= createGoal("ams_search_agents");
    search.getParameter("description").setValue(desc);
    // search.getParameter("ams").setValue(ams);  // Set ams in case of remote platform
    dispatchSubgoalAndWait(search);
    AMSAgentDescription[] result = (AMSAgentDescription[])
    search.getParameterSet("result").getValues();
    ...
}
				

...
<capabilities>
    <capability name="amscap" file="jadex.planlib.AMS" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="ams_shutdown_platform">
        <concrete ref="amscap.ams_shutdown_platform" />
    </achievegoalref>
    ...
</goals>
...

public void body() {
    IGoal sd = createGoal("ams_shutdown_platform");
    // sd.getParameter("ams").setValue(ams);  // Set ams in case of remote platform
    dispatchSubgoal(sd);
}

The directory facilitator allows the agents to register their services and search for the services offered by other agents. In order to avoid that there are registered services in the DF, that are no longer available, e.g. because the agent offering the service has been destroyed without deregistering its services, Jadex can use “lease times”, that is, the agent's service is only kept registered for that lease time and has to be refreshed by the agent before the lease time expires.

So if you're working with lease times, you have two possibilities of registering an agent. Either you register the agent's service only for the lease time by using the achieve-goal “df_register” with the option to manually refresh the registration with a “df_modify” achieve-goal, or you use the maintain-goal “df_keep_registered” that refreshes the registration automatically.

Depending on the kind of registration you chose, you can deregister an agent, either by using the “df_deregister”-goal as counterpart of “df_register” or you must first call the method drop() on the instance of the maintain-goal “df_keep_registered” and afterwards use a “df_deregister”-goal or keep the (now outdated registration) until the lease time expires.

The DF works with service descriptions. They are specified in the FIPA Agent Management Specification. Generally the agent services are described in form of DF service descriptions which belong to a DF agent description that additionally might contain information about the agent itself.

Concretely this means the DF capability can be used for

...
<capabilities>
    <capability name="dfcap" file="jadex.planlib.DF" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="df_register">
        <concrete ref="dfcap.df_register"/>
    </achievegoalref>
    ...
</goals>
...

public void body() {
    // Create an agent description with service descriptions
    
    ServiceDescription service1 = new ServiceDescription(
        "service_1", "type of service_1", "owner of service_1");

    // Define some characteristics of the services
    String[] languages = new String[]{"language_1", "language_2"};
    String[] ontologies = new String[]{"ontology_1", "ontology_2"};
    String[] protocols = new String[]{"protocol_1", "protocol_2"};

    Property[] properties = new Property[]{
        new Property("property_1", "value_1"),
        new Property("property_2", "value_2")};

    ServiceDescription service2 = SFipa.createServiceDescription(
        "service_2", "type of service_2", "owner of service_2",
        languages, ontologies, protocols, properties);
	
    ServiceDescription[] services = new ServiceDescription[]{service1, service2};

    AgentDescription desc = SFipa.createAgentDescription(null, services, null, null, null);

    IGoal register = createGoal("df_register");
    register.getParameter("description").setValue(desc);
    
    // For a remote DF
    // AgentIdentifier df = ...
    // register.getParameter("df").setValue(df);

    dispatchSubgoalAndWait(register);
    ...
}

...
<configurations>
    <configuration name="default">
        ...
        <goals>
            <initialgoal ref="df_register">
                <parameter ref="description">
                    <value>
                        SFipa.createAgentDescription(null, 
                        SFipa.createServiceDescription("offered_service",
                        "my_agent", "me"))
                    </value>
                </parameter>
                <parameter ref="leasetime">
                    <value>100000</value>
                </parameter>
            </initialgoal>				
        </goals>
        ...
    </configuration>
</configurations>
...

...
<capabilities>
    <capability name="dfcap" file="jadex.planlib.DF" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="df_keep_registered">
        <concrete ref="dfcap.df_keep_registered"/>
    </achievegoalref>
    ...
</goals>
...

public void body() {
    AgentDescription desc = ...

    // Alternative for setting the lease time as goal-parameter
    //desc.setLeaseTime(new Date(System.currentTimeMillis() + 20000));

    IGoal keep = createGoal("df_keep_registered");
    keep.getParameter("description").setValue(desc);
    keep.getParameter("leasetime").setValue(new Long(20000));
    // For a remote DF
    // AgentIdentifier df = ...
    // keep.getParameter("df").setValue(df);
    dispatchSubgoalAndWait(df_keep_registered, 2000);
    AgentDescription resdesc = ((AgentDescription)df_keep_registered
        .getParameter("result").getValue());
    ServiceDescription[] descriptions = resdesc.getServices();
    ...
}

...
<configurations>
    <configuration name="default">
        ...
        <goals>
            <initialgoal ref="df_keep_registered">
                <parameter ref="description">
                    <value>
                        SFipa.createAgentDescription(null, 
                        SFipa.createServiceDescription("offered_service",
                        "my_agent", "me"))
                    </value>
                </parameter>
                <parameter ref="leasetime">
                    <value>120000</value>
                </parameter>
            </initialgoal>				
        </goals>
        ...
    </configuration>
</configurations>
...

...
<capabilities>
    <capability name="dfcap" file="jadex.planlib.DF" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="df_modify">
        <concrete ref="dfcap.df_modify"/>
    </achievegoalref>
    ...
</goals>
...

public void body() {
    AgentDescription desc = ...
    IGoal modify = createGoal("df_modify");
    modify.getParameter("description").setValue(desc);
    // Set the leasetime up to one day
    modify.getParameter("leasetime").setValue(new Long(86400000));
    // For a remote DF
    // AgentIdentifier df = ...
    // modify.getParameter("df").setValue(df);
    dispatchSubgoalAndWait(modify);			
    AgentDescription resdesc = ((AgentDescription) 
        modify.getParameter("result").getValue());
    ...
}

...
<capabilities>
    <capability name="dfcap" file="jadex.planlib.DF" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="df_deregister">
        <concrete ref="dfcap.df_deregister"/>
    </achievegoalref>
    ...
</goals>
...

public void body() {
    IGoal deregister = createGoal("df_deregister");
    //AgentDescription desc = ...
    //deregister.getParameter("description").setValue(descript);

    dispatchSubgoalAndWait(deregister);
    ...
}

public void body() {
    IGoal keep = createGoal("df_keep_registered);
    ...
    dispatchSubgoal(keep);
    ...
    keep.drop();
    ...
}

...
<capabilities>
    <capability name="dfcap" file="jadex.planlib.DF" />
    ...
</capabilities>
...
<goals>
    <achievegoalref name="df_search">
        <concrete ref="dfcap.df_search"/>
    </achievegoalref>
    ...
</goals>
...

public void body() {
    // Search for a service with given type.
    IGoal df_search = createGoal("df_search");
    AgentDescription desc = new AgentDescription();
    desc.addService(new ServiceDescription(null, "type of service_1", null))
    df_search.getParameter("description").setValue(desc);
    // For a remote DF
    // AgentIdentifier df = ...
    // modify.getParameter("df").setValue(df);
    dispatchSubgoalAndWait(df_search);
    AgentDescription[] result = (AgentDescription[])df_search
        .getParameterSet("result").getValues();
    if(result.length != 0) {
        AgentIdentifier[] serviceproviders = new AgentIdentifier[result.length];
        for(int i = 0; i < result.length; i++)
            serviceproviders[i] = result[i].getName();
    }		
    ...
}

Interaction protocols are predefined patterns of allowed message sequences that are designed for different interaction purposes. As certain kinds of interaction objectives are useful in different kinds of application domains FIPA has standardized several domain-independent protocols. Jadex offers built-in support for most of these FIPA protocols and hence facilitates the task of building standardized interactions.

The FIPA specifications define interaction protocols by using AUML sequence diagrams [Bauer et al. 2001]. These sequence diagrams specify the roles of the participating agents, their cardinality and the allowed message occurrences. The specifications do not consider how these protocols should be systematically related to necessary domain activities. Therefore, the protocol- domain interactions have been analyzed and led to the extended specification of goal-oriented interaction protocols. These protocol descriptions devide each role into two distinct parts: the domain and the protocol layer. Together both layers encapsulate the whole functionality of a role. This separation has the objective to make explicit the interaction point between both. The interaction points are defined by the start and the end of the activity (denoted by arrows in the AUML diagrams) and also by the goal signature which shows the purpose of the activity. In addition, the goal signatures contain detailed information about the in- and out-parameters that are used to parametrize the invocations.

The protocols capability offers implementations of the following FIPA interaction protocol specifications:

The protocols capability contains the functionality of the initiator as well as the participant sides of the interactions. To use the functionality of the protocols capability it is necessary to include it within the capability section of the ADF. Generally, if the agent should be enabled to initiate protocols it is also required to reference the corresponding initiator goal types, e.g. for the request protocol the rp_initiate goal type. Within plans a protocol can be started by creating a goal instance of a initiator goal type, setting the needed parameter value and dispatching it. After the protocol has ended the results can be directly read out of the out-parameters of the goal.

On the other hand the participant side of the protocols capability depends not only referencing necessary receiver goals but also on belief settings. Per default the participant role of the capability is turned off meaning that no messages will be handled by it. If you want to use it for handling protocols it is necessary to determine as exactly as possible which kinds of initiator messages should be accepted. For that purpose for each of the supported protocols a filter belief has been defined, e.g. the belief rp_filter is used to determine which request messages should trigger the capability. If the initial fact is set to IFilter.ALWAYS all request messages will be delegated to the capability. Normally, it is advisable to further constrain the kinds of messages that should be routed into the capability by using a custom filter expression.

In the following the meaning and usage of the different protocols will be described in more detail.

16.3.1. FIPA Request Interaction Protocol (RP)

The Request Interaction Protocol (SC00026H) manages the interaction consisting of one initiator and one participant agent. The initiator wants the participant to perform some action.

Figure 16.29.  The Request Protocol

The protocol consists of a initiator and a participant side (cf. Figure 16.29, “ The Request Protocol ”). The initiator asks the participant to perform an action by sending a request message. When the participant receives this message it accepts or refuses to perform the action and dependent on that decision it either sends an optional agree message or a refuse message. If it has agreed, the participant subsequently performs the action and when it has finished, the participant sends a failure or an inform message. The inform message may be just a notification that the task was done or contain a result of the task execution.

In Jadex, the Protocols capability offers four corresponding goals. One for the initiator and three for the participant side. Namely “rp_initiate”, “rp_receiver_interaction”, “rp_decide_request” and “rp_execute_request”.

16.3.1.1. Initiator Side

From the view of the initiator side the protocol can be executed completely with dispatching the “rp_initiate”-goal and waiting for its completion.

It has the following parameters:

Table 16.13. Parameters for rp_initiate

Name	Type	Description
action	Object	The action to be performed by the requested agent.
receiver	AgentIdentifier	The receiver of the request.
language *	String	The language to be used in the interaction (for the marshalling of the action and result objects).
ontology *	String	The ontology to be used in the interaction (for the marshalling of the action and result objects).
timeout *	Long	The timeout for the request.
interaction_state [out]	InteractionState	An object allowing to inspect the interaction state after protocol execution.
result [out]	Object	The result of the protocol execution (if sent in the inform message).

_{*: optional parameter}

In the code snippets below it is shown what needs to be done for starting a request protocol. First, the capability and the rp_initiate goal need to be included as depicted in Figure 16.30, “Inclusion of the rp_initiate goal”. From within a plan the protocol can be started by creating a corresponsing goal instance, setting its parameters to the desired values and dispatching it (cf. Figure 16.31, “Using the rp_initiate goal”). When the goal has finished the results of the protocol execution can be fetched.

...
<capabilities>
    <capability name="procap" file="jadex.planlib.Protocols"/>
    ...
</capabilities>
...
<goals>
    ...
    <achievegoalref name="rp_initiate">
        <concrete ref="procap.rp_initiate"/>
    </achievegoalref>
</goals>
...				

Figure 16.30. Inclusion of the rp_initiate goal

public void body() {
    AgentIdentifier rec = ...
    Object action = ...
    IGoal request = createGoal("rp_initiate");
    request.getParameter("action").setValue(action);
    request.getParameter("receiver").setValue(rec);
    dispatchSubgoalAndWait(request);	
    Object res = request.getParameter("result").getValue();
    ...
}				

Figure 16.31. Using the rp_initiate goal

16.3.1.2. Participant Side

On the participant side a request protocol can be triggered when the rp_filter belief value allows this (per default it is turned off). When a request message arrives that passes the rp_filter a new “rp_receiver_interaction” goal is created. This goal is present during the whole lifetime of the interaction and will contain the results and interaction state of the conversation. If the participant side wants to be informed about the outcome of its conversations it can do so by waiting for the completion of this goal (using the goalfinished trigger type). For the implementation of the requesters domain functionality two goals can be used. If the conversation is handled by the capability it will request domain activities by dispatching subgoals which should be handled by custom user plans.

The “rp_decide_request” goal is used by the capability to decide if the request should be accepted and the optional agree message should be sent. This goal is optional, which means that it needs not to be handled by the user. Per default the request is accepted and no agree message is sent. To accept and send the agree message the goal has be to handled and the accept return value should be set to true. If set to false a refuse message is sent and the interaction is immediately terminated.

Table 16.14. Parameters for rp_decide_request

Name	Type	Description
initiator	AgentIdentifier	The initiator of the protocol.
action	Object	The action to be performed by the requested agent.
accept [out]	Boolean	True, if the request should be accepted and the optional agree message should be sent.

The “rp_execute_request” goal is used by the capability to request the action being executed by the domain layer. The handling of this goal is mandatory for a successful protocol execution. If the domain plan for handling this goal has executed the requested action without problems it can write back to results of this execution to the result parameter of the goal. If the action execution fails this should be indicated by letting the plan fail (by raising an exception).

Table 16.15. Parameters for rp_execute_request

Name	Type	Description
initiator	AgentIdentifier	The initiator of the protocol.
action	Object	The action to be performed by the requested agent.
result [out] *	Object	The result of the action execution.

In the following code cutouts it is shown what needs to be done for handling a request protocol as receiver. First, the capability and the participant goals need to be included as indicated in Figure 16.32, “Inclusion of the participant goals and beliefs”. In the example also the optional rp_decide_request goal is used. It is shown that the agent in the example wants to handle all request messages via its protocol capability, because the rp_filter is set to IFilter.ALWAYS. In addition three plans have been declared, one for each of the protocol goals. The optional rp_finished_plan is used to detect whenever a request interaction has ended. The corresponding plan body can evaluate the results and may perform action in response to them.

...
<capabilities>
    ...
    <capability name="procap" file="jadex.planlib.Protocols"/>
</capabilities>

<beliefs>
    ...
    <beliefref name="rp_filter" class="IFilter">
        <concrete ref="procap.rp_filter"/>
    </beliefref>
</beliefs>

<goals>
    ...
    <performgoalref name="rp_receiver_interaction">
        <concrete ref="procap.rp_receiver_interaction"/>
    </performgoalref>
    <achievegoalref name="rp_decide_request">
        <concrete ref="procap.rp_decide_request"/>
    </achievegoalref>
    <achievegoalref name="rp_execute_request">
        <concrete ref="procap.rp_execute_request"/>
    </achievegoalref>
</goals>

<plans>
    ...
    <plan name="rp_decide_request_plan">
        <parameter name="action" class="Object">
            <goalmapping ref="rp_decide_request.action"/>
        </parameter>
        <parameter name="accept" class="Boolean" direction="out">
            <goalmapping ref="rp_decide_request.accept"/>
        </parameter>
        <body>new MyDecideRequestPlan()</body>
        <trigger><goal ref="rp_decide_request"/></trigger>
    </plan>

    <plan name="rp_execute_request_plan">
        <parameter name="action" class="Object">
            <goalmapping ref="rp_execute_request.action"/>
        </parameter>
        <parameter name="result" class="Object" direction="out" optional="true">
            <goalmapping ref="rp_execute_request.result"/>
        </parameter>
        <body>new MyExecuteActionPlan()</body>
        <trigger><goal ref="rp_execute_request"/></trigger>
    </plan>

    <plan name="rp_finished_plan">
        <parameter name="interaction_state" class="InteractionState">
            <value>(InteractionState)((IRGoalEvent)$event).getGoal()
                .getParameter("interaction_state").getValue()</value>
        </parameter>
        <parameter name="result" class="Object">
            <value>((IRGoalEvent)$event).getGoal()
                .getParameter("result").getValue()</value>
        </parameter>
        <body>new MyResultPlan()</body>
        <trigger>
            <goalfinished ref="rp_receiver_interaction"/>
        </trigger>
    </plan>
</plans>
...
<configurations>
    <configuration name="default">
        <beliefs>
            <initialbelief ref="rp_filter">
                <fact>IFilter.ALWAYS</fact>
            </initialbelief>
            ...
        </beliefs>
        ...
    </configuration>
</configurations>
...				

Figure 16.32. Inclusion of the participant goals and beliefs

In Figure 16.33, “ Plan body of the MyDecideRequestPlan ” the schematic content of the MyDecideRequestPlan body is depicted. The result of the acceptance test is stored in the accept parameter. Similarly, in Figure 16.34, “ Plan body of the MyExecuteRequestPlan ” an outline of the MyExecuteActionPlan is given. It reads out the action description, performs some operation for executing this action and then writes back the result to the result parameter.

public void body()
{
    Object action = getParameter("action").getValue();
    boolean accept = ... // Determine acceptance
    getParameter("accept").setValue(new Boolean(accept));
}				

Figure 16.33.  Plan body of the MyDecideRequestPlan

public void body() {
    Object action = getParameter("action").getValue();
    // Perform the action
    result = ...
    // Store the result
    getParameter("result").setValue(result);
}				

Figure 16.34.  Plan body of the MyExecuteRequestPlan

16.3.2. FIPA Contract Net Interaction Protocol (CNP)

The Contract Net Protocol (SC00029H) is used for negotiations between one initiator and an arbitrary number of participant agents. Its purpose is to delegate a task to other agents and let them execute the tasks on the initiator agent's behalf.

Figure 16.35.  The Contract Net Protocol

There is an initiator and a participant side of the protocol. The initiator sends a call for proposal to an arbitrary number of participant agents. Then it waits for proposals of the participants until a given deadline has passed. Up to this deadline the participants can either send a propose message or a refuse message. When the deadline has passed, the initiator decides about all of the received proposals and either sends reject- or accept-proposal messages to the participants. The elected participants now have the commitment to perform the task. Thereafter they send send an inform message with the result (if any), or if the execution has failed, they send a failure message.

In Jadex, there are five corresponding goals, called “cnp_initiate”, “cnp_evaluate_proposals”, “cnp_receiver_interaction”, “cnp_make_proposal” and “cnp_execute_task”. The first two implement the initiator side, the other ones belong to the participant side.

16.3.2.1. Initiator Side

From the view of the initiator side the protocol can be started via dispatching the “cnp_initiate”-goal. During execution of the goal the protocol engine will automatically dispatch a “cnp_evaluate_proposals”-goal. This goal should be handled to decide wich proposals should be accepted.

The cnp_initiate-goal has the following parameters:

Table 16.16. Parameters for cnp_initiate

Name	Type	Description
cfp	Object	The call for proposals. Will be sent to all participants.
cfp_info *	Object	Some local information about the cfp. Will not be sent to the participants but is available as input in other initiator goals.
ontology *	String	The ontology to be used in the interaction (e.g. for the marshalling of the cfp and proposal objects).
language *	String	The language to be used in the interaction (e.g. for the marshalling of the cfp and proposal objects).
timeout *	Long	The timeout for the call for proposal.
executeall *	Boolean	Set to true, when all acceptable proposals should be executed. Defaults to false, such that only one successful proposal is accepted per default.
interaction_state [out]	InteractionState	An object allowing to inspect the interaction state after protocol execution.
receivers [set]	AgentIdentifier	The receivers of the call for proposal.
result [set][out]	Object	The results of the task executions.
history [set][out]	NegotiationRecord	The negotiation history.

_{*: optional parameter}

The second important goal on initiator side is the "cnp_evaluate_proposals" goal. Its in- and out-parameters are described below.

Table 16.17. Parameters for cnp_evaluate_proposals

Name	Type	Description
cfp	Object	The original call for proposals as initially sent to participants.
cfp_info [inout] *	Object	Local information about the cfp if set in the initiate goal.
proposals [set]	ParticipantProposal	The proposals received from the participants.
history [set] *	NegotiationRecord	Details about the negotiation.
acceptables [set][out]	ParticipantProposal	The acceptable proposals that should be selected.

_{*: optional parameter}

In the code that follows it is depicted what needs to be done for executing a contract-net negotiation. First, the capability, the cnp_initiate and the cnp_evaluate_proposals goals need to be included as shown in Figure 16.36, “ Including the protocols capability and the goals for the contract-net protocol ”. In a plan the cnp_initiate goal needs to be created and its mandatory parameters should be set to the desired values. After dispatching the goal (cf. Figure 16.37, “Using the cnp_initiate goal”) one can wait for its completion and read out the results of the protocol execution. During the execution the engine will raise a cnp_evaluate_proposals goal which should be handled by a custom plan.

...
<imports>
    ...
    <import>jadex.planlib.*</import>
</imports>

<capabilities>
    ...
    <capability name="procap" file="jadex.planlib.Protocols"/>
</capabilities>
...
<goals>
    ...
    <achievegoalref name="cnp_initiate">
        <concrete ref="procap.cnp_initiate"/>
    </achievegoalref>
    <querygoalref name="cnp_evaluate_proposals">
        <concrete ref="procap.cnp_evaluate_proposals"/>
    </querygoalref>	
    ...
</goals>
<plans>
    ...
    <plan name="evaluator_plan">
        <parameter name="cfp" class="Object">
            <goalmapping ref="cnp_evaluate_proposals.cfp"/>
        </parameter>
        <parameter name="cfp_info" class="Object" direction="inout" optional="true">
            <goalmapping ref="cnp_evaluate_proposals.cfp_info"/>
        </parameter>
        <parameterset name="proposals" class="ParticipantProposal">
            <goalmapping ref="cnp_evaluate_proposals.proposals"/>
        </parameterset>
        <parameterset name="history" class="NegotiationRecord" optional="true">
            <goalmapping ref="cnp_evaluate_proposals.history"/>
        </parameterset>
        <parameterset name="acceptables" class="ParticipantProposal" direction="out">
            <goalmapping ref="cnp_evaluate_proposals.acceptables"/>
        </parameterset>
        <body>new MyEvaluatorPlan()</body>
        <trigger>
            <goal ref="cnp_evaluate_proposals"/>
        </trigger>
    </plan>
</plans>
...				

Figure 16.36.  Including the protocols capability and the goals for the contract-net protocol

public void body() {
    AgentIdentifier[] recs = ...
    Object cfp = ...
    IGoal cnpini = createGoal("cnp_initiate");
    cnpini.getParameterSet("receivers").addValues(recs);
    cnpini.getParameter("cfp").setValue(cfp);
    dispatchSubgoalAndWait(cnpini);
    Object res = request.getParameterSet("result").getValues();
    ...
}				

Figure 16.37. Using the cnp_initiate goal

Not shown here is the content of the custom evaluator plan body which has the purpose to weight the proposals and choose those which should be performed. This can either be one or many and the acceptable proposals (if any) should be stored in the out-parameterset result. Depending on the value of the "executeall" parameter, the initiator will either sequentially accept the accpetable proposals in turn, until the first participant reports the given task being executed (i.e. answers with an inform message) and reject the remaining proposals ("executeall=false") or the initiator will accept all acceptable proposals in parallel rejecting only inacceptable proposals, thereby collecting potentially many results at once ("executeall=true"). The results of the execution are available in the "result" parameter set of the "cnp_initiate" goal. Additional information can be found in the negotiation history (parameter set "history"), which contains one NegotiationRecord object for the negotiation phase containg all proposals and their evaluations and another one for the execution phase containing the executed proposals and the received results from the participant.

16.3.2.2. Participant Side

On the participant side a cnp protocol is triggered when the cnp_filter belief value allows this (per default it is turned off). When a cfp message arrives that passes the cnp_filter a new “cnp_receiver_interaction” goal is created. This goal is present during the whole lifetime of the interaction and will contain the results and interaction state of the conversation. If the participant side wants to be informed about the outcome of its conversations it can do so by waiting for the completion of this goal (using the goalfinished trigger type). For the implementation of the participant domain functionality two goals need to be supported. If the conversation is handled by the capability it will automatically request domain activities by dispatching subgoals which should be handled by custom user plans.

The “cnp_make_proposal” goal is used by the capability to indicate that a proposal for a cfp should be generated. The custom user plan that handles this goal finds all necessary information about the cfp in the parameters of the goal. On the basis of this knowledge it can decide to participate in the contract-net negotiation by creating a proposal and storing it into the proposal out-parameter.

The “cnp_make_proposal”-goal has the following parameters:

Table 16.18. Parameters for cnp_make_proposal

Name	Type	Description
cfp	Object	The call-for-propsal that can be handled.
initiator	AgentIdentifier	The agent identifier of the protocol initiator.
proposal [out]	Object	The proposal for the cfp that will be sent back to the initiator.
proposal_info [out] *	Object	Some optional local data for the proposal. It will be available in the cnp_execute_task goal.

_{*: optional parameter}

If a proposal has been made and the initiator selects the participant as one of the winners a "cnp_execute_task" goal will be raised. A custom user plan should be provided that handles the goal, executes the task and reports back the results of the processing.

The “cnp_execute_task”-goal has the following parameters:

Table 16.19. Parameters for cnp_execute_task

Name	Type	Description
proposal	Object	The proposal that was sent to the initiator and has won.
proposal_info *	Object	The local proposal data that was generated by the cnp_make_proposal goal
initiator	Object	The initiator of the cfp.
result [out] *	Object	Information about the task execution.

_{*: optional parameter}

In the following code snippets it is shown what needs to be done for handling a contract-net protocol as receiver. First, the capability and the cnp_make_proposal, cnp_execute_task goals need to be included as indicated in Figure 16.38, “Inclusion of the participant goals and beliefs”. It is shown that the agent in the example wants to handle all cfp messages via its protocol capability, because the cnp_filter is set to IFilter.ALWAYS. In addition two plans have been declared, one for each of the protocol goals.

...
<capabilities>
    <capability name="procap" file="jadex.planlib.Protocols"/>
    ...
</capabilities>

<beliefs>
    <beliefref name="cnp_filter" class="IFilter">
        <concrete ref="procap.cnp_filter"/>
    </beliefref>
    ...
</beliefs>

<goals>
    <querygoalref name="cnp_make_proposal">
        <concrete ref="procap.cnp_make_proposal"/>
    </querygoalref>
    <achievegoalref name="cnp_execute_task">
        <concrete ref="procap.cnp_execute_task"/>
    </achievegoalref>
    ...
</goals>

<plans>
    <plan name="cnp_make_proposal_plan">
        <parameter name="cfp" class="Object">
            <goalmapping ref="cnp_make_proposal.cfp"/>
        </parameter>
        <parameter name="initiator" class="AgentIdentifier">
            <goalmapping ref="cnp_make_proposal.initiator"/>
        </parameter>
        <parameter name="proposal" class="Object" direction="out">
            <goalmapping ref="cnp_make_proposal.proposal"/>
        </parameter>
        <parameter name="proposal_info" class="Object" direction="out" optional ="true">
            <goalmapping ref="cnp_make_proposal.proposal_info"/>
        </parameter>
        <body>new MyMakeProposalPlan()</body>
        <trigger>
            <goal ref="cnp_make_proposal"/>
        </trigger>
    </plan>

    <plan name="cnp_execute_task_plan">
        <parameter name="proposal" class="Object">
            <goalmapping ref="cnp_execute_task.proposal"/>
        </parameter>
        <parameter name="proposal_info" class="Object" optional="true">
            <goalmapping ref="cnp_execute_task.proposal_info"/>
        </parameter>
        <parameter name="initiator" class="AgentIdentifier">
            <goalmapping ref="cnp_execute_task.initiator"/>
        </parameter>
        <parameter name="result" class="Object" direction="out" optional="true">
            <goalmapping ref="cnp_execute_task.result"/>
        </parameter>
        <body>new MyExecuteTaskPlan()</body>
        <trigger>
            <goal ref="cnp_execute_task"></goal>
        </trigger>
    </plan>
    ...
</plans>
...
<configurations>
    <configuration name="default">
        <beliefs>
            <initialbelief ref="cnp_filter">
                <fact>IFilter.ALWAYS</fact>
            </initialbelief>
            ...
        </beliefs>
        ...
    </configuration>
</configurations>
...				

Figure 16.38. Inclusion of the participant goals and beliefs

Besides the inclusion of the relevant goals and beliefs the main task of the agent programmer consists in developing the two custom domain plans. Here in the example code they are named MyMakeProposalPlan and the MyExecuteTaskPlan. As the basic responsibilities of the two plans consists in performing domain tasks and writing back the results to the goals no further code snippets will be given here.

16.3.2.3. Simplified Protocol Usage

In many cases, the decisions an agent has to make during the execution of a protocol are quite simple and do not necessarily have to be defined in terms of goals and plans. Therefore, the protocols capability offers some simple Java interfaces that can be implemented to describe these decisions instead of having to define plans. For the contract-net usually a plan has to be defined, to evaluate the received proposals and to decide about acceptable proposals. Alternatively, the jadex.planlib.IProposalEvaluator interface can be used for this purpose. An object implementing this interface can be passed in the "cfp_info" parameter of the "cnp_initiate" goal and will then automatically be used by a default plan in the protocols capability to handle the "evaluate_proposals" goal.

The IProposalEvaluator interface requires the evaluateProposals() method to be implemented, which features in essence the same parameters as the "evaluate_proposals" goal. To simplify the usage of the contract-net protocol even more, a default implementation is available (jadex.planlib.ProposalEvaluator), which handles some very common cases. The default implementation allows to determine acceptable proposals by comparing proposals or evaluations to a limit value, given in the constructor. Moreover, the evaluation process is implemented in three methods, which can be separately overwritten if needed, while reusing functionality of the other methods.

• The proposals are evaluated by calling the the evaluateProposal() method for each of the proposals. The evaluation result is written back into the proposal. The default implementation just checks, if the proposal object itself is suitable as an evaluation (i.e. if it is java.lang.Comparable).
• For each of the proposals, the acceptability is determined. By default, if a limit value is given, the proposal evaluations are compared to the limit value.
• Finally, the acceptable proposals are ordered by preference. As a default, the proposals are compared to each other and sorted according to a given ordering.

The usage of the default implementation is illustrated in Figure 16.39, “Simplified usage of the cnp_initiate goal”, in which a newly instantiated ProposalInitiator is used as cfp_info, to automatically accept all proposals greater or equal to 5.

public void body() {
    AgentIdentifier[] recs = ...
    Object cfp = ...
    IProposalEvaluator cfp_info = new ProposalEvaluator(new Integer(5), false);
    IGoal cnpini = createGoal("cnp_initiate");
    cnpini.getParameterSet("receivers").addValues(recs);
    cnpini.getParameter("cfp").setValue(cfp);
    cnpini.getParameter("cfp_info").setValue(cfp_info);
    dispatchSubgoalAndWait(cnpini);
    Object res = request.getParameterSet("result").getValues();
    ...
}				

Figure 16.39. Simplified usage of the cnp_initiate goal

16.3.3. FIPA Iterated Contract Net Protocol (ICNP)

The Iterated Contract Net Protocol (SC00030H) is used for negotiations between one initiator and an arbitrary number of participant agents. Its purpose is to delegate a task to other agents and let them execute the tasks on the initiator agent's behalf. The only difference to the normal contract net protocol described in the last section is that more than one negotiation round may be performed.

Figure 16.40. The Iterated Contract Net Protocol

There is an initiator and a participant side of the protocol. The initiator sends a call for proposal to an arbitrary number of participant agents. Then it waits for proposals of the participants until a given deadline has passed. Up to this deadline the participants can either send a propose message or a refuse message. When the deadline has passed, the initiator decides about all of the received proposals and evaluates if some proposals are acceptable (like in the non-iterated contract-net discussed in the last section). In a second step, the initiator decides, if another negotiation round should be initiated with a possibly refined cfp. New negotiation rounds can be performed with the same or any subset of the original participants. If a subset is chosen the excluded participants will be rejected immediately. When the initiator decides to accept some proposals (i.e. performing no further negotiation round), the winning participants have the commitment to perform the task. Thereafter they send send an inform message with a result (if any), or if the execution has failed, they send a failure message.

In Jadex, there are six corresponding goals, called “icnp_initiate”, “icnp_evaluate_proposals”, “icnp_nextround_info”, “icnp_receiver_interaction”, “icnp_make_proposal” and “icnp_execute_task”. The first three implement the initiator side, the other ones belong to the participant side. The goals are very similar to the non-iterated version of the contract net protocol. The only new goal is the query “icnp_nextround_info” goal, which decides if another negotiation round is necessary and which settings should apply to the next round (if any). As the other goals are identical to their original non-iterated counterparts here only the “icnp_nextround_info” will be explained in detail. For details about the other goals please refer to the explanations from the last section.

16.3.3.1. Initiator Side

From the view of the initiator side the protocol can be started via dispatching the "icnp_initiate" goal. During execution of the goal the protocol engine will automatically dispatch a "icnp_evaluate_proposals" goal. This goal should be handled to decide wich proposals are acceptable. After the evaluation has taken place the engine raises a "icnp_nextound_info" goal which has the purpose to decide if another negotiation round should be performed and if yes, which settings should be used, concerning e.g. the participants, the possibly refined cfp and additional only locally availabe cfp data.

The "icnp_nextound_info" goal has the following parameters:

Table 16.20. Parameters for icnp_nextround_info

Name	Type	Description
cfp [inout]	Object	The original call for proposals as initially sent to participants. Can be refined for the next round.
cfp_info [inout] *	Object	Local information about the cfp if set in the "icnp_initiate" or "icnp_evaluate_proposals" goal. Can be refined for the next round.
participants [set][inout]	AgentIdentifier	The participants of the negotiation. Can be refined for the next round.
proposals [set]	ParticipantProposal	The proposals received from the participants including the evaluation value possibly created while handling the "icnp_evaluate_proposals" goal.
history [set]	NegotiationRecord	Contains details about all the negotiation rounds that have been performed so far.
iterate [out]	Boolean	Flag indicating the decision to iterate (set to true or false to end goal).

_{*: optional parameter}

In the code that follows it is depicted what needs to be done for executing an iterated contract-net negotiation. First, the capability, the "icnp_initiate" goal, the "icnp_evaluate_proposals" goal and the "icnp_nextround_info" goal need to be included as shown in Figure 16.41, “ Including the protocols capability and the goals for the iterated contract-net protocol ”. In a plan the "icnp_initiate" goal needs to be created and its mandatory parameters should be set to the desired values. After dispatching the goal (cf. Figure 16.42, “Using the icnp_initiate goal”) one can wait for its completion and read out the results of the protocol execution. During the execution the engine will raise one "icnp_evaluate_proposals" goal in every negotiation round when the collected proposals need to be evaluated. Additionally an "icnp_nextround_info" goal is created in every round to decide if another round is necessary.

...
<imports>
    ...
    <import>jadex.planlib.*</import>
</imports>

<capabilities>
    ...
    <capability name="procap" file="jadex.planlib.Protocols"/>
</capabilities>
...
<goals>
    ...
    <achievegoalref name="icnp_initiate">
        <concrete ref="procap.icnp_initiate"/>
    </achievegoalref>
    <querygoalref name="icnp_evaluate_proposals">
        <concrete ref="procap.icnp_evaluate_proposals"/>
    </querygoalref>	
    <querygoalref name="icnp_nextround_info">
        <concrete ref="procap.icnp_nextround_info"/>
    </querygoalref>
</goals>
<plans>
    ...
    <plan name="evaluator_plan">
        <parameter name="cfp" class="Object">
            <goalmapping ref="icnp_evaluate_proposals.cfp"/>
        </parameter>
        <parameter name="cfp_info" class="Object" direction="inout" optional="true">
            <goalmapping ref="icnp_evaluate_proposals.cfp_info"/>
        </parameter>
        <parameterset name="proposals" class="ParticipantProposal">
            <goalmapping ref="icnp_evaluate_proposals.proposals"/>
        </parameterset>
        <parameterset name="history" class="NegotiationRecord" optional="true">
            <goalmapping ref="icnp_evaluate_proposals.history"/>
        </parameterset>
        <parameterset name="acceptables" class="ParticipantProposal" direction="out">
            <goalmapping ref="icnp_evaluate_proposals.acceptables"/>
        </parameterset>
        <body>new MyEvaluatorPlan()</body>
        <trigger>
            <goal ref="icnp_evaluate_proposals"/>
        </trigger>
    </plan>
	
    <plan name="icnp_nextround_plan">
        <parameter name="cfp" class="Object" direction="inout">
            <goalmapping ref="icnp_nextround_info.cfp"/>
        </parameter>
        <parameter name="cfp_info" class="Object" direction="inout" optional="true">
            <goalmapping ref="icnp_nextround_info.cfp_info"/>
        </parameter>
        <parameter name="iterate" class="Boolean" direction="out">
            <goalmapping ref="icnp_nextround_info.iterate"/>
        </parameter>
        <parameterset name="participants" class="AgentIdentifier" direction="inout">
            <goalmapping ref="icnp_nextround_info.participants"/>
        </parameterset>
        <parameterset name="proposals" class="ParticipantProposal">
            <goalmapping ref="icnp_nextround_info.proposals"/>
        </parameterset>
        <parameterset name="history" class="NegotiationRecord" optional="true">
            <goalmapping ref="icnp_nextround_info.history"/>
        </parameterset>
        <body>new MyNextroundPlan()</body>
        <trigger>
            <goal ref="icnp_nextround_info"/>
        </trigger>
    </plan>
</plans>
...				

Figure 16.41.  Including the protocols capability and the goals for the iterated contract-net protocol

public void body() {
    AgentIdentifier[] recs = ...
    Object cfp = ...
    IGoal icnpini = createGoal("icnp_initiate");
    icnpini.getParameterSet("receivers").addValues(recs);
    icnpini.getParameter("cfp").setValue(cfp);
    dispatchSubgoalAndWait(icnpini);
    Object res = request.getParameterSet("result").getValues();
    ...
}				

Figure 16.42. Using the icnp_initiate goal

Not shown here is the content of the custom evaluator plan body for the "icnp_evaluate_proposals" plan, which has the purpose to rate the proposals. It may identify one or many acceptable proposals (if any) which should be stored in the out-parameterset acceptables. This information can also be helpful for deciding which agent should participate in the next negotiation round. The information is available in the "icnp_decide_iteration" goal, which decides if another negotiation round should be performed (out-parameter "iterate") and which settings to use (inout-parameters "cfp", "cfp_info", "participants").

As already described for the non-iterated contract-net, the execution of acceptable proposals can be influenced by the value of the "executeall" parameter. When set to false (default) the initiator will either sequentially accept the accpetable proposals in turn, until the first participant answers with an inform message and reject the remaining proposals. When set to true, initiator will accept all acceptable proposals in parallel rejecting only inacceptable proposals, thereby collecting potentially many results at once.

16.3.3.2. Participant Side

On the participant side an iterated contract-net protocol is triggered when the icnp_filter belief value allows this (per default it is turned off). When a cfp message arrives that passes the icnp_filter a new “icnp_receiver_interaction” goal is created. This goal is present during the whole lifetime of the interaction and will contain the results and interaction state of the conversation. If the participant side wants to be informed about the outcome of its conversations it can do so by waiting for the completion of this goal (using the goalfinished trigger type). For the implementation of the participant domain functionality two goals need to be supported. If the conversation is handled by the capability it will automatically request domain activities by dispatching subgoals which should be handled by custom user plans.

The "icnp_make_proposal" goal is used by the capability to indicate that a proposal for a cfp should be generated. The custom user plan that handles this goal finds all necessary information about the cfp in the parameters of the goal. On the basis of this knowledge it can decide to participate in the contract-net negotiation by creating a proposal and storing it into the proposal out-parameter. As the iterated version of the contract-net protocol can consist of an arbirary number of negotiation rounds the protocol engine will raise one "icnp_make_proposal" goal in each round.

If the initiator finally selects the participant as one of the winners a "icnp_execute_task" goal will be raised. A custom user plan should be provided that handles the goal, executes the task and reports back the results of the processing.

16.3.3.3. Simplified Protocol Usage

To simplify the usage of protocols for cases, where no complex plans are needed, the protocols capability offers some simple Java interfaces that can be implemented to describe the required decisions instead of having to define plans. The iterated contract-net usually requires one plan for evaluating proposals and another plan for preparing the settings for the next negotiation round. Alternatively to an evaluate proposals plan, the IProposalEvaluator interface can be used as already described for the non-iterated contract-net protocol in Section 16.3.2.3, “Simplified Protocol Usage”. For determing settings of a further negotiation round the interface IQueryNextroundInfo comes into play for the iterated contract-net. As described before, an object implementing one of this interfaces can be passed in the "cfp_info" parameter of the "cnp_initiate" goal and will then automatically be used by a default plan in the protocols capability to handle the "evaluate_proposals" or the "nextround_info" goal. If you want to supply implementations of both interfaces, you can use the wrapper class ICNPHandler designed specifically for this purpose.

The IQueryNextroundInfo interface requires the queryNextroundInfo() method to be implemented, which resembles the signature of the "nextround_info" goal. As the "nextround_info" goal contains several inout parameters, which can not be mapped directly to method paramters, a helper class NextroundInfo is used to hold the current cfp, cfp_info and participants and allows these settings to be changed for the next round. The queryNextroundInfo() should return true, when another negotiation round is required. Currently, no default implementation for the IQueryNextroundInfo interface is available, so you have to implement the required method yourself. The usage of both interfaces is illustrated in Figure 16.43, “Simplified usage of the icnp_initiate goal”, in which a newly instantiated ICNPHandler is used as cfp_info containing an IProposalEvaluator and an IQueryNextroundInfo object. The proposal evaluator will automatically accept all proposals greater or equal to 5 and the IQueryNextroundInfo, implemented as anonymous inner class, leads to three negotiation rounds being performed.

public void body() {
    AgentIdentifier[] recs = ...
    Object cfp = ...
    IProposalEvaluator pe = new ProposalEvaluator(new Integer(5), false);
    IQueryNextroundInfo qnri = new IQueryNextroundInfo() {
        public boolean queryNextroundInfo(NextroundInfo info, 
            NegotiationRecord[] history, ParticipantProposal[] proposals) {
            return history.length < 3;
        }
    };
    Object cfp_info = new ICNPHandler(pe, qnri);
    IGoal icnpini = createGoal("icnp_initiate");
    icnpini.getParameterSet("receivers").addValues(recs);
    icnpini.getParameter("cfp").setValue(cfp);
    icnpini.getParameter("cfp_info").setValue(cfp_info);
    dispatchSubgoalAndWait(icnpini);
    Object res = request.getParameterSet("result").getValues();
    ...
}				

Figure 16.43. Simplified usage of the icnp_initiate goal

16.3.4. FIPA English Auction Interaction Protocol (EA)

The FIPA English Auction Interaction Protocol (XC00031F) describes an auction with steadily increased offers. The auction consists of an auctioneer and a set of bidders. The auctioneer chooses a start offer below the supposed market value. Round-by-round the offer is increased by the auctioneer as long as at least one bidder accepts the proposal. When no bidder is willing to accept the current offer of the auctioneer the auction has finished and the winner is the agent that has accepted the last offer. As the auctioneer starts the auction below the true market value it has the choice to not sell the good when the offered proposal is below his secret limit value.

Figure 16.44. The English Auction Protocol

Technically the auction is specified as follows:

The auctioneer starts the auction by sending an “inform-start-of-auction”-message that contains information such as the topic, start time etc. about the planned auction. When the start time of auction has been reached the auctioneer sends a call for proposal (CFP) to all bidders and waits. The bidders can react in three different ways. Firstly, a bidder can send a “not-understood”-message in order to signalize that it is not able to understand or not interested in the CFP. The auctioneer will subsequently exclude this bidder from the auction. Secondy, the bidder can decide to make an offer by sending a propose message. Thirdly, e.g., when the CFP exceeds the price the bidder is currently willing or allowed to pay, it may decide not to answer. In this case, the bidder will stay in the auction and may decide to bid again in a later negotiation round. Of course, the bidder, who won the last round, will usually not bid in the current round. The auctioneer waits for bids until the timeout of a negotiation round. If there is more than one proposal message, only the first one is accepted.^[2] (Even if they arrive at the same time, they will technically not be processed concurrently. This is similar to a real English auction, because if two bidders raise their hands at the same time it is also nondeterministic which one of the bidders is selected, as it depends on who is first noticed by the auctioneer.) So the first proposal is answered with an “accept_proposal”-message, any other proposal with a “reject_proposal”-message. The auction lasts as long as at least one bidder answers the current cfp. When in one round no bidder is willing to accept the current cfp, the auction ends. Finally, the auctioneer will send a “inform”-message to all participants.

There are six predefined goals in this capability that offer the possibility to implement an English auction without much coding effort. These goals are “ea_initiate”, “ea_decide_iteration”, “ea_decide_acceptance” “ea_receiver_interaction”, “ea_decide_participation” and “ea_make_proposal”. The first three goals belong to the initiator side while the others are used on receiver side.

16.3.4.1. Initiator Side

From the perspective of the initiator the protocol can be started via dispatching the “ea_initiate”-goal. The protocol engine will raise a “ea_decide_iteration”-goal for every further negotiation round. This goal gives the inititor the chance to decide if a next negotiation round should be performed (e.g. if there are time constraints) and what offer should be made to the participants.

The da_initiate goal needs to be provided with information about the auction (auction_description), the initial call-for-proposal (cfp) and the receivers that shall participate in the negotiation (receivers). Optionally, some local cfp data (cfp_info) as well as a language and ontology for marshalling can also be specified. As result the goal contains the global interaction state (iteraction_state) and the domain output (result).

The ea_initiate goal parameters are further explained in the following table:

Table 16.21. Parameters for ea_initiate

Name	Type	Description
auction_description	AuctionDescription	A detailed description about the auction.
cfp	Object	The initial offer of the initiator.
cfp_info *	Object	Optional locally available further cfp details.
limit *	Comparable	The secret limit offer of the auctioneer. When specified the protocol engine will test if the last offer is greater or equal than the limit. If this is not the case the good will not be sold to any bidder. When no limit is specified a ea_decide_acceptance goal will be raised and can be used to decide upon acceptance of the final offer.
ontology *	String	The ontology for marshalling.
language *	String	The language for marshalling.
receivers [set]	AgentIdentifier	The agent identifiers of the participants to which the auction will be advertised.
interaction_state [out]	InteractionState	The interaction state after protocol execution.
result [out] *	Object	The result of the protocol execution.

_{*: optional parameter}

The ea_decide_iteration goal is used to determine if the next round should be performed and which offer should be used in that round. For that purpose it provides the history of all made CFPs (history) and the only locally available additional cfp information (cfp_info). If a new round shall be performed the new CFP should be written to the cfp out-parameter.

The ea_decide_iteration parameters are further explained in the following table:

Table 16.22. Parameters for ea_decide_iteration

Name	Type	Description
cfp [out]	Object	The cfp for the next round.
cfp_info [inout] *	Object	Optional locally available further cfp details. Changes of the cfp_info can be stored in the parameter again.
history [set]	Object	The negotiation history. Contains all cfps made so far.

_{*: optional parameter}

The ea_decide_acceptance goal comes into play when the auction has ended and the auctioneer needs to decide if he, e.g., wants to sell the good for the reached price. There are two alternative ways how one can influence this decision. Firstly, the limit offer can be set directly in the ea_initiate goal. If this is too inflexible and the limit may vary over time it should be left open in the ea_initiate goal. Secondly, it can be determined by the automatically raised ea_decide_acceptance goal. When the goal is not handled by a custom plan and a winner exists it will be accepted. Otherwise the custom plan can decide upon acceptance.

The ea_decide_acceptance parameters are further explained in the following table:

Table 16.23. Parameters for ea_decide_acceptance

Name	Type	Description
auction_description	AuctionDescription	The detailed auction description.
cfp	Object	The current cfp.
cfp_info *	Object	Optional locally available further cfp details.
winner	AgentIdentifier	The auction winner.
accept [out]	Boolean	True, if the current offer should be accepted.
history [set]	Object	The negotiation history. Contains all cfps made so far.

_{*: optional parameter}

In the code below it is described what needs to be done for executing an English auction. First, the capability, the ea_initiate, the ea_decide_iteration (and optionally the ea_decide_acceptance) goals need to be included as shown in Figure 16.45, “ Including the protocols capability and the goals for the English auction protocol ”. In a plan the ea_initiate goal needs to be created and its mandatory parameters should be set to the desired values. After dispatching the goal (cf. Figure 16.46, “Using the ea_initiate goal”) one can wait for its completion and read out the results of the protocol execution. During the execution the engine will raise a ea_decide_iteration goal in every negotiation round which should be handled by a custom user plan. At the end of the auction a ea_decide_acceptance goal is raised when no limit was specified in the ea_initiate goal.

...
<capabilities>
    <capability name="procap" file="jadex.planlib.Protocols"/>
    ...
</capabilities>
...
<goals>
    ...
    <achievegoalref name="ea_initiate">
        <concrete ref="procap.ea_initiate"/>
    </achievegoalref>
    <querygoalref name="ea_decide_iteration">
        <concrete ref="procap.ea_decide_iteration"/>
    </querygoalref>	
    <querygoalref name="ea_decide_acceptance">
        <concrete ref="procap.ea_decide_iteration"/>
    </querygoalref>	
    ...
</goals>
<plans>
    <plan name="decide_iteration_plan">
        <parameter name="cfp" class="Object" direction="out">
            <goalmapping ref="ea_decide_iteration.cfp"/>
        </parameter>
        <parameter name="cfp_info" class="Object" direction="inout" optional="true">
            <goalmapping ref="ea_decide_iteration.cfp_info"/>
        </parameter>
        <parameterset name="history" class="Object">
            <goalmapping ref="ea_decide_iteration.history"/>
        </parameterset>
        <body>new MyDecideIterationPlan()</body>
        <trigger>
            <goal ref="ea_decide_iteration"/>
        </trigger>
    </plan>
    
    <plan name="decide_acceptance_plan">
        <parameter name="auction_description" class="Object">
            <goalmapping ref="ea_decide_acceptance.auction_description"/>
        </parameter>
        <parameter name="cfp" class="Object">
            <goalmapping ref="ea_decide_acceptance.cfp"/>
        </parameter>
        <parameter name="cfp_info" class="Object" optional="true">
            <goalmapping ref="ea_decide_acceptance.cfp_info"/>
        </parameter>
        <parameter name="winner" class="AgentIdentifier">
            <goalmapping ref="ea_decide_acceptance.winner"/>
        </parameter>
        <parameter name="accept" class="Boolean" direction="out">
            <goalmapping ref="ea_decide_acceptance.accept"/>
        </parameter>
        <parameterset name="history" class="Object">
            <goalmapping ref="ea_decide_acceptance.history"/>
        </parameterset>
        <body>new MyDecideAcceptancePlan()</body>
        <trigger>
            <goal ref="ea_decide_acceptance"/>
        </trigger>
    </plan>
    ...
</plans>
...				

Figure 16.45.  Including the protocols capability and the goals for the English auction protocol

public void body() {
    AgentIdentifier[] recs = ...
    Object cfp = ...
    long starttime = ...
    long roundtimeout = ...
    IGoal eaini = createGoal("ea_initiate");
    eaini.getParameterSet("receivers").addValues(recs);
    eaini.getParameter("cfp").setValue(cfp);
    eaini.getParameter("auction_description").setValue(new AuctionDescription(
        starttime, roundtimeout, "Test auction 1"));
    // Comparable limit = ...
    // eaini.getParameter("limit").setValue(limit);
    dispatchSubgoalAndWait(eaini);
    Object res = request.getParameter("result").getValues();
    ...
}				

Figure 16.46. Using the ea_initiate goal

Not shown here is the content of the custom decide iteration plan body which has the purpose to generate a new cfp if the next auction round should be performed A convenient way to do this consists in using an automatic offer generator following the interface of jadex.planlib.IOfferGenerator. Currently there are two implementation of this interface that allow automatic price generation. For linear price intervals you can use the LinearPriceCalculator and for exponential intervals the ExponentialPriceCalculator. In addition the custom plan body of the decide acceptance is not further illustrated. It only has to check if the offer should be accepted and write back the boolean value to the corresponding out-parameter (accept). Alternatively, the outcommented lines can be used if a fixed limit is admissable.

16.3.4.2. Participant Side

On the participant side an English auction protocol is triggered when the ea_filter belief value allows this (per default it is turned off). When a inform start-auction message arrives that passes the ea_filter a new “ea_receiver_interaction” goal is created. This goal is present during the whole lifetime of the interaction and will contain the results and interaction state of the conversation. If the participant side wants to be informed about the outcome of its conversations it can do so by waiting for the completion of this goal (using the goalfinished trigger type). For the implementation of the participant domain functionality two goals need to be supported. If the conversation is handled by the capability it will automatically request domain activities by dispatching subgoals which should be handled by custom user plans.

The “ea_decide_participation” goal is raised when an inform start-auction message has been received. It is used to determine if the participant wants to participate at the auction. If no plan is provided for handling the goal this is regarded as acceptance and the agent will participate at the auction.

Table 16.24. Parameters for ea_decide_participation

Name	Type	Description
initiator	AgentIdentifier	The agent identifier of the initiator.
auction_description	AuctionDescription	A detailed description about the auction.
auction_info [out] *	Object	Optional details about the auction that are only available locally.
participate [out] *	Boolean	True if the agent wants to participate.

_{*: optional parameter}

If the agent has decided to particpate and the auction has started it will be requested to react on call-for-proposals of the initiator. For this purpose a “ea_make_proposal” goal will be raised in every negotiation round. A custom user plan should be provided that handles the goal by evaluating the cfp and deciding about its acceptance. Additionally, the agent can also decide to leave the auction in every round via the goal if circumstances have changed.

Table 16.25. Parameters for ea_make_proposal

Name	Type	Description
cfp	Object	The call-for-proposal represents the current offer of the auctioneer.
auction_description	AuctionDescription	A detailed description about the auction.
auction_info [inout] *	Object	Optional details about the auction that are only available locally.
history [set] *	Object	The history of earlier CFPs.
accept [out] *	Boolean	True if the agent wants to accept the current cfp.
leave [out] *	Boolean	True if the agent wants to leave the auction.

_{*: optional parameter}

To use these goals, you must first of all include the Protocols capability in your ADF (if not yet done in order to use other goals of the Protocols capability) and set a reference to the goals as described in Figure 16.47, “ Including the Protocols capability and the participant goals for the English auction ”.

...
<capabilities>
    <capability name="procap" file="jadex.planlib.Protocols"/>
    ...
</capabilities>

<beliefs>
    <beliefref name="ea_filter" class="IFilter">
        <concrete ref="procap.ea_filter"/>
    </beliefref>
    ...
</beliefs>

<goals>
    <performgoalref name="ea_receiver_interaction">
        <concrete ref="procap.ea_receiver_interaction"/>
    </performgoalref>
    <achievegoalref name="ea_decide_participation">
        <concrete ref="procap.ea_decide_participation" />
    </achievegoalref>
    <querygoalref name="ea_make_proposal">
        <concrete ref="procap.ea_make_proposal" />
    </querygoalref>
    ...
</goals>

<plans>
    <plan name="decide_participation_plan">
        <parameter name="initiator" class="AgentIdentifier">
            <goalmapping ref="ea_decide_participation.initiator" />
        </parameter>
        <parameter name="participate" class="Boolean" direction="out" optional="true">
            <goalmapping ref="ea_decide_participation.participate" />
        </parameter>
        <parameter name="auction_description" class="AuctionDescription">
            <goalmapping ref="ea_decide_participation.auction_description" />
        </parameter>
        <parameter name="auction_info" class="Object" direction="out" optional="true">
            <goalmapping ref="ea_decide_participation.auction_info" />
        </parameter>
        <body>new MyDecideParticipationPlan()</body>
        <trigger>
            <goal ref="ea_decide_participation"></goal>
        </trigger>
    </plan>
    
    <plan name="make_proposal_plan">
        <parameter name="accept" class="Boolean" direction="out" optional="true">
            <goalmapping ref="ea_make_proposal.accept" />
        </parameter>
        <parameter name="leave" class="Boolean" direction="out" optional="true">
            <goalmapping ref="ea_make_proposal.leave" /> 
        </parameter>
        <parameter name="cfp" class="Object">
            <goalmapping ref="ea_make_proposal.cfp" />
        </parameter>
        <parameter name="auction_description" class="AuctionDescription">
            <goalmapping ref="ea_make_proposal.auction_description" />
        </parameter>
        <parameter name="auction_info" class="Object" direction="inout" optional="true">
            <goalmapping ref="ea_make_proposal.auction_info" />
        </parameter>
        <parameterset name="history" class="Comparable" optional="true">
            <goalmapping ref="ea_make_proposal.history" />
        </parameterset>
        <body>new MyMakeProposalPlan()</body>
        <trigger>
            <goal ref="ea_make_proposal"/>
        </trigger>
    </plan>
</plans>
...
<configurations>
    <configuration name="default">
        <beliefs>
            <initialbelief ref="ea_filter">
                <fact>IFilter.ALWAYS</fact>
            </initialbelief>
            ...
        </beliefs>
        ...
    </configuration>
</configurations>
...				

Figure 16.47.  Including the Protocols capability and the participant goals for the English auction

Besides the inclusion of the relevant goals and beliefs the main task of the agent programmer consists in developing the custom domain plan(s). Here in the example code they are named MyDecideParticipationPlan and MyMakeProposalPlan. As the basic responsibilities of the two plans consists in performing domain tasks and writing back the results to the goals no further code cutouts are shown here.

16.3.5. FIPA Dutch Auction Interaction Protocol (DA)

The FIPA Dutch Auction Interaction Protocol (XC00032F) describes an auction with steadily decreased offers. The auction consists of an auctioneer and a set of bidders. The auctioneer chooses a start offer much higher than the supposed market value. Round-by-round the offer is decreased by the auctioneer until there is a proposal from a bidder that accepts the offer. In this case the auction has finished successfully. Otherwise the auctioneer can stop the auction if his limit offer has been reached and further bids may not be acceptable for him.

Figure 16.48. The Dutch Auction Protocol

Technically the auction is specified as follows:

The auctioneer starts the auction by sending an “inform-start-of-auction”-message that contains information such as the topic, start time etc. about the planned auction. When the start time of auction has been reached the auctioneer sends a call for proposal (CFP) to all bidders and waits. The bidders can react in three different ways. Firstly, a bidder can send a “not-understood”-message in order to signalize that it is not able to understand the CFP. The auctioneer will subsequently exclude this bidder from the auction. Secondly, a bidder considers the CFP as inacceptable. In this case it will do nothing and wait for the next negotiation round in which a new CFP will be available. Thirdly, a bidder can send a proposal, i.e. it can accept the offer contained in the CFP from the auctioneer. If there is more than one proposal, only the first one is accepted.^[3] (Even if they arrive at the same time, they will technically not be processed concurrently. This is similar to a real Dutch auction, because if two bidders raise their hands at the same time it is also nondeterministic which one of the bidders is selected, as it depends on who is first noticed by the auctioneer.) So the first proposal is answered with an “accept_proposal”-message, any other proposal with a “reject_proposal”-message. At the end of the auction the auctioneer will send a “inform”-message to all participants.

There are five predefined goals in this capability that offer the possibility to implement a Dutch auction with only few lines of code. These goals are “da_initiate”, “da_decide_iteration”, “da_receiver_interaction”, “da_decide_participation” and “da_make_proposal”. The first two goals belong to the initiator side while the others are used on receiver side.

16.3.5.1. Initiator Side

From the perspective of the initiator the protocol can be started via dispatching the “da_initiate”-goal. If the auctioneered good is not bought immediately, the protocol engine will raise a “da_decide_iteration”-goal for every further negotiation round. This goal gives the inititor the chance to decide if a next negotiation round should be performed and what offer should be made to the participants.

The da_initiate goal needs to be provided with information about the auction (auction_description), the initial call-for-proposal (cfp) and the receivers that shall participate in the negotiation (receivers). Optionally, some local cfp data (cfp_info) as well as a language and ontology for marshalling can also be specified. As result the goal contains the global interaction state (interaction_state) and the domain output (result).

The da_initiate goal parameters are further explained in the following table:

Table 16.26. Parameters for da_initiate

Name	Type	Description
auction_description	AuctionDescription	A detailed description about the auction.
cfp	Object	The initial offer of the initiator.
cfp_info *	Object	Optional locally available further cfp details.
ontology *	String	The ontology for marshalling.
language *	String	The language for marshalling.
receivers [set]	AgentIdentifier	The agent identifiers of the participants to which the auction will be advertised.
interaction_state [out]	InteractionState	The interaction state after protocol execution.
result [out] *	Object	The result of the protocol execution.

_{*: optional parameter}

The da_decide_iteration is used to determine if the next round should be performed and which offer should be used in that round. For that purpose it provides the history of all made CFPs (history) and the only locally available additional cfp information (cfp_info). If a new round shall be performed the new CFP should be written to the cfp out-parameter.

The da_decide_iteration parameters are further explained in the following table:

Table 16.27. Parameters for da_decide_iteration

Name	Type	Description
cfp [out]	Object	The cfp for the next round.
cfp_info [inout] *	Object	Optional locally available further cfp details. Changes of the cfp_info can be stored in the parameter again.
history [set]	Object	The negotiation history. Contains all cfps made so far.

_{*: optional parameter}

In the code below it is described what needs to be done for executing a Dutch auction. First, the capability, the da_initiate and the da_decide_iteration goals need to be included as shown in Figure 16.49, “ Including the protocols capability and the goals for the Dutch auction protocol ”. In a plan the da_initiate goal needs to be created and its mandatory parameters should be set to the desired values. After dispatching the goal (cf. Figure 16.50, “Using the da_initiate goal”) one can wait for its completion and read out the results of the protocol execution. During the execution the engine will raise a da_decide_iteration goal in every negotiation round which should be handled by a custom user plan.

...
<capabilities>
    <capability name="procap" file="jadex.planlib.Protocols"/>
    ...
</capabilities>
...
<goals>
    ...
    <achievegoalref name="da_initiate">
        <concrete ref="procap.da_initiate"/>
    </achievegoalref>
    <querygoalref name="da_decide_iteration">
        <concrete ref="procap.da_decide_iteration"/>
    </querygoalref>	
    ...
</goals>
<plans>
    <plan name="decide_iteration_plan">
        <parameter name="cfp" class="Object" direction="out">
            <goalmapping ref="da_decide_iteration.cfp"/>
        </parameter>
        <parameter name="cfp_info" class="Object" direction="inout" optional="true">
            <goalmapping ref="da_decide_iteration.cfp_info"/>
        </parameter>
        <parameterset name="history" class="Object">
            <goalmapping ref="da_decide_iteration.history"/>
        </parameterset>
        <body>new MyDecideIterationPlan()</body>
        <trigger>
            <goal ref="da_decide_iteration"/>
        </trigger>
    </plan>
</plans>
...				

Figure 16.49.  Including the protocols capability and the goals for the Dutch auction protocol

public void body() {
    AgentIdentifier[] recs = ...
    Object cfp = ...
    IGoal daini = createGoal("da_initiate");
    daini.getParameterSet("receivers").addValues(recs);
    daini.getParameter("cfp").setValue(cfp);
    daini.getParameter("auction_description").setValue(new AuctionDescription(
        System.currentTimeMillis()+1000, roundtimeout, "Test auction 1"));
    dispatchSubgoalAndWait(daini);
    Object res = request.getParameter("result").getValues();
    ...
}				

Figure 16.50. Using the da_initiate goal

Not shown here is the content of the custom decide iteration plan body which has the purpose to generate a new cfp if the next auction round should be performed A convenient way to do this consists in using an automatic offer generator following the interface of jadex.planlib.IOfferGenerator. Currently there are two implementation of this interface that allow automatic price generation. For linear price intervals you can use the LinearPriceCalculator and for exponential intervals the ExponentialPriceCalculator.

16.3.5.2. Participant Side

On the participant side a Dutch auction protocol is triggered when the da_filter belief value allows this (per default it is turned off). When a inform start-auction message arrives that passes the da_filter a new “da_receiver_interaction” goal is created. This goal is present during the whole lifetime of the interaction and will contain the results and interaction state of the conversation. If the participant side wants to be informed about the outcome of its conversations it can do so by waiting for the completion of this goal (using the goalfinished trigger type). For the implementation of the participant domain functionality two goals need to be supported. If the conversation is handled by the capability it will automatically request domain activities by dispatching subgoals which should be handled by custom user plans.

The “da_decide_participation”-goal is raised when an inform start-auction message has been received. It is used to determine if the participant wants to participate at the auction. If no plan is provided for handling the goal this is valued as acceptance and the agent will participate at the auction.

Table 16.28. Parameters for da_decide_participation

Name	Type	Description
initiator	AgentIdentifier	The agent identifier of the initiator.
auction_description	AuctionDescription	A detailed description about the auction.
auction_info [out] *	Object	Optional details about the auction that are only available locally.
participate [out] *	Boolean	True if the agent wants to participate.

_{*: optional parameter}

If the agent has decided to particpate and the auction has started it will be requested to react on call-for-proposals of the initiator. For this purpose a “da_make_proposal” goal will be raised in every negotiation round. A custom user plan should be provided that handles the goal by evaluating the cfp and deciding about its acceptance. Additionally, the agent can also decide to leave the auction in every round via the goal if circumstances have changed.

Table 16.29. Parameters for da_make_proposal

Name	Type	Description
cfp	Object	The call-for-proposal represnts the current offer of the auctioneer.
auction_description	AuctionDescription	A detailed description about the auction.
auction_info [inout] *	Object	Optional details about the auction that are only available locally.
history [set] *	Object	The history of earlier CFPs.
accept [out] *	Boolean	True if the agent wants to accept the current cfp.
leave [out] *	Boolean	True if the agent wants to leave the auction.

_{*: optional parameter}

To use these goals, you must first of all include the Protocols capability in your ADF (if not yet done in order to use other goals of the Protocols capability) and set a reference to the goals as described in Figure 16.51, “ Including the Protocols capability and the participant goals for the Dutch auction ”.

...
<capabilities>
    <capability name="procap" file="jadex.planlib.Protocols"/>
    ...
</capabilities>

<beliefs>
    <beliefref name="da_filter" class="IFilter">
        <concrete ref="procap.da_filter"/>
    </beliefref>
    ...
</beliefs>

<goals>
    <performgoalref name="da_receiver_interaction">
        <concrete ref="procap.da_receiver_interaction"/>
    </performgoalref>
    <achievegoalref name="da_decide_participation">
        <concrete ref="procap.da_decide_participation" />
    </achievegoalref>
    <querygoalref name="da_make_proposal">
        <concrete ref="procap.da_make_proposal" />
    </querygoalref>
    ...
</goals>

<plans>
    <plan name="decide_participation_plan">
        <parameter name="participate" class="Boolean" direction="out" optional="true">
            <goalmapping ref="da_decide_participation.participate" />
        </parameter>
        <parameter name="auction_description" class="AuctionDescription">
            <goalmapping ref="da_decide_participation.auction_description" />
        </parameter>
        <parameter name="auction_info" class="Object" direction="out" optional="true">
            <goalmapping ref="da_decide_participation.auction_info" />
        </parameter>
        <body>new MyDecideParticipationPlan()</body>
        <trigger>
            <goal ref="da_decide_participation"></goal>
        </trigger>
    </plan>
    
    <plan name="make_proposal_plan">
        <parameter name="accept" class="Boolean" direction="out" optional="true">
            <goalmapping ref="da_make_proposal.accept" />
        </parameter>
        <parameter name="leave" class="Boolean" direction="out" optional="true">
            <goalmapping ref="da_make_proposal.leave" /> 
        </parameter>
        <parameter name="cfp" class="Object">
            <goalmapping ref="da_make_proposal.cfp" />
        </parameter>
        <parameter name="auction_description" class="AuctionDescription">
            <goalmapping ref="da_make_proposal.auction_description" />
        </parameter>
        <parameter name="auction_info" class="Object" direction="inout" optional="true">
            <goalmapping ref="da_make_proposal.auction_info" />
        </parameter>
        <parameterset name="history" class="Comparable" optional="true">
            <goalmapping ref="da_make_proposal.history" />
        </parameterset>
        <body>new MyMakeProposalPlan()</body>
        <trigger>
            <goal ref="da_make_proposal"/>
        </trigger>
    </plan>
</plans>
...
<configurations>
    <configuration name="default">
        <beliefs>
            <initialbelief ref="da_filter">
                <fact>IFilter.ALWAYS</fact>
            </initialbelief>
            ...
        </beliefs>
        ...
    </configuration>
</configurations>
...				

Figure 16.51.  Including the Protocols capability and the participant goals for the Dutch auction

Besides the inclusion of the relevant goals and beliefs the main task of the agent programmer consists in developing the custom domain plan(s). Here in the example code they are named MyDecideParticipationPlan and MyMakeProposalPlan. As the basic responsibilities of the two plans consists in performing domain tasks and writing back the results to the goals no further code cutouts are shown here.

16.3.6. Abnormal Termination of Protocols

As described in the specification of the FIPA protocols such as FIPA Request and FIPA Contract Net, at any point in time, one side of an ongoing interaction, i.e. the initiator or one of the participants, may decide to leave the interaction. When the initiator decides to leave the interation this will lead to the whole interaction to stop, while when a participant leaves, the initiator will usually continue to interact with the other participants. To indicate that it wishes to leave an interaction, a participant may send a not-understood message, while an initiator can decide to stop the whole protocol by sending a cancel message to all participants.

In the Protocols capability, all interactions are represented by an interaction goal. Therefore, when an agent whishes to leave an interaction it can naturally do so by dropping the corresponding goal. Generic mechanisms available in all implemented protocols will take care of the necessary coordination between initiator and participant(s). These mechanism are described in more detail in the following sections Section 16.3.6.1, “Leaving an Interaction (Participant Side)” and Section 16.3.6.2, “FIPA Cancel Meta Protocol (CM)”.

16.3.6.1. Leaving an Interaction (Participant Side)

Figure 16.52. The Participant Termination Subprotocol

The process of leaving an interaction is depicted in Figure 16.52, “The Participant Termination Subprotocol”. At any time after the interaction has started, the domain layer of the participant may decide to drop the interaction goal (e.g. a "cnp_receiver_interation" goal). The protocol will be aborted at the participant side and as an indication, a not-understood message is sent to the initiator, which will exclude the participant from the rest of the interaction. The participant domain layer can check the state after the abortion of the interaction, by waiting for the goalfinished event of the "<protocol>_receiver_interaction" (e.g. rp_receiver_interaction) goal and inspecting the "interaction_state" parameter.

16.3.6.2. FIPA Cancel Meta Protocol (CM)

Figure 16.53. The FIPA Cancel Meta Protocol

In Figure 16.53, “The FIPA Cancel Meta Protocol” it is shown, how a protocol can be cancelled from the initiator side. At any time after the interaction has started, the domain layer of the initiator may decide to drop the interaction goal (e.g. a "cnp_initiate" goal). The protocol will be aborted at the initiator side and a cancel message is sent to all participants. According to the FIPA Cancel Meta Protocol, which is specified as part of several other FIPA protocol specifications^[4], the participant has two choices. It may either answer with an inform message thereby indicating that it has no problem with the cancellation of the protocol. Otherwise, it might send a failure message containing some description of its objections (e.g. if the participant already performed some costly task it may demand a reimbursement). This decision is delegated to the participant domain layer in form of the query "cm_approve_cancel" goal. It contains the following input and output parameters:

Table 16.30. Parameters for cm_approve_cancel

Name	Type	Description
conversation-id	String	The id of the interaction to be cancelled. Can e.g. be used to find the corresponding goal in the goal base.
protocol	String	The name of the cancelled protocol (e.g. "fipa-request").
initiator	AgentIdentifier	The agent identifier of the initiator of the interaction.
result [out]	Boolean	Should be set to true if the interaction can be safely cancelled, and to false if there are some problems related to cancelling the interaction.
failure_reason [out] *	Object	An object describing the participants objections to the cancellation of the protocol.

_{*: optional parameter}

The "conversation-id", "protocol", and "initiator" parameters are used to identify the interaction to be cancelled. The boolean "result" parameter is used to store the decision and another parameter is available for the optional "failure_reason". A default plan exists in the protocols capability that will automatically acknowledge all "cm_approve_cancel" goals. Therefore custom plans for this goal are only necessary, when in some cases a failure message should be sent. Regardless of the goal result, the interaction will be terminated at the participant side, when the "cm_approve_cancel" goal returns. The handling of possibly required compensations is out of the scope of the cancel meta protocol and would have to be performed in a separate interaction between participant and initiatior.

The decision and potentially also the failure reason are communicated back to the sender, after the interaction has been terminated at the participant side. After all participants have answered to the cancel message or after the timout has passed, the protocol also ends at the initiator side. The participant and the initiator domain layer can check the state after the abortion of the interaction, by waiting for the goalfinished event of the "<protocol>_receiver_interaction" goal resp. the "<protocol>_initiate" goal and inspecting the "interaction_state" parameter, which will also contain references to the supplied failure reasons of the participants (if any). This information should be useful to initiate compensation actions, if necessary.