The Jadex Control Center provides different graphical areas that are partly customized by some of the plugins. Basically the JCC offers:

The settings dialog available from the "File" menu is used to set up diverse options for the Jadex platform and agent loading process. It is shown below in the Figure 2.2, “Platform settings dialog” and includes following options.

Expression evaluation.  Jadex provides several options how to evaluate the Java expressions contained in ADFs. The built in interpreter features fast loading times, but limited runtime performance, as the Java statements have to be interpreted on every access. The interpreter allows to restart plan classes, when they have changed. This allows to try out a change in the Java code without having to restart the platform. Note, that this feature should only be used for debugging, as it slows down the system. The alternative to the interpreter is the on-the-fly compiler based on Janino, which is available from the Jadex homepage as an add-on. In order to further speed up the process of agent loading and execution, the compiled expressions may be saved directly to a cache file. The options "Write to file-cache enabled" and "Read from file-cache enabled" activate this behavior.

XML model loading.  The XML model loading section allows to influence how Jadex loads agent and capability models. When integrity checking is enabled all loaded agent and capability models are checked against a set of consistency rules (syntax of Java expressions, validity of cross references between goals and plans, etc.). The platform will refuse to start invalid agent models. The feature can be disabled to improve performance in deployed applications. Furthermore it can be determined if model caching should be used. In case it is enabled Jadex will load a model only once from an XML file and will afterwards use a master Java model from which new model instances are cloned. With the auto-refresh option it can be specified if Jadex should always check the timeliness of the files. When turned off files will always be loaded from cache regardless of their timeliness.

Generic settings.  The gereric settings allow for customizing several minor platform features. If the welcome message printed to the console shortly after start-up is unwanted it can be turned off here. Additionally the exit behaviour can be specified. The default behaviour when closing the JCC user interface is that the user is asked if he wishes to shutdown the platform also. To avoid this prompting it can be set to automatically shutdown the platform or keep it alive without asking.

Figure 2.2. Platform settings dialog

View refresh.  In addition to the standard start and stop functionalities the model tree also supports more advanced features. If not explicitly turned off in the "Model" menu the tree is automatically refreshed in certain time intervals. This means that changes on hard-disk are immediately reflected within the model tree. You can also initiate a refreshment directly by clicking the button.

Integrity checking.  In addition all models found in the tree are automatically checked for integrity if this feature isn't turned off in the "Model" menu. This feature allows to effortlessly locate corrupt agent and capability files in the project. If a corrupt file is found, the file as well as all packages up to the root are marked as corrupt. A corrupt entity is displayed with a red bolt .

The Running Agents panel shows all currently alive agents of the platform. For each agent its name and the first transport address is shown. The following actions are available in this view:

In the Model Panel details of a loaded agent or capability are shown. A model can be loaded either by selecting a file from the Model Tree or by using the "..." button to browse for a certain file. For a selected model several properties are presented:

If an agent model could be loaded without errors you can start a new agent instance of this model simply by hitting the Start button. If you changed a model you can load it from model again with the Reload button. The Reset button can be used to clear all fields and discard all loaded models from cache. Finally, the help button allows to invoke the online JavaHelp.

The center view is split-up into three different panels. The uppermost "Registered Agent Description" panel shows all agent descriptions of the selected DF agent, i.e. if no DF agent is selected no registrations will be visible. For each registered agent description, the agent name, the lease time, the contained services as well as a overview about the used ontologies, languages and protocols are shown.

Below the agent description panel the "Registered Services" panel shows agent services in more detail. For each service its name, type, ownership as well as a short info about ontologies, languages and protocols is displayed. Additionally an entry exists for the containing agent description making clear to which of the agent descriptions a service belongs. Per default the service descriptions of all agent descriptions are presented. Selecting an agent description in the "Registered Agent Description" panel restricts the services presented in the lower panel to those that belong to one of the selected agent descriptions.

In the lowermost panel one service is shown with all its properties, i.e. especially all contained ontologies, languages, protocols and properties can be inspected. The selection of the service description that should be made visible in the "Service Properties" panel has to be done in the "Registered Services" panel (here only a single selection is allowed).

Besides viewing the registered agent descriptions and services the DF browser can also be used for deleting obsolete agent descriptions. This can be done by selecting the service (or services) in the agent description panel and activating the remove operation via the popup menu or via the corresponding button in the toolbar.

The send tab will always be present and allows to compose a new message for sending. The message format follows the FIPA standards (see FIPA ACL Message Structure Specification and [Jadex User Guide]). You can choose an appropriate performative for your message by using the drop down list of available performatives. The sender is by default initialized with the name of the control center agent. The receivers specify which agents will receive the message. If answers to the message should not be sent to the original sender (default) you can provide an optional reply-to agent. The agent identifiers for sender, receivers, and reply-to are selected using a separate dialog, which can be accessed by clicking the "..." button besides the text field. To clear the agent identifiers click on the "x" button to the right of the "..." button.

