Work through the exercises in order, because later exercises require knowledge from the earlier ones.

Don't destroy your solutions of an exercise by modifying the old files. The different exercises often use the plans and agent description files (ADF) of a preceeding exercise. Copy all files and apply a simple naming scheme which contains the name of the exercise in the plan and ADF file names, e.g. the ADF in the exercise A1 is called TranslationA1.agent.xml and in exercise B1 TranslationB1.agent.xml.

Help us to make this tutorial better with your feedback. When you find errors or have problems that are directly concerned with the exercise descriptions feel free to let us know.

Whenever you encounter problems with Jadex we would be happy to help you. Please use therefore primarily the sourceforge help forum available on the Jadex sourceforge.net page. There is also a Jadex mailing list that can be used for asking questions about Jadex.

JADEX_HOME/lib/jadex_rt.jar

JADEX_HOME/lib/jibx-run.jar

JADEX_HOME/lib/xpp3.jar

JADEX_HOME/lib/nuggets.jar

JADEX_HOME/lib/janino.jar

JADEX_HOME/lib/jadex_standalone.jar

JADEX_HOME/lib/jadex_tools.jar

JADEX_HOME/lib/GraphLayout.jar

JADEX_HOME/lib/jhall.jar

Blackjack.  A distributed Blackjack implementation that allows agents as well as human players playing the famous Blackjack card game. In each round the participants bet virtual money and are rewarded if they win against the dealer.

Blocksworld.  In the well-known blocksworld scenario the problem consists of stacking differently colored blocks on a table. The objective for the agent is here to restack the blocks (and block towers) on the table in a way that the target configuration is achieved. This target configuration can be entered via the gui by the human user.

Booktrading.  In the booktrading scenario human book buyers and sellers delegate buy resp. sell orders to their corresponding agents. The agents negotiate using a contract-net protocol at a distributed market place in order to fulfill the strategic goals of their principals (low/high prices, deadline etc.).

Cleanerworld.  The cleanerworld example deals with the exploring and cleaning of an unknown environment. Basically, a cleaner robot has the tasks to search for waste, pick it up and bring it to a nearby wastebin. Additionally, it has to patrol in the environment at night and must always ensure that its battery does not run low.

Garbagecollector.  This example is a simpler version of the cleaner world. Cleaner robots have a predefined route which the use for picking up waste. When they found a piece of waste they carry it to a burner agent nearby which is responsible for burning it.

Helloworld.  The helloworld example contains a simple agent that when started prints out some welcome message and terminates itself after that.

Hunterprey.  This is a quite complex multi-agent simulation which realizes a variant of the hunter prey scenario. In general there are two different kinds of animals sheeps (the preys) and wulfs (the hunters). Both animals can get points by comsuming food. A sheep looks for salad whereas the wolfs hunt sheeps.

Marsworld.  In this scenario three different kind of robots operate on mars and search for ore. The main strategic objective is to carry as much ore as possible to the homebase of the robots. For this purpose sentry robots scan promising locations and commission production robots. These production robots convey the ore and order carry robots which have the task to bring the ore to the homebase.

Ping.  The ping example shows how an agent can send a simple "ping"-message to another agent which reacts on this message with an "alive"-reply.

Puzzle.  The puzzle agent has the task to solve a complex board game. The main goal is to swap the positions of the red and white pegs whereby the pieces can only move forward one field and can jump over one opposite peg. The puzzle agent solves this game by using an goal-oriented form of backtracking.

Create the plan as extension to the jadex.runtime.Plan class:

public class EnglishGermanTranslationPlanB1 extends Plan {
    // Plan attributes.

    public EnglishGermanTranslationPlanB1() {
        // Initialization code.
    }

    public void body() {
        // Plan code.
    }
}

Import the needed classes:

import java.util.*;
import jadex.runtime.*;

Let the no argument constructor print out the text "Created:"+this.

Implement the plan's body() method as infinite loop. At the beginning of this loop the plan should wait for translation requests:

IMessageEvent me = waitForMessageEvent("request_translation");

Instead of performing a database query let us use a simple hashmap for the word lookup. The creation and initialization of this word table with a few word pairs can already be done in the constructor. As result the plan should print "Translating from English to German: "+eword+" - "+gword or "Sorry word is not in database: "+eword. To get the content from the request-event use me.getContent().

Therefore, a new plans section is introduced (lines 13-20), in which all plans for the agent have to be declared. In this simple example only one plan named here "egtrans" is added (lines 14-19). In line 15 the Java expression for creating the plan body is stated. Note that it is allowed to use any Java mechanism to create the plan (e.g. one could use a static method instead of a constructor call). In the next lines the plan's waitqueue is declared to handle all message events of type "request_translation". This means that the plan has its own event waitqueue in which all matching events are dispatched, even when the plan is busy and currently waits for other events. These events are collected in its queue till it calls a suitable waitFor() matching one of the collected events. In this case this collected event is directly dispatched to the plan.

The plan should be started when the agent is born. For this purpose a configuration has to be declared within the ADF (lines 30-36). It is sufficient in this case to define one configuration (named "default") with an initial plan (lines 31-35). The initial plan simply references the plan for which an instance should be created (line 33).

Besides the introduction of the new plan we also need to make explicit what exactly a request_translation event means. For this purpose a new events section is introduced (lines 22-28). In this section the request_translation event is declared being a message event with one parameter (lines 23-27). This parameter specifies that its performative has the fixed value request. Whenever the agent receives a message it will search its declared events for the best matching event type. In this case all messages with performative request it will be treated as request_translation events.

  1 <!--
  2     Creating an initial plan.
  3     The agent has one initial plan (created when the agent is born)
  4     for translating words from English to German.
  5 -->
  6 <agent xmlns="http://jadex.sourceforge.net/jadex"
  7     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  8     xsi:schemaLocation="http://jadex.sourceforge.net/jadex
  9                         http://jadex.sourceforge.net/jadex-0.96.xsd"
 10     name="TranslationB1"
 11     package="jadex.tutorial">
 12 
 13     <plans>
 14         <plan name="egtrans">
 15             <body>new EnglishGermanTranslationPlanB1()</body>
 16             <waitqueue>
 17                 <messageevent ref="request_translation"/>
 18             </waitqueue>
 19         </plan>
 20     </plans>
 21 
 22     <events>
 23         <messageevent name="request_translation" direction="receive" type="fipa">
 24             <parameter name="performative" class="String" direction="fixed">
 25                 <value>jadex.adapter.fipa.SFipa.REQUEST</value>
 26             </parameter>
 27         </messageevent>
 28     </events>
 29 
 30     <configurations>
 31         <configuration name="default">
 32             <plans>
 33                 <initialplan ref="egtrans"/>
 34             </plans>
 35         </configuration>
 36     </configurations>
 37 
 38 </agent>

Replace all occurrences of "B1" in the Plan with "B2"

In contrast to the initial plan, the passive plan's body method is only invoked, when an event matches the plan's trigger. So use the method getInitialEvent() to retrieve the event that caused the execution. Because we know that only certain messages activate the plan the event can directly be cast to type jadex.runtime.IMessageEvent and the content can be retrieved. The infinite loop in the body should be discarded, because for each event a new plan instance is created, which only handles a single message.

Replace all occurrences of "B1" in the ADF file with "B2"

Modify the plan declaration in the ADF by removing the configurations section. Additionally a passive plan needs a trigger, that specifies under what circumstances a new plan instance is created. Therefore remove the waitqueue statement and add a new statement for the plan trigger:

<trigger>
	<messageevent ref="request_translation"/>
</trigger>

Instead of using the getInitialEvent() method to retrieve the English word, we use the the statement:

String eword = (String)getParameter("eword").getValue();

Add the new plan parameter with a message event mapping to the ADF:

<plan name="egtrans">
    <parameter name="eword" class="String">
        <messageeventmapping ref="request_translation.content"/>
    </parameter>
    <body>new EnglishGermanTranslationPlanB3()</body>
    <trigger>
        <messageevent ref="request_translation"/>
    </trigger>
</plan>

This plan should be used when the agent cannot find the word in its (currently very small) dictionary. In this case the online search plan will try to connect to a web dictionary and report the found translations. The address of a simple English-German dictionary is http://wolfram.schneider.org/dict/dict.cgi (you may use any other dictionary for this purpose if you are not afraid of parsing the result HTML page). To issue a query against this online database you need to create a URL and read the data from there as outlined below:

URL dict = new URL("http://wolfram.schneider.org/dict/dict.cgi?query="+eword);
BufferedReader in = new BufferedReader(new InputStreamReader(dict.openStream()));
String inline;
while((inline = in.readLine())!=null) {
    if(inline.indexOf("<td>")!=-1 && inline.indexOf(eword)!=-1) {
        try {
            int start = inline.indexOf("<td>")+4;
            int end = inline.indexOf("</td", start);
            String worda = inline.substring(start, end);
            start = inline.indexOf("<td", start);
            start = inline.indexOf(">", start);
            end = inline.indexOf("</td", start);
            String wordb = inline.substring(start, end==-1? inline.length()-1: end);
            wordb = wordb.replaceAll("<b>", "");
            wordb = wordb.replaceAll("</b>", "");
            System.out.println(worda+" - "+wordb);
        }
        catch(Exception e) {
            System.out.println(inline);
        }
    }
}
in.close();

Make the variable for the dictionary static and initialize it in a static block instead of in the constructor:

static {
    wordtable = new HashMap();
    wordtable.put("coffee", "Kaffee");
    wordtable.put("milk", "Milch");
    wordtable.put("cow", "Kuh");
    wordtable.put("cat", "Katze");
    wordtable.put("dog", "Hund");
}

Provide a public static method for testing if a word is contained in the dictionary:

public static boolean containsWord(String name) {
	return wordtable.containsKey(name);
}

Add the new online search plan to the plan declarations using a low priority:

<plan name="searchonline" priority="-1">
    <body>new SearchTranslationOnlineB4()</body>
    <trigger>
        <messageevent ref="request_translation"/>
    </trigger>
</plan>

Modify the applicability of the translation plan by introducing a precondition

<plan name="egtrans">
    <body>new EnglishGermanTranslationPlanB4()</body>
    <trigger>
        <messageevent ref="request_translation"/>
    </trigger>
    <precondition>
        EnglishGermanTranslationPlanB4.containsWord((String)$event.getContent())
    </precondition>
</plan>

Prepare the agent debugging by setting the debugging flag in a new properties section (at the end of the file) of the ADF to true, e.g. in the B4 ADF. Therefore the agent will be started in step mode and will only process events when the execution is manually requested in the introspector tool.

<properties>
    <property name="debugging">true</property>
</properties>

Note that you can also freeze the execution of the translation agent by setting execution mode to "step" in the tool. Using the debug flag is preferable when the agent directly starts with executing some actions and you want to observe it right from the start.

Start the translation agent of the last exercise from the Control Center.