The other attributes of the message can be entered as plain strings. For the protocol you can also select one of the protocol types predefined by FIPA. Normally, only a few slots need to be filled in for a message. See e.g. Figure 5.1, “Conversation center overview”, which shows a message commonly used in the [Jadex Tutorial]. After composing the message it can be sent simply by hitting the "Send" button. If it was successfully sent, a copy of the message will be placed in the sent messages list.

You can later reopen the message in a new tab by double-clicking it in the list. To resend the message without changes click the "Resend" button in the newly opened tab. If you wish to change the message before resending it use the "Edit" button instead, which will fill in the slots of the message in the send tab, so you can edit it.

5.1.1. Agent Selector Dialog

The left list of the agent selector dialog (see Figure 5.2, “Agent selector dialog”) shows the agents currently running on the platform. You can double-click on an agent from the list to select it. The upper list on the right side shows the currently selected agent(s). The buttons below the list allow to add a new agent identifier from scratch, which can be edited below the list. When you finished selecting agents, hit the "Ok" (or "Cancel") button at the bottom of the dialog.

Figure 5.2. Agent selector dialog

The messages received by the conversation center agent are placed in the "Received Messages" list. Double-clicking on a received message will open it as a new tab (see Figure 5.3, “A received message”). When you want to reply to the message, click on the "Reply" button. The user interface will switch to the send panel, and fill in all slots (receiver, conversation-id, etc.) based on the received message. You can then edit the reply message and hit the "Send" button. If you want to get rid of the tab of a received message, you can use the "Close" button next to the "Reply" button.

Figure 5.3. A received message

Three base panels show the beliefs (), goals (), and plans () of the selected agent. They are very similar in their usage (see Figure 6.2, “The Beliefs Panel of Introspector”). All elements are shown in a tree structure representing the containment hierarchy of the elements in the capabilities of the agent.

Figure 6.2. The Beliefs Panel of Introspector

The different elements of the agent are shown with different icons as explained in Table 6.1, “Introspector Base Panel Elements”. For each element the most important attributes are displayed directly in the tree/table structure. The content of the base panels will automatically be updated when changes occur inside the agent.

The tree component allows nodes to be closed to focus on interesting subsets of the agent's functionality. The column widths can be (auto-) adjusted by dragging or double-clicking between the column headers. The table headers also provide a popup->menu (opened with right-click) that allows to hide some of the columns for better readability. You can double click on the elements to see more detailed information. The details panel is not automatically updated, you may have to double click the element again, to see up to date information.

You can to some extent manipulate the elements shown in the base panels. E.g. you can alter the values of facts in the beliefbase. Double click on the fact value you wish to change (in the value column), and then enter the new value as Java expression (i.e "text" for a string value). The expressions are evaluated using the imports as specified in the ADF (of the corresponding capability) therefore you can write expressions just as you would do that in a <fact> tag of the ADF. In addition, popup menus are available e.g. to remove beliefs, terminate plans or change the state of goals.

Some options are available to influence the appearance of the base panels (see Table 6.2, “Introspector Base Panel Options”).

The resize icon allows to auto-adjust the widths of the table columns to fit the displayed content. The next two icons are concerned with the presentation of removed elements. Because the final state of a goal or a plan may be of interest after the goal has been dropped or the plan has terminated, the panels have an option not to remove those elements from the representation, but just visually mark them as removed. This is especially useful for debugging your agents, e.g. in conjunction with the debugger view described in the next section. To flush removed beliefs, goals and plans from the representation, you can use the waste bin icon.

The last icon is only available in the goalbase panel. It allows to switch between the goalview and the planview representation of the agent's current goals. The goalview, shown by default, displays only the goals and goal references in the context of their containing capabilities. In the planview the global goal-plan hierarchy of the agent is displayed. This means that the causal relationships of the agent's goal structure are visible. Starting with some top-level element, which can be a top-level goal or plan, it is shown which subelements are connected with it, i.e. which plan is currently executed for a goal, which subgoal the plan has dispatched and so forth. Both views are compared in Figure 6.3, “Goalview and planview”. In the planview you can see that the move_dest#11 achieve goal was actually created by a plan as a subgoal of the carry_ore#1 achieve goal.

Figure 6.3. Goalview and planview