Switch to the introspector perspective in the Control Center open an introspector for the translation agent and activate debugging by choosing the debugger tab and clicking the start button.

Use the Conversation Center to send some translation requests to the translation agent (as in B4).

Press the "step" button several times in the dispatcher and observe how an action from the agenda is executed. If the mode is "cycle" instead of step process event actions are executed in one step. Otherwise actions for all intermediate steps - searching applicable plans, selecting candidates from this list and scheduling the candidates for execution - are generated.

Replace all occurrences of System.out.println(..) to getLogger().info(..).

Add an imports section and the import statement for the java.logging classes to the imports section.

<imports>
    <import>java.util.logging.*</import>
</imports>

Introduce a properties section at the bottom of the ADF to specify the logging behavior. Insert the following code:

<properties>
    <property name="logging.level">Level.INFO</property>
    <property name="logging.useParentHandlers">true</property>
</properties>

These properties can be used to control the agent logging. The log-level decides what kind of log-outputs shall be considered for logging, according to the java.util.logging level hierarchy. Increasing the level value, e.g. to warning means, that only log-outputs at this or a higher level are conisdered by the logger. The useParentHandlers property can be used to turn on or off the standard console logging handler (per default it is set to true).

Create a new AddGermanWordPlanC1 as passive plan, that handles add-new-wordpair requests. In its body method, the plan should check whether the format is correct (using a java.util.StringTokenizer). If it is ok, it should retrieve the hashtable containing the word pairs via:

Map words = (Map)getBeliefbase().getBelief("egwords").getFact();

Assuming that the belief for storing the wordpairs is named "egwords". Now the plan has to check if the English word is already contained in the map (using words.containsKey(eword)) and if it is not contained, it should be added (using words.put(eword, gword)).

Modify the EnglishGermanTranslationPlanC1 so, that it uses the word table stored as single belief in the beliefbase. Additionally the plan has to check the newly introduced request format by using a java.util.StringTokenizer.

Add a static getDictionary() method to the EnglishGermanTranslationPlanC1. This method should return a hashmap with some wordpairs contained in it. Besides the static method you also need to declare a static variable for storing the dictionary:

protected static Map dictionary;
public static Map getDictionary(){
    if(dictionary==null)
    {
        dictionary = new HashMap();
        dictionary.put("milk", "Milch");
        dictionary.put("cow", "Kuh");
        dictionary.put("cat", "Katze");
        dictionary.put("dog", "Hund");
    }
    return dictionary;
}

The updated version of the translation agent ADF is outlined in Figure 4.1, “C1 XML ADF”. Note that the agent now has two plans named "addword" for adding a word pair to the database and "egtrans" for translating from English to German. The belief declaration is enclosed by a beliefs tag that denotes that an arbitrary number of belief declarations may follow. Of course, plans can create and delete beliefs (and belief sets) at runtime (see [Jadex User Guide] for more details). The ADF only defines the initially created beliefs, optionally with default fact(s). The belief for storing the wordtable is named "egwords" and typed through the class attribute to java.util.Map. The tag of this element is set to belief (in contrast to beliefset) denoting that only one fact can be stored. Further it is necessary to clarify which kinds of events trigger the plans. Therefore, the events section (lines 41-58) is extended to include a new request_addword event type which also matches request messages. To be able to distinguish between both kinds of events they are refined to match only messages that start with a specific content string (cf. lines 46-48 / 54-56).

  1 <!--
  2     Using the beliefbase with a belief.
  3     The agent stores its dictionary in a single-valued
  4     belief that can be accessed from a translation as well
  5     as from an add new word plan.
  6 -->
  7 <agent xmlns="http://jadex.sourceforge.net/jadex"
  8     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  9     xsi:schemaLocation="http://jadex.sourceforge.net/jadex
 10                         http://jadex.sourceforge.net/jadex-0.96.xsd"
 11     name="TranslationC1"
 12     package="jadex.tutorial">
 13 
 14     <imports>
 15         <import>java.util.logging.*</import>
 16         <import>java.util.*</import>
 17         <import>jadex.adapter.fipa.*</import>
 18     </imports>
 19 
 20     <beliefs>
 21         <belief name="egwords" class="Map">
 22             <fact>EnglishGermanTranslationPlanC1.getDictionary()</fact>
 23         </belief>
 24     </beliefs>
 25 
 26     <plans>
 27         <plan name="addword">
 28             <body>new EnglishGermanAddWordPlanC1()</body>
 29             <trigger>
 30                 <messageevent ref="request_addword"/>
 31             </trigger>
 32         </plan>
 33         <plan name="egtrans">
 34             <body>new EnglishGermanTranslationPlanC1()</body>
 35             <trigger>
 36                 <messageevent ref="request_translation"/>
 37             </trigger>
 38         </plan>
 39     </plans>
 40 
 41     <events>
 42         <messageevent name="request_addword" direction="receive" type="fipa">
 43             <parameter name="performative" class="String" direction="fixed">
 44                 <value>SFipa.REQUEST</value>
 45             </parameter>
 46             <parameter name="content-start" class="String" direction="fixed">
 47                 <value>"add english_german"</value>
 48             </parameter>
 49         </messageevent>
 50         <messageevent name="request_translation" direction="receive" type="fipa">
 51             <parameter name="performative" class="String" direction="fixed">
 52                 <value>SFipa.REQUEST</value>
 53             </parameter>
 54             <parameter name="content-start" class="String" direction="fixed">
 55                 <value>"translate english_german"</value>
 56             </parameter>
 57         </messageevent>
 58     </events>
 59 </agent>

Modify the EnglishGermanTranslationPlanC2 so, that it uses a query to search the requested word in the belief set. Therefore use an expression defined in the ADF: this.queryword = getExpression("query_egword"); (Assuming that the jadex.runtime.IExpression queryword is declared as instance variable in the plan) To apply the query insert the following code at the corresponding place inside the plan's body method: String gword = (String)queryword.execute("$eword", eword);

Modify the EnglishGermanAddWordPlanC2 so, that it also uses the same query to find out, if a word pair is already contained in the belief set. Apply the query before inserting a new word pair. When the word pair is already contained log some warning message. To add a new fact to an existing belief set you can use the method:

getBeliefbase().getBeliefSet("egwords").addFact(new jadex.util.Tuple(eword, gword));

For checking if a word pair is contained in the wordtable and for retrieving a wordpair from the wordtable a query expression will be used. Insert the following code into the ADF below the events section:

<expressions>
    <expression name="query_egword">
        select one $wordpair.get(1)
        from Tuple $wordpair in $beliefbase.egwords
        where $wordpair.get(0).equals($eword)
        <parameter name="$eword" class="String"/>
    </expression>
</expressions>

We don't cover the details of the query construction in this tutorial. If you are interested in understanding the details of the Jadex OQL query language, please consult the [Jadex User Guide].

Modify the ADF by defining a belief set for the wordtable. Therefore change the tag type from "belief" to "belief set" and the class from "Map" to "Tuple". Note that Tuple is a helper class that is located in jadex.util and has to be added to the imports section if you don't specify the fully-qualified classname. Remove the old Map fact declaration and put in four new facts each surrounded by the fact tag. Put in the same values as before (using new Tuple("milk", "Milch")) etc. for each fact.

Create a new passive ThankYouPlanC3 that prints out a congratulation message and the actual number of processed requests. The number of processed requests will be stored in a belief called "transcnt" in the ADF. Retrieve the actual request number by getting the fact from the beliefbase with:

int cnt = ((Integer)getBeliefbase().getBelief("transcnt").getFact()).intValue();

Modify the EnglishGermanTranslationPlanC3 to count the translation requests:

int cnt = ((Integer)getBeliefbase().getBelief("transcnt").getFact()).intValue();
getBeliefbase().getBelief("transcnt").setFact(new Integer(cnt+1));

Modify the ADF by defining the new ThankYouPlanC3 as passive plan (with the name thankyou in the ADF) in the plans section. Instead of defining a triggering event for this passive plan we define a condition that activates the new ThankYouPlanC3. A condition has the purpose the monitor some state of affair of the agent. In this case we want to monitor the belief "transcnt" and get notified whenever 10 translations have been requested. Insert the following in the plan's trigger:

<condition>$beliefbase.transcnt>0 &amp;&amp; $beliefbase.transcnt%10==0</condition>

This condition consists of two parts: This first transcnt>0 makes sure that at least one translation has been done and the second part checks if transcnt modulo 10 has no rest indicating that 10*x translations have been requested. The two parts are connected via a logical AND (&&), that has to be written a little bit awkwardly with the xml entities &&.

Define and initialize the new belief in the ADF by introducing the following lines in the beliefs section:

<belief name="transcnt" class="int">
    <fact>0</fact>
</belief>

Use the translation agent C3 as starting point and specify an agent argument in the ADF. Arguments are beliefs for which a value can be supplied from outside during the agent start-up. For declaring a belief being an agent argument simply mark it as exported by using the corresponding belief attribute exported="true". In this case we want the belief "transcnt" being the argument. Note that only beliefs not belief sets can be used as arguments.

Use the Starter to create instances of the new agent model. The Starter automatically displays textfields for all agent arguments and also shows the default model value (if any) that will be used when the user does not supply a value. Try entering different values into the textfield, what happens if you enter e.g. a string instead of the integer value that is needed here?

Start the agent with different argument values. Verfify, that the agent immediately invokes the congratulation plan if the initial number of translation requests is e.g. 10.

Start the translation agent from the last exercise. Before sending requests to the translation agent start the Jadex BDI introspector agent by selecting the translation agent in the AgentManager and activating the "Show Jadex Introspector" via the start button.

Use the Conversation Center to send translation or add-word requests to the translation agent.

Observe the belief change of the translation count, whenever a translation request is processed.

Observe the changes of the word pair belief set, whenever an add-word request is processed.

Use the example from C1 to see the difference in the representation of the word table as belief and belief set.

Declare two variables at the beginning of the plans:

String reply;  // The message event type of the reply.
String content; // The content of the reply message event.

Set both variables with respect to the success of the translation. In the success case set (assuming that gword and eword are variables for the English and German word respectively):

reply = "inform";
content = gword;

And in the failure case:

reply = "failure";
content = "Sorry, word could not be translated: "+eword;

Send an answer to the caller at the end of the event processing:

sendMessage(((IMessageEvent)getInitialEvent()).createReply(reply, cont));

Add the new message event types "inform" and "failure" to the ADF:

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

    <messageevent name="failure" direction="send" type="fipa">
        <parameter name="performative" class="String" direction="fixed">
            <value>SFipa.FAILURE</value>
        </parameter>
    </messageevent>
</events>

Test the agent and verify that it answers to the request messages by sending an answer message (for correct as well as for incorrect requests).