The debugger panel allows watching the internal processing inside an agent. The window is made up of the agenda area, the agenda control area in the middle and the details view at bottom (see Figure 6.4, “The Debugger Panel of Introspector”.

Figure 6.4. The Debugger Panel of Introspector

The agenda contains all current action entries of the agent, whereby entries in light-grey denote already processed actions. In addition it can be seen whether entries currently have a valid precondition and thus can subsequently be executed; otherwise they are marked as (invalid). Such invalid actions will not be executed, but just ignored by the execution mechanism. To see some more information about an agenda action you can double-click on it and inspect its values in the details view. In addition to observing the agent's internal behavior the tool also allows you to control the agenda execution by performing actions in step mode. If the execution mode is set to "step" or "cycle" you can use the "forward" button to execute as many steps as shown in the "execute <n> agenda actions" choice. The difference between step and cycle mode concerns only the execution of ProcessEventActions that are decomposed to finer-grained sub steps (FindApplicableCandidatesAction, SelectCandidatesAction and ScheduleCandidatesAction) when the "step" mode is activated. Therefore, the step mode allows you to examine the details of the BDI plan selection process what can be helpful in understanding and explaining unexpected application behavior. The "open steps" status bar shows the progress of the action execution by highlighting the number of steps the agent still has to perform whereas in the the "processing state" line it can be seen if a step is currently requested or has been finished.

The main window of the tracer agent may be seen in Figure 7.1, “Tracer Main Window”.

Figure 7.1. Tracer Main Window

The traces presented above are from the Blocksworld example. In order to indicate a type of traces, they are marked with icons and their different meaning is explained in Table 7.1, “Information logged by the tracer”:

The tracer perspective is split into four views including a tree view of agents and traces, a tabular view of traces, tracing settings and a 2D trace space exploring panel.

7.1.1. Trace Tree

At the left there is a tree view showing all agents known to the tracer. The meaning of a particular icon depicting an agent is shown in Table 7.2, “State of an agent”. Descending from the BDI agents, all traces are linked beneath nodes identified to be their cause.

Table 7.2. State of an agent

	The agent is ignored by the tracer.
	The agent sends its traces to the tracer.
	The agent has died.

The functionality provided by the tree popup menu is similar to the functionality from the Agent menu (Section 7.2.1, “Agent Menu”) and concerns the currently selected trace or agent. In the case of an agent the user may choose to observe it and to adjust the trace filter and history limit (Filter). The other options allow to show or hide traces in the graph or table. With the last menu item the trace or the agent may be removed from the tracer perspective.

Figure 7.2. Tree Popup Menu

7.1.2. Trace Table

On the right side there are three views. The upper one in the middle shows a tabular view of the traces, as can be seen in Figure 7.3, “Trace Table”:

Figure 7.3. Trace Table

The traces are ordered in the sequence they arrive. The table shows information like a unique trace id, the agent name, the event name, The event name and the content are closely related and explain which kind of event occurrence has happened. The cause describes the reason for the event occurrence and the time shows when the event has happened.

The user may select traces in the table based on different criteria, remove them from the table, show them in the graph panel or delete from the tracer perspective. All the fuctionality is accessible under the Table Menu (Section 7.2.2, “Table Menu and Tracing Settings”) and a corresponding popup menu.

The view on the upper right side, offers some tracing settings, as can be seen in Figure 7.4, “Tracing Settings”:

Figure 7.4. Tracing Settings

Check boxes let the user specify what to trace and above the number of traces to show can be chosen from a pull down menu. The changes can be applied by the button “apply” and the other button labled with “clear” clears the trace table.

The menu provides access to functions concerning the tracer agent itself and the BDI agents analyzed. Functions corresponding to the tabular view and the 2D graph view are also accessible from here.

7.2.1. Agent Menu

Under this menu (cf. Figure 7.5, “Agent Menu” concerning agents the user has the option to:

• Observe - an agent. This will tell the agent to send its traces to the tracer.

• Observe all - will cause all BDI agents (known to the tracer) to send their data.

• Ignore - an agent. Has the complementary effect to Observe.

• Ignore all - is the reverse of Observe all.

• Ignore at first - causes the tracer to ignore all newly occurring agents.

• Show in graph - tells the tracer to show the traces of an agent in the 2D graph as soon as they arrive.

• Hide from graph - removes all agent traces from the 2D graph.

• Show in table - tells the tracer to show the traces of an agent in the table.

• Hide from table - removes all agent traces from the table.

• Delete - removes the agent and corresponding traces from all views.

• Delete dead agents - removes all dead agents and their traces from all views.

• Filter - shows a filter dialog for the current selected agent.

• Default filter - shows a filter dialog for a prototypical agent all new agents will inherit their properties from.

Figure 7.5. Agent Menu

7.2.2. Table Menu and Tracing Settings

The Table menu (cf. Figure 7.6, “Table Menu” ) provides functionality concerning the table view. Following options are available to the user:

• Select causes - selects immediate causes of selected traces.

• Select effects - selects the immediate effects.

• Show in graph - shows all selected traces in the 2D graph.

• Hide in graph - hides selected traces from the 2D graph.

• Remove - removes traces from the table.

• Delete - deletes the traces and removes them from all views.

• Scroll - tells if the table should be scrolled, when new traces arrive.

Figure 7.6. Table Menu

7.2.3. Graph Menu

The tracer graph menu is accessible from the main menu and as popup in the graph view (cf. Figure 7.7, “Graph Popup Menu” ). It provides access to following functions:

• Show - is used to show actions, beliefs or messages connected to trace nodes already shown in the graph. If a trace is selected, the user may choose to show the causes and effects of that trace.

• Hide - hides actions, beliefs or messages from the graph view. A single trace, its causes or its effects may be removed from the view.

• Expand - will expand the trace by one level of the causes or effects.

• Collapse - will shrink and hide the traces around the selected one.

• Delete - will remove the trace from all views in the tracer.

• Join Beliefs - may be used to collapse all belief access nodes into a single one.

• Join Messages - will join the send and receive events of a message with an edge, therefore establishing connections between agents.

• Labels - this check-box indicates that the traces in the graph should be shown with thier corresponding labels instead of an anonymous icon. The labels are truncated by length and a selected trace is always shown with its label.

Figure 7.7. Graph Popup Menu

Below a more detailed description of the panels and their usage is given.

8.1.1. Model Tree Panel

The model tree shows all agents of your current project and allows for adding/removing test agents to the test suite. The tree automatically searches for testable agents and marks them visually . Each source folder that contains at least one testable agent changes its icon to red and green and the packages that contain tests change the red and green icon to . For adding resp. removing testable agents to/from the test suite different options are available:

• Adding a single test case can be done by double-clicking the testable agent.

• Activating the popup menu on a single test case agent allows for adding or removing the selected test case.

• Activating the popup menu on a test case folder allows for adding or removing recursively all contained test cases.

• After having selected an agent or a folder adding or removing these items can also be done by using the corresponding buttons from the tool bar.

In the following screenshot the popup for a folder in the model tree is shown:

Figure 8.2. Right-Click in Model Tree

8.1.2. Settings Panel

The test suite settings panel offers information about the current test suite.

Figure 8.3. The test suite settings panel

All the testable agents of the test suite appear in the list. With the x-symbol you can remove testcases, with the "+"-symbol you can add new test suites and enter their name manually.

The checkbox below the list allows to turn on or off checking for duplicates. If duplicates are forbidden the addition of testcases that are already contained in the list will have no effect. Otherwise you can add the same testcase more than once.

The testcase timeout option allows for specifying the maximum amout of time that a single test agent is permitted to be executed. If the test agent does not return the test results within this timeframe it will be considered as failed. The default timeout for testcases is 20000 ms and can be adapted if necessary, i.e. if one of test agents needs a longer test execution time.

The testcase cuncurreny setting can be used to determine how many test agents should be executed at the same time. By setting the concurrency to 1 a sequential execution can be enforced. In general, the concurrent execution has several consequences. One important pragmatic aspect is that the execution will be much faster as the center can always execute some test and needs not to wait for the result of one specific test. On the contrary the parallel execution of tests also may lead to non-deterministic test results, if timeouts are used and the system load becomes too high. On the right hand side four buttons are offered. One for adding a testcase from the file system, two for loading and saving the test suite and one for clearing the current test suite.

8.1.3. Test Suite Execution Panel

Figure 8.4. The test suite execution panel

The test suite execution panel shows the test execution progress bar. This progress bar is green as long as all tests have been successfully executed. The first failed test causes the progress bar changing its color from green to red. Furthermore the progress bar contains overview information about the number of already executed tasks (performed: x/total), the time the exexcution took so far and the number of failed tests (failed: y/total).

The panel also offers three buttons, to run the test suite execution, save the test report and to clear the results of a previous test suite execution. The run button can be used to start the execution and changes to an abort button during execution. Pressing abort immediately stops the current execution. The save button can be used to store the detailed test result permanently in a file. The output file is saved in HTML and can hence be loaded by any browser. The clear button can be utilized to delete the contents of the details panel and additionally resets the progress bar.

8.1.4. Details Panel

Figure 8.5. The details panel

The details panel shows the detailed results of the testcase execution, including a detailed report about success and failure of the testcases (cf. Figure 8.5, “The details panel”).

The report begins with a test execution summary which lists all the test agents and shows the execution state. Tests that are currently in execution are marked as "?", whereas already failed tests are visualized with "X" and succeeded tests with "O". In addition the overview shows the execution time that was needed for each of the test agents.

Below the execution overview the detailed results are depicted. For each test agent a list of all the performed test cases is shown. Each test case report consists of the name, description and a result. In case of a testcase failure additionally a failure reason is displayed.

In this section it will be described how agent-based testcases can be written. The test agents can be executed either in the testcenter tool, or as they are normal agents in the starter tool. If you start them in the starter tool, the test output will be written to the console.

For the construction of a testable agent it is necessary to include (and make available) functionality of the jadex.planlib.Test capability. In general, this capability is responsible for collecting user-defined jadex.planlib.TestReports and sends them back to the test center after all tests of a test agents have been carried out. Conceretely, a test agent has to import resp. reference the following elements of the Test capabiliy:

...
<capabilities>
    <capability name="testcap" file="jadex.planlib.Test"/>
    ...
</capabilities>

<beliefs>
    <beliefsetref name="reports" class="TestReport">
        <concrete ref="testcap.reports"/>
    </beliefsetref>
    <beliefref name="testcase_cnt" class="int">
        <concrete ref="testcap.testcase_cnt"/>
    </beliefref>
    <beliefref name="timeout" class="long" exported="true">
        <concrete ref="testcap.timeout"/>
    </beliefref>
    <beliefref name="testcenter" class="jadex.adapter.fipa.AgentIdentifier" exported="true">
        <concrete ref="testcap.testcenter"/>
    </beliefref>
    ...
</beliefs>

<configurations>
    <configuration name="default">
        <beliefs>
            <initialbelief ref="testcase_cnt">
                <fact>...</fact> <!-- Here the actual number of testcases needs to be entered. -->
            </initialbelief>
        </beliefs>
        <plans>
            <initialplan ref="test"/>
        </plans>
    </configuration>
</configurations>
...		

Besides the test preparation the test cases have to be written in a plan which normally is defined also as initial plan of the test agent. In the following code snippet (Figure 8.7, “ The plan for a testable agent ”) it is depicted what steps usually make up one test case.

...
public void body()
{
    ...
    TestReport tr = new TestReport("#1", "The description of what is tested.");
    
    try
    {
        // Test code goes here, e.g.:
        // IGoal mygoal = createGoal("my_goal");
        // dispatchSubgoalAndWait(mygoal);
        tr.setSucceeded(true);
    }
    catch(GoalFailureException e)
    {
        tr.setFailed("Exception occurred: " + e);
    }
    getBeliefbase().getBeliefSet("reports").addFact(tr);
}
...

The test plan should take care of creating a test report (jadex.planlib.TestReport) before the actual test code and initialize it with a name (e.g. the number of the test) and a short description of what is to be tested (both appear in the test report details).

Below that setup code the domain dependent test code can be placed. Usually, it is advantageous surrounding that test code with a try-catch block so that any occurring exception can be handled and the plan is capable of continuing with the execution of futher test cases from the same plan.

If the execution of the test was successful (e.g. when no exception occurred and the results are as expected), this should be marked in the test report via the setSucceeded(true) method. In case of a failure, the setFailed()-method can be used. It requires an error description to be given as parameter.

The test case execution is finished by adding the corresponding test report to the “reports”-beliefset (see Figure 8.6, “ The ADF of a testable agent ”) by calling getBeliefbase().getBeliefSet("reports").addFact(tr);. The test agent won't terminate successfully until the last report is added to the “reports”-beliefset.

If you want to do any cleanup operations before terminating, this should be done before adding the last test report to the “reports”-beliefset. The reason is that the Test capability will immediately notice when the declared number of test cases has been executed and will subsequently send back the test results to the test center and terminate the test agent.

The easiest way to use the Jadexdoc tool is via the plugin which provides a gui simplifying the documentation task:

Figure 9.1. Jadexdoc tool overview

There are three basic panels in this graphical tool. The model tree on the left hand side, the package panel and the settings panel. They will be described in detail below.

9.1.1. Model Tree

On the left upper side there is the model tree which is already known from other tools such as the starter tool (see Section 3.1, “Model Tree”):

Figure 9.2. Model Tree

With this panel you can manage adding packages or single files to your selection of files of which you want to create the Javadoc/Jadexdoc. For this purpose the following actions are available via popup (and also partially via the tool bar above):

• For adding the selected package to the list of packages to document.

• For adding the selected package and all recursivly contained subpackages to the list of packages to document.

• For removing the selected package to the list of packages to document.

• For removing the selected package and all recursivly contained subpackages to the list of packages to document.

9.1.2. Package Selection Panel

In the middle you can find a panel which displays selections of “Packages”, “Source Paths”, “Class Paths” and “URL Links”:

Figure 9.3. The panel for adding packages etc.

• The“Packages” tab shows the packages and files that should be documented by the Jadexdoc and Javadoc tools.

• In the “Source Paths” tab the path(s) to the sources of the packages and files to document can be defined. In case of Jadexdoc source paths are normally not that important because the ADF files are contained in the "classes" folder, too. With respect to Javadoc source path are more important as Javadoc always needs the Java source files for accessing the Javadoc comments which are not present in the compiled classes any more.

• In the “Class Paths” tab the class path can be edited. This can be done either by hand or by clicking on the “Fetch” button which results in fetching the currently used class paths.

• If you finally choose the tab “URL Links” you can specify locations you want to cross-link to in your doc-files. If you click on fetch this will insert an entry for the URL to the Standard JDK Java API. This will enable Javadoc and Jadexdoc to generate links for the standard Java classes such as String, Integer etc.

9.1.3. Settings Panel

On the right hand side you can find the settings panel, where some detailed settings for Javadoc and Jadexdoc and be defined:

Figure 9.4. The settings panel

• The "Include subpackes" check box can be used for automatically including subpackages. This means if this option is checked the tools will generate documentation for all selected packages (and files) and all of the recursively contained subpackages.

• Via the "Output directory" textfield it can be defined to which directory the documentation should be generated. The standard output directory is the current directory. The "..." button can be used to select another appropriate target directory.

• The "Overview page" represents the top-level page for the whole generated documentation and contains information about the contained packages. The "..." button can be used to select a custom overview HTML page. The overview page will only be included when the corresponding check box is selected.

• The "Document title" option can be used for specifying the title to be placed near the top of the overview summary file. The title will be placed as a centered, level-one heading directly beneath the upper navigation bar. The title will only be included when the corresponding check box is selected.

• The "Basic options" can be used to turn on/off several generation features. The hierarchy tree is a page containing agents and capabilities displayed in usage relationships. The navigation bar offers possibilities to refer to related documentation pages. It can be turned off if you are interested only in the content and have no need for navigation, e.g. when converting the files to PostScript or PDF for print only. The index holds an alphabetical list of elements. It can be adjusted with an options in a way that only one letter per page is generated.

• The "Generate Javadoc" check box can be used to turn on/off the invocation of the Javadoc tool.

• In the extra options text field an arbitrary number of additional Javadoc command line options can be specified.

• The "Javadoc program location" option allows for specifying the program location of the Javadoc tool, which belongs to the standard JDK edition.

• The "Generate Jadexdoc" check box can be used to turn on/off the invocation of the Jadexdoc tool.

• In the extra options text field an arbitrary number of additional Jadexdoc command line options can be specified.

• The "Java program location" option allows for specifying the program location of the Java program (e.g. java.exe on Windows systems), which belongs to the standard JDK edition and is required for the invocation of the Jadexdoc tool.

During the documentation generation, there will appear an animated icon in the bottom right corner. While running Javadoc, it shows a Java icon scanned by a red bar , while running Jadexdoc, an icon with an agent scanned by a red bar is displayed .

9.1.4. Console Output Panel

The Jadexdoc and Javadoc tools both use the standard Java output and error streams (System.out and System.err) for printing out information about the generation progress. The console panel of the JCC allows for inspecting these outputs directly in the tool (see also Section 2.1, “Using the JCC”).

Figure 9.5. The console output panel

On the top right of the console outputs, there are two buttons. With the left one, you can turn on and off the console output during a run, with the right one you can clear the console.

You can start the Jadexdoc tool from a console via:

Description.  Arguments can be in any order. See processing of Source Files for details on how the Jadexdoc tool determines which source files to process.

The Jadexdoc tool will generate output originating from four different types of "source" files: Agent and Capability source files, package comment files, overview comment files, and miscellaneous unprocessed files.

Processing of source files.  The Jadexdoc tool processes files that end with ".agent.xml" and ".capability.xml" plus other files described below. If you run the Jadexdoc tool by explicitly passing in individual source filenames, you can determine exactly which ADF files are processed. However, that is not how most developers want to work, as it is simpler to pass in package names.

Package Comment Files.  Each package can have its own documentation comment, contained in its own "source" file, that the Jadexdoc tool will merge into the package summary page that it generates. You typically include in this comment any documentation that applies to the entire package.

To create a package comment file, you must name it package.html and place it in the package directory in the source tree along with the agent description files. The Jadexdoc tool will automatically look for this filename in this location. Notice that the filename is identical for all packages.

The content of the package comment file is one big documentation comment, written in HTML, like all other comments. When writing the comment, you should make the first sentence a summary about the package, and not put a title or any other text between <body> and the first sentence.

When the Jadexdoc tool runs, it will automatically look for this file; if found, the Jadexdoc tool does the following:

Overview Comment File.  Each application or set of packages that you are documenting can have its own overview documentation comment, kept in its own "source" file, that the Jadexdoc tool will merge into the overview page that it generates. You typically include in this comment any documentation that applies to the entire application or set of packages.

To create an overview comment file, you can name the file anything you want, typically overview.html and place it anywhere, typically at the top level of the source tree. The content of the overview comment file is one big documentation comment, written in HTML, like the package comment file described previously. When you run the Jadexdoc tool, you specify the overview comment file name with the -overview option. The file is then processed similar to that of a package comment file.

Miscellaneous Unprocessed Files.  You can also include in your source any miscellaneous files that you want the Jadexdoc tool to copy to the destination directory. These typically includes graphic files, example agent description files, and self-standing HTML files whose content would overwhelm the documentation comment of a normal agent description file.

To include unprocessed files, put them in a directory called doc-files which can be a subdirectory of any package directory that contains source files. You can have one such subdirectory for each package. For example, if you want to include the image of a creature Creature.png in the jadex.examples.hunterprey.creature.CleverPrey agent documentation, you place that file in the jadex/examples/hunterprey/creature/doc-files/ directory. Notice the doc-files directory should not be located at jadex/examples/doc-files/ because examples does not directly contain any source files.

All links to these unprocessed files must be hard-coded, because the Jadexdoc tool does not look at the files, it simply copies the directory and all its contents to the destination. For example, the link in the CleverPrey.agent.xml doc comment might look like:

<!-- The image of the CleverPrey agent: <img src="doc-files/Creature.png"> -->

By default, Jadexdoc uses a standard doclet that generates HTML-formatted documentation. This doclet generates the following kinds of files (where each HTML "page" corresponds to a separate file). Note that Jadexdoc generates files with two types of names: those named after agents/capabilities, and those that are not (such as package-summary.html). Files in the latter group contain hyphens to prevent filename conflicts with those in the former group.

Basic Content Pages. 

Cross-Reference Pages. 

Support Files. 

Commenting the Source Code.  You can include documentation comments in the agent description files, ahead of declarations for any agent, capability, plan, goal, event or expression, etc. You can also create comments for each package and another one for the overview, though their syntax is slightly different. The comments in the agent description files are regular xml-comments consisting of the characters between the characters <!-- that begin the comment and the characters --> that end it. The text in a comment can continue onto multiple lines.

<!--
    This is the typical format of a simple documentation
    comment that spans multiple lines.
-->

<!-- To save space you can also put a comment on one line. -->

Placement of comments.  Documentation comments are recognized only when placed immediately before agent, capability, belief, goal, plan, event or expression declarations. Only one documentation comment per declaration statement is recognized by the Jadexdoc tool.

<!-- This is the comment for the agent 'MyAgent' -->
<agent name="MyAgent" package="jadex.examples.myagents">
    <beliefs>
        <!-- The comment for the belief 'MyBelief' -->
        <belief name="MyBelief" class="Object"/>
    </beliefs>
</agent>		

Comments are written in HTML.  The texts can be written in HTML, in that they should use HTML entities and can use HTML tags. You can use whichever version of HTML your browser supports. The bold HTML tag <b> is shown in the following example.

<!-- This is a <b>documentation</b> comment. -->

First sentence.  The first sentence of each documentation comment should be a summary sentence, containing a concise but complete description of the declared member. This sentence ends at the first period that is followed by a blank, tab, or line terminator. The Jadexdoc tool copies this first sentence to the member summary at the top of the HTML page. For convenience, Jadexdoc strips any html tags from this sentence, when it is displayed in a summary table.

The Jadexdoc tool uses a standard doclet to determine its output. The Jadexdoc tool provides a set of command-line options that can be used with any doclet. These options are described below under the sub-heading Section 9.6.1, “Jadexdoc Options”. The standard doclet provides an additional set of command-line options that are described below under the sub-heading Options Provided by the Standard Doclet. All option names are case-insensitive, though their arguments can be case-sensitive.

The description of the installation process assumes that you have successfully downloaded and installed Protégé 2.1 (or later). The installation of the plugin is simple. Extract the plugin.zip file from the beanynizer distribution into the protege/plugins directory. Make sure to use the “Use folder names” option (or similar) of your zip tool, such that a subdirectory protege/plugins/jadex.tools.beanynizer is automatically created. (You can also create this directory by hand before unzipping. In the end you should have a jadex_beanynizer.jar, a plugin.properties file, and some additional jar files in this directory.) Now you can start Protégé as usual. The Help → Plugins menu should contain an entry Jadex Beanynizer. Selecting this entry will just take you to the Jadex homepage. For the usage of the plugin see the next sections.

This section only discusses details of the usage of the Beanynizer plugin. For general information about creating ontologies in Protégé please consult the Protégé documentation. To create an ontology for use with Jadex, follow these four steps:

Figure 10.1. Protégé plugin configuration

The general options for the ontology are available from the code generation panel (see Figure 10.2, “Jadex Beanynizer tab”). The ontology name is the name, that will appear in the "ontology" slot of an ACL messages. From Java this is available with the ontologyclass.ONTOLOGY_NAME constant. A package can be specified, where the ontology class file should be generated. This package is also the default for other generated classes. The class name is the Javaclass name to be used for the ontology (without package). The output directory is the root directory for the package hierarchy to be generated. You can use relative paths here, which will be expanded relative to the saving-location of the Protégé project. When subdirectories for some packages do not exist, they will be created on-the-fly.

Figure 10.2. Jadex Beanynizer tab

The "Files to Generate" option specifies which kind of Java files should be generated for your ontology classes. Note that this option only represents a default, that can be overridden individually for each ontology class as described in the next section.

The Protégé classes panel is extended with extra options concerning the code generation. These extra options are shown below the template slots list (see Figure 10.3, “Protégé classes panel”, bottom right). As default, the Protégé name of the class is used for the .java file. This can be overridden by specifying an additional Java class name. The interface flag can be set, when not a class but an interface should be generated. In general, this only makes sense for abstract ontology classes.

Figure 10.3. Protégé classes panel

The package field allows to specify the package of the Java class, overriding the default package specified in the code generation tab. The "Generation Options" offer the same options as the "Files to Genrate", and influence how many files are generated for each ontology class. E.g., setting the option to "Fixed" allows to include an already existing class in the ontology. In addition, the field can be left blank to indicate that the ontology default should be used. The superclass field and the additional interfaces list, allow to specify fully qualified class or interface names to use as superclass or additionally implemented interfaces. If no superclass is given, the code generator creates a class hierarchy corresponding to the hierarchy in the ontology. For interfaces, only implements interface, . . . is added to the class, the generator does not (yet) magically fill in any missing method implementations.

The code generator generates fields and getter / setter methods for each slot, thereby respecting settings such as name, type, default value, and cardinality (see Figure 10.4, “Protégé Slot Options”). For slots that allow multiple values, also add / remove methods are generated. Supported slot types and their default Java mappings are:

Figure 10.4. Protégé Slot Options

The name to use for the generated field can be specified using the attribute name option. The Beanynizer has its own idea of Java coding conventions and tries to create a suitable Java name from the slot name, when no specific attribute name is given. The attribute type allows to change the generated Java type, by specifying a fully qualified class name, or one of the basic types (e.g. long). The names of getter and setter methods are derived from the attribute name (which may also be derived from the slot name). Use the get method and set method options to change the names of the methods to generate. This is especially helpful, when including already existing classes in the ontology. The pure Java ontology supports two other settings for slots: "transient" and "external". For transient slots, the field is generated with the transient keyword. External slots are ignored during code generation (this is useful, if the ontology class extends an existing Java class, which already provides the get/set methods for a given slot).

It is possible (while maybe a bit awkward) to convert other ontologies to be used with the Beanynizer. To convert an existing ontology perform the following steps (note, this process has only been tested with Protégé 2.1 and might not work with 3.0):

Protégé is a complex tool in itself, therefore a basic understanding of it is essential before you can effectively use the Beanynizer plugin. The Beanynizer is still an early staged development based on our specific requirements, and does not try to be a general purpose code generation environment. If you encounter problems or miss some features please drop us a note, such that we can improve the Beanynizer for upcoming releases.

Usages of the Beanynizer can be found in the cleanerworld, marsworld and hunterprey examples (look for an "ontology" package). Also, some Jadex tools use a Beanynizer generated ontology for communication (e.g., introspector, and tracer). Their Protégé ontology files can be found in the jadex/onto directory.

The Beanynizer was designed for flexible code generation. The code for the Java classes is based on templates processed with the Velocity template engine. The templates for the Java and Jade generation modes can be found in the src/jadex/tools/beanynizer/genjava and src/jadex/tools/beanynizer/genjade directories. If you want to change the way Beanynizer generates code, you may try to alter these templates to suit your needs. See http://jakarta.apache.org/velocity/ for more information about the Velocity template language.