Create a new file TranslationD1.capability.xml with the skeleton code from Figure 5.1, “D1 XML ADF”. Now copy the definition of imports, plans, beliefs, events (including the newly defined ones from above) and expressions (in this case there are no goals) from TranslationC2.agent.xml into this file.

  1 <!--
  2     Translation capability.
  3 -->
  4 <capability xmlns="http://jadex.sourceforge.net/jadex"
  5     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  6     xsi:schemaLocation="http://jadex.sourceforge.net/jadex
  7                         http://jadex.sourceforge.net/jadex-0.96.xsd"
  8     name="TranslationD1"
  9     package="jadex.tutorial">
 10     ...
 11 </capability>

Modify the agent ADF (TranslationD1.agent.xml) by removing all plan and belief definitions. Instead insert a new section for using the new capability.

<capabilities>
    <capability name="transcap" file="TranslationD1"/>
</capabilities>

Note that here the type name is emloyed, but absolute and relative paths to (the model name of) the XML file can also be used.

Create the file FindEnglishSynonymsPlanD2.java as a passive plan which reacts on messages with performative type request and starts with "find_synonyms english". Therefore, you need to introduce the new message event type "find_synonyms" that fits for request messages that start with "find_synonyms english".

Create one query (called query_translate here) in the constructor for translating an English word (the query expression can be copied from the EnglishGermanTranslationPlanD2). Create another query (called query_find here) with the purpose to find all English words that match exactly a German word and are unequal to the given English word.

String find = "select $wordpair.get(0) " +
    "from Tuple $wordpair in $beliefbase.egwords " +
    "where $wordpair.get(1).equals($gword) && !$wordpair.get(0).equals($eword)";
this.queryfind	= createExpression(find, new String[]{"$gword", "$eword"},
    new Class[]{String.class, String.class});

In the body method, search for synonyms when the message format is correct, what means that the request has exactly three tokens. Use a StringTokenizer to parse the request and apply the translation query on the the given English word. When a translation was found, use the result to apply the query find for searching for synonyms. Create a reply and send back the found synonyms as an inform message in the success case and a failure message with a failure reason in the error case. The following code snippet outlines how the second query can be realized (eword is the English word for which synonyms are searched, gword is the German translation of the given English word):

query_find.setParameter("$gword", gword);
query_find.setParameter("$eword", eword);
List syns = (List)query_find.execute();

Create a new file TranslationD2.capability.xml by copying the capability from exercise D1.

Modify the belief set declaration of "egwords" by setting the belief set type="exported". Add some facts to the belief "egtrans" to have some synonyms present.

<beliefset name="egwords" class="Tuple" exported="true">
    <fact>new Tuple("milk", "Milch")</fact>
    <fact>new Tuple("cow", "Kuh")</fact>
    <fact>new Tuple("cat", "Katze")</fact>
    <fact>new Tuple("dog", "Hund")</fact>
    <fact>new Tuple("puppy", "Hund")</fact>
    <fact>new Tuple("hound", "Hund")</fact>
    <fact>new Tuple("jack", "Katze")</fact>
    <fact>new Tuple("crummie", "Kuh")</fact>
</beliefset>

Also use the exported attribute to make the "inform" and "failure" messages accessible, as we want to use these in the new synomyms plan.

Create a new file TranslationD2.agent.xml by copying the file from D1. Extend this definition by adding the new plan to the plans section and adding a referenced belief, that relates to the egwords belief from the capability. Note that the name of the referenced belief can be chosen arbitrarily (in this case we name it egwords, too). Additionally change the capability reference to the newly created TranslationCapabilityD2 and add the new message event type request_findsynonyms.

<beliefs>
    <beliefsetref name="egwords">
        <concrete ref="transcap.egwords" />
    </beliefsetref>
</beliefs>

<plans>
    <plan name="find_synonyms">
        <body>new FindEnglishSynonymsPlanD2()</body>
        <trigger>
            <messageevent ref="request_findsynonyms"/>
        </trigger>
    </plan>
</plans>

<events>
    <messageevent name="request_findsynonyms" direction="receive" type="fipa">
        <parameter name="performative" class="String" direction="fixed">
            <value>SFipa.REQUEST</value>
        </parameter>
        <parameter name="content-start" class="String" direction="fixed">
            <value>"find_synonyms english"</value>
        </parameter>
    </messageevent>

    <messageeventref name="inform">
        <concrete ref="transcap.inform"/>
    </messageeventref>

    <messageeventref name="failure">
        <concrete ref="transcap.failure"/>
    </messageeventref>
</events>

Remove the EnglishGermanAddWordPlan to keep the agent simple.

Create a new initial ProcessTranslationRequestPlanE1 that reacts on all incoming messages with performative type request and creates subgoals for all (correctly formatted) requests. Because we are using a service plan implement the body method with an infinite loop and start waiting for a message to process. Assuming that the plan has extracted the action (translate), the language direction (english_german or english_french) and the word(s) from an incoming message the following code can be used to create, dispatch and wait for a subgoal:

IGoal goal = createGoal("translate");
goal.getParameter("direction").setValue(dir);
goal.getParameter("word").setValue(word);
try {
    dispatchSubgoalAndWait(goal);
    getLogger().info("Translated from "+goal.getName()+" "+
        word+" - "+goal.getParameter("result").getValue());
}
catch(GoalFailureException e) {
    getLogger().info("Word is not in database: "+word);
};

After the goal returns successfully, read the result from the goal and log some translation message.

Modify the EnglishGermanTranslationPlanE1 so that it can handle a translation goal with direction="english_german". Therefore, the body method has to be adapted so that it extracts the word from the plan parameter mapping (using getParameter("word").getValue()). After having performed the query on the wordtable, set the result using getParameter("result").setValue(gword). When no translation could be retrieved, the plan has failed and this should be indicated calling the fail() method (which throws a plan failure exception).

Create a new EnglishFrenchTranslationPlanE1 as a copy of the EnglishGermanTranslationPlanE1 and make sure to work on a new wordtable belief efwords. Modify the query_word and the body method accordingly.

Add the ProcessTranslationRequestPlanE1 to the ADF as initial plan with a waitqueue for translation requests. Add an configurations section and declare a configuration with an initial plan for the ProcessTranslationRequestPlanE1.

Adapt the plan head declarations of both plans to include plan parameters and the new triggers. The plan parameters are directly mapped to the corresponding goal parameters so that the input as well as the result are automatically transferred from resp. to the goal. In addition, both translation plans should handle exactly suitable translation goals. In the following the modified plan head for the EnglishGermanTranslationPlanE1 is depicted:

<plan name="egtrans">
    <parameter name="word" class="String">
        <goalmapping ref="translate.word"/>
    </parameter>
    <parameter name="result" class="String">
        <goalmapping ref="translate.result"/>
    </parameter>
    <body>new EnglishGermanTranslationPlanE1()</body>
    <trigger>
        <goal ref="translate">
            <match>"english_german".equals(
                   $goal.getParameter("direction").getValue())</match>
        </goal>
    </trigger>
</plan>

Introduce a new goals section and declare the achieve goal for translations:

<goals>
    <achievegoal name="translate">
        <parameter name="direction" class="String"/>
        <parameter name="word" class="String"/>
        <parameter name="result" class="String" direction="out"/>
    </achievegoal>
</goals>

Modify the ADF by adjusting the plan declarations to include the new EnglishFrenchTranslationPlanE1 and exclude the add word plan. Additionally a new belief efwords has to be declared in the beliefs section:

<beliefset name="efwords" class="Tuple">
    <fact>new Tuple("milk", "lait")</fact>
    <fact>new Tuple("cow", "vache")</fact>
    <fact>new Tuple("cat", "chat")</fact>
    <fact>new Tuple("dog", "chien")</fact>
</beliefset>

Introduce a second query for the new belief efword in the expressions section of the ADF:

<expression name="query_efword">
    select one $wordpair.get(1)
    from Tuple $wordpair in $beliefbase.efwords
    where $wordpair.get(0).equals($eword)
    <parameter name="$eword" class="String" /> 
</expression>

Modify the trigger of both translating plans so, that they react on every translation goal by removing the lines:

<match>"english_german/english_french".equals(
$goal.getParameter("direction").getValue())</match>

Having done this causes the translation plans to react on every translation goal, even when they can't handle the translation direction or language.

Introduce a new plan parameter for the translation direction and supply it with a corresponding goal mapping:

<parameter name="direction" class="String">
    <goalmapping ref="translate.direction"/>
</parameter>

Modify the translation plans so that they check the translation direction in the body method before translating. When the direction cannot be handled, they should indicate that they failed to achieve the goal by calling the fail() method. Addtionally the plans should log or print some warning message, when they fail to process a goal:

if("english_french".equals(getParameter("direction").getValue()))
    // print out some message and fail() if this is not the english-french plan

You need not explicitly set the BDI-retry flag of the goal, because in the standard configuration for goals all BDI-mechanisms (retry, exclude and meta-level reasoning) are enabled. This means, that a failed goal will be retried by different plan candidates until it succeeds or all possible candidates have failed to handle the goal and it is finally failed.

This plan has the purpose to delete an entry from the wordtable.

Create a constructor with a String parameter. This parameter will tell the plan in which belief set an entry has to be deleted. Save the parameter in an object variable called "beliefsetname".

In the body method use the following code to delete one entry from the set:

Object[] facts = getBeliefbase().getBeliefSet(beliefsetname).getFacts();
getBeliefbase().getBeliefSet(beliefsetname).removeFact(facts[0]);

Remove the FindSynonymsPlanD2 from the plans section and remove the event section completely.

Add the RemoveWordPlanE3 to the plans section:

<plan name="remegword">
    <body>new RemoveWordPlanE3("egwords")</body>
    <trigger>
        <goal ref="keepstorage"/>
    </trigger>
    <precondition>$beliefbase.egwords.length &gt; 0</precondition>
</plan>

Add the following beliefs to the belief section:

<beliefsetref name="egwords">
    <concrete ref="transcap.egwords" />
</beliefsetref>
<belief name="maxstorage" class="int">
    <fact>8</fact>
</belief>

Add a new maitain goal declaration to the goals section:

<maintaingoal name="keepstorage" exclude="when_failed">
    <maintaincondition>
        $beliefbase.egwords.length &lt;= $beliefbase.maxstorage
    </maintaincondition>
</maintaingoal>

Create a configurations section with one configuration that creates a maintain goal instance on startup.

<configurations>
    <configuration name="default">
        <goals>
            <initialgoal ref="keepstorage"/>
        </goals>
    </configuration>
</configurations>

This class has the purpose to show the already performed actions in a table. As member variable the table model is needed to be able to refresh the data in response to update notifications.

protected DefaultTableModel tadata;

In the constructor the table and its model should be created and added to the frame:

String[] columns = new String[]{"Action", "Language", "Content", "Translation"};
this.tadata = new DefaultTableModel(columns, 0);
JTable tatable = new JTable(tadata);
JScrollPane sp = new JScrollPane(tatable);
this.getContentPane().add("Center", sp);
this.pack();
this.setVisible(true);

Finally, for updating the gui a method is needed:

public void addRow(final String[] content){
    SwingUtilities.invokeLater(new Runnable(){
        public void run(){
            tadata.addRow(content);
        }
    });
}

Create a new GUIPlanF1 plan that has the purpose to create the gui and update it accordingly. The plan should create the gui in its constructor. In its body method it should wait in an endless lopp for internal events of type gui_update:

IInternalEvent event = waitForInternalEvent("gui_update");

Whenever such an event occurs the plan has to invoke the addRow() method of the gui whereby the update information is contained in a parameter named content within the internal event, accessible by:

event.getParameter("content").getValue();

In addition the plan's aborted method can be used to close the gui automatically when the agent is terminated:

public void aborted(){
    SwingUtilities.invokeLater(new Runnable(){
        public void run(){
            gui.dispose();
        }
    });
}

Modify the EnglishGermanTranslationPlanF1 so that it produces an internal event after translation processing:

IInternalEvent event = createInternalEvent("gui_update");
event.getParameter("content").setValue(new String[]{action, dir, eword, gword});
dispatchInternalEvent(event);

The addword plan and event declarations are not used and can be removed for clarity.

Modify the ADF so, that it contains the declaration for the new gui plan without specifying a trigger:

<plan name="gui">
    <body>new GUIPlanF1()</body>
</plan>

Introduce the declaration of the new gui_update event within the events section:

<internalevent name="gui_update">
    <parameter name="content" class="String[]"/>
</internalevent>

Add an configurations section with one configuration that creates an initial gui plan:

<configurations>
    <configuration name="default">
        <plans>
            <initialplan ref="gui"/>
        </plans>
    </configuration>
</configurations>

Start the agent and send several translation requests to the agent. Observe if the gui displays all the translation requests.

Add the following to the imports section:

<import>
   jadex.planlib.*
   jadex.adapter.fipa.*
</import>

Add the new not-understood plan to the plan declarations:

<plan name="notunderstood">
    <body>new NotUnderstoodPlan()</body>
    <trigger>
        <messageevent ref="any_message"/>
    </trigger>
</plan>

Add the new any_message event which matches all kinds of messages and the not understood message that will be sent by the NotUnderstoodPlan to the event declarations:

<messageevent name="any_message" direction="receive" type="fipa"/>
<messageevent name="not_understood" direction="send" type="fipa">
    <parameter name="performative" class="String" direction="fixed">
        <value>SFipa.NOT_UNDERSTOOD</value>
    </parameter>
</messageevent>

Besides the any_message for receiving arbitrary kinds of messages and the not_understood message which will be send by the not understood plan, we also need message declarations for the other messages to be sent be our agent. Here we need inform and failure messages that will be used by the modified translation plan:

<messageevent name="inform" direction="send" type="fipa">
    <parameter name="performative" class="String" direction="fixed">
        <value>SFipa.INFORM</value>
    </parameter>
</messageevent>
<messageevent name="failure" direction="send" type="fipa">
    <parameter name="performative" class="String" direction="fixed">
        <value>SFipa.FAILURE</value>
    </parameter>
</messageevent>

Include the DF capability in the ADF to be used:

<capabilities>
    <capability name="dfcap" file="jadex.planlib.DF"/>
    <capability name="transcap" file="TranslationD1"/>
</capabilities>

Create a reference for the df_keep_registered goal to make it locally available:

<goals>
    <maintaingoalref name="df_keep_registered">
        <concrete ref="dfcap.df_keep_registered"/>
    </maintaingoalref>
</goals>

Create a configurations section with one configuration. In this configuration an initial goal for the df registration should be provided. The agent description that is used for the registration is provided as initial value of the "description" parameter of the df_keep_registered goal:

<configurations>
    <configuration name="default">
        <goals>
            <initialgoal ref="df_keep_registered">
                <parameter ref="description">
                    <value>
                        SFipa.createAgentDescription(null,
                        SFipa.createServiceDescription("service_translate",
                        "translate english_german", "University of Hamburg"))
                    </value>
                </parameter>
                <parameter ref="leasetime">
                    <value>20000</value>
                </parameter>
            </initialgoal>
        </goals>
    </configuration>
</configurations>

Start the agent and open the DF GUI. Observe if an entry for the agent exists. Use the DF GUI to deregister your agent (via popup-menu) and observe what happens after a while. Note that when you want to register the agent at a remote df, you only need to slightly modify your initial goal description by adding parameter values for the DF AgentIdentifier and address.

Create a new agent called UserAgent by creating an ADF and one plan called EnglishGermanTranslateSentencePlanF4. In the ADF define the translate sentence plan with an appropriate waitqueue that handles message events of the new type request_translatesentence. The new request_translatesentence message event should be declared to match request messages that start with "translate_sentence english_german". Additionally incorporate the DF and Protocols capabilities in the capabilities section and create references for the rp_initiate (request protocol initiate) and df_search goals. This agent uses the df search goal to find a translation agent and the request goal to communicate in a similar standard way with the translation agent.

<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="UserF4"
    package="jadex.tutorial">

    <imports>
        <import>jadex.planlib.*</import>
        <import>jadex.adapter.fipa.*</import>
        <import>java.util.logging.*</import>
    </imports>

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

    <goals>
        <achievegoalref name="rp_initiate">
            <concrete ref="procap.rp_initiate"/>
        </achievegoalref>
        <achievegoalref name="df_search">
            <concrete ref="dfcap.df_search"/>
        </achievegoalref>
    </goals>

    <plans>
        <plan name="egtrans">
            <body>new EnglishGermanTranslateSentencePlanF4()</body>
            <waitqueue>
                 <messageevent ref="request_translatesentence"/>
            </waitqueue>
        </plan>
    </plans>

    <events>
        <messageevent name="request_translatesentence" direction="receive" type="fipa">
            <parameter name="performative" class="String" direction="fixed">
                <value>SFipa.REQUEST</value>
            </parameter>
            <parameter name="content-start" class="String" direction="fixed">
                <value>"translate_sentence english_german"</value>
            </parameter>
        </messageevent>
        <messageevent name="inform" direction="send" type="fipa">
            <parameter name="performative" class="String" direction="fixed">
                <value>SFipa.INFORM</value>
            </parameter>
        </messageevent>
        <messageevent name="failure" direction="send" type="fipa">
            <parameter name="performative" class="String" direction="fixed">
                <value>SFipa.FAILURE</value>
            </parameter>
        </messageevent>
    </events>

    <configurations>
        <configuration name="default">
            <plans>
                <initialplan ref="egtrans"/>
            </plans>
        </configuration>
    </configurations>
</agent>

The body method of this plan should adhere to the following basic structure:

public void body()
{
    protected AgentIdentifier ta;    
    ...

    while(true)
    {
        // Read the user request.
        IMessageEvent mevent = (IMessageEvent)
            waitForMessageEvent("request_translatesentence");

        // Save the words of the sentence.
        // Process the message event here.
        ...        
        String[] words = ...;
        String[] twords = ...;
        ...

        // Search a translation agent.
        while(ta==null) // ta is the instance variable for the translation agent
        {
            // Create a service description to search for.
            // You can use the ServiceDescription from the ADF of exercise F3.
            // Use a df-search subgoal to search for a translation agent
            // Save the translation agent in the variable ta
            // If no translation agent could be found waitFor() some time and try again
        }

        // Translate the words.
        for(int i=0; i<words.length; i++)
        {
            IGoal tw = createGoal("rp_initiate");
            tw.getParameter("content").setValue("translate english_german "+words[i]);
            tw.getParameter("receiver").setValue(this.ta);
            try
            {
                dispatchSubgoalAndWait(tw);
                twords[i] = (String)tw.getParameter("result").getValue();
            }
            catch(GoalFailureException gfe)
            {
                twords[i] = "n/a";
            }
        }

        // Send the reply with the translation of the whole sentence
        // to the caller (the user agent)
        // ...
    }
}

Start a translation agent and a user agent. Now send a translate sentence request to to the user agent, which will answer with a message in which the translated sentence is contained, e.g."translate_sentence english_german dog cat milk".

Declare the ServerSocket as attribute within the plan

protected ServerSocket server;

Create a constructor which takes the server port as argument and creates a the server within it:

try {
    this.server	= new ServerSocket(port);
}
catch(IOException e) {
    throw new RuntimeException(e.getMessage());
}
getLogger().info("Created: "+server);

Additionally create a close method that can be used for shutting down the server socket:

public void close() {
    try {
        getExternalAccess().getLogger().info("Closing: "+server);
        server.close();
    }
    catch(IOException e) {
        e.printStackTrace();
    }
}

In the body simply start a new thread that will handle client request in the run method. Additionally add an agent listener that gets invoked when the agent will be terminating. In this case the server is shut down:

new Thread(this).start();
getScope().addAgentListener(new IAgentListener() {
    public void agentTerminating(AgentEvent ae) {
        close();
    }
}, false);

In the threads run method create and dispatch goals for every incoming request:

while(true)
{
    Socket    client    = server.accept();
    IGoal goal = getExternalAccess().getGoalbase().createGoal("translate");
    goal.getParameter("client").setValue(client);
    getExternalAccess().getGoalbase().dispatchTopLevelGoal(goal);
}

Extract the socket from the goal and read the English word:

Socket client = (Socket)getParameter("client").getValue();
BufferedReader in = new BufferedReader(new InputStreamReader(client.getInputStream()));
String request = in.readLine();
// Read the word to translate from the input string

Translate the word as usual by using the query

Send back answer to the client:

PrintStream out = new PrintStream(client.getOutputStream());
out.print("HTTP/1.0 200 OK\r\n");
out.print("Content-type: text/html\r\n"); out.println("\r\n");
out.println("<html><head><title>TranslationG1 - "+eword
    +"</title></head><body>");
out.println("<p>Translated from english to german: "+eword+" = "+gword+".");
out.println("</p></body></html>");
client.close();

The addword plan and event declarations are not used and can be removed for clarity.

Introduce the translation goal type:

<achievegoal name="translate">
    <parameter name="client" class="java.net.Socket"/>
</achievegoal>

Introduce the new plan for setting up the server and start the plan initially:

<plan name="server">
    <body>new ServerPlanG1(9099)</body>
</plan>
...
<configurations>
    <configuration name="default">
        <plans>
            <initialplan ref="server"/>
        </plans>
    </configuration>
</configurations>

Modify the trigger of the translation plan to react on translation goals and add a parameter for the client:

<plan name="egtrans">
    <parameter name="client" class="Socket">
        <goalmapping ref="translate.client"/>
    </parameter>
    <body>new EnglishGermanTranslationPlanG1()</body>
    <trigger>
        <goal ref="translate"/>
    </trigger>
</plan>

Start the agent and open a browser to issue translation request. This can be done by entering the server url and appending the word to translate, e.g. http://localhost:9099/dog. The result should be printed out in the returned web page.