GOLEM Tutorial

The tutorials section aims to demonstrate using or interacting with GOLEM, its APIs, or sample applications in an effort to increase familiarity with the platform. If further clarification is required, or behaviour does not match that shown in the tutorials, please email golem@cs.rhul.ac.uk.

GOLEM Human Avatar demo

This demo has been tested on Linux Mint 14 (64-bit) and Windows 7 (64-bit), both using Java 7.

Download the demo zip here. Extract it to a location on your local machine, ensuring that no spaces are in the path to the extracted folder, GOLEM. The extracted contents should be as shown in Fig. 1.

  1. GOLEM
    1. golem.jar
    2. golem.sh
    3. golem.bat
    4. golem_lib
    5. AppData
      1. PW_humanavatar
        1. agent
        2. config
        3. container
        4. dest
        5. packet
        6. physics
    6. plugins
      1. manifest.golem
Fig. 1: Extracted directory structure for GOLEM

Running GOLEM is simple: double-click on the golem.bat file (Windows) or golem.sh (Unix-based OS). In the case of the latter, permission may be required to allow the file to be executed as a program. This can be achieved using by accessing the Permissions tab in the Properties menu for the file.

This version of GOLEM is bundled with an application already; the Human Avatar application. Open an instance of the application by navigating to GOLEM > Launch > PW Human Avatar.

As the config directory contained a saved configuration file, the application attempts to find the specified files in the PW_humanavatar directory, and sets the correct values in the configuration tab. Scroll to the bottom, and click Create.

The configuration tab closes, and a new tab opens, with the Human Avatar variant of Packet World running. Use the on-screen buttons, the arrow keys or W A S and D to move the avatar agent around the world, noticing how its (your) view is limited to that which the agent body is able to see. Use the on-screen buttons or Q and E to pick up the target packet (coordinates for the target packet are given in the status bar at the bottom) and drop it in a destination slot.

Deploying Applications

Applications on GOLEM are run as plugins, packaged in JAR format. Applications developed on GOLEM are required to implement the Application interface and are recommended to extend the DefaultApplication class which provides functionality that should be common to all applications.

Along with Packet World, another application is included as a demonstration of interacting with GOLEM as a generic application platform; the plugins.basic package contains no agent-related code and only displays the minimum required code to create an application for GOLEM.

SampleApplication.java is the main application class. In its constructor, it defines the name of the application, as well as the name that GOLEM should give its application directory structure (null is passed because this example doesn’t require a directory structure).

The postInit() method is called after the initialisation which is handled in DefaultApplication. This is typically where a setup tab would be created. As this application has no setup tab, the launch() method is immediately invoked (if there was a setup tab, launch() would be invoked from that context at the appropriate time, e.g. when the user presses Create).

The launch() method creates a new tab, giving the name of the tab to be created, and a flag to indicate whether the tab is a scrolling tab or not. The setup() method of the tab is called.

// SampleApplication.java 
package uk.ac.rhul.cs.dice.golem.plugins.basic;
import uk.ac.rhul.cs.dice.golem.application.DefaultApplication;
 
public class SampleApplication extends DefaultApplication {
 
    // Application constants    
    public static final String NAME = "Sample Basic Application";
     
    public SampleApplication() {
        // this sample application doesn't require a directory
        super(NAME, null);
    }
 
    @Override
    protected void postInit() {
        launch();
    }
     
    @Override
    protected void launch() {
        SampleApplicationTab test = new SampleApplicationTab(this,
                "Sample Application", false);
        test.setup();
    }
}

SampleApplicationTab.java extends from the DefaultTabPanel, which takes care of some basic tab functions. initSetup() is called at the end of DefaultTabPanel#setup() and is where the user interface of the tab should be initialised.

cleanup() is an optional method (unused in the demo), which is called when the tab is being destroyed. This is where listeners should be removed, simulations stopped, or where any other “cleanup” that needs to be performed should be done.

// SampleApplicationTab.java 
package uk.ac.rhul.cs.dice.golem.plugins.basic;
import uk.ac.rhul.cs.dice.golem.api.Application;
import uk.ac.rhul.cs.dice.golem.application.DefaultTabPanel;
 
public class SampleApplicationTab extends DefaultTabPanel {
 
    protected SampleApplicationTab(Application context, String name,
            boolean scrollingTab) {
        super(context, name, scrollingTab);
    }
    
    @Override
    protected void postInit() {
        launch();
    }
     
    @Override
    protected void launch() {
        SampleApplicationTab test = new SampleApplicationTab(this,
                "Sample Application", false);
        test.setup();
    }
}
The sample application running

Fig. 2: The sample application running

When run, the sample application launches the tab which has a single label, and the status bar displays the name of the application which has launched (Fig. 2).

Testing applications without deploying them as plugins requires modification of the GolemGUI.java class which is available in the uk.ac.rhul.cs.dice.golem.gui package. Add a menu item to GOLEM > Launch menu for easy access during development using the addMenuItemsManually(JMenu) method as follows:

// GolemGUI.java
 private void addMenuItemsManually(JMenu menu) {
    // SampleBasicGolemPlugin
    JMenuItem menuBtn = new JMenuItem("Sample Menu Basic");
    menuBtn.addActionListener(new ActionListener() {
        public void actionPerformed(ActionEvent e) {
            SampleApplication sample = new SampleApplication();
            sample.init(GolemGUI.this);
        }
    });
    menu.add(menuBtn);
}

Distributing the plugin requires exporting it as a JAR. In the Eclipse Package Explorer, select your plugin package/subpackages, right-click and Export. Select Java > JAR file from the dialog. Select where to save, and click Finish. In this guide, the JAR is named samplebasic.jar.

To use the application in a compiled version of GOLEM, copy it to the plugins directory, and edit manifest.golem adding an entry using the example in the file, which should consist of the menu item name, the filename of the JAR which should be in the plugins directory, and the fully qualified class name which extends DefaultApplication.

For the demo, this line was added (attributes are separated by tabs, not linebreaks):

// manifest.golem
"Sample Plugin"    "samplebasic.jar"    "uk.ac.rhul.cs.dice.golem.plugins.basic.SampleApplication"

which results in the demo application being added to the GOLEM menu (GOLEM must be restarted after manifest file changes).

Try adding this plugin yourself using the GOLEM package downloaded in the GOLEM Human Avatar section. There exists an empty plugins directory in the main GOLEM hierarchy in which you can copy the samplebasic.jar plugin. The plugin can be downloaded here. Ensure that the manifest file is updated using the line given above (attributes are separated by tabs, not linebreaks or spaces), or copy the manifest file bundled with the plugin.

E-Commerce Application

This section presents a purchase protocol from e-commerce to demonstrate how GOLEM agents communicate. We create two agents in a single container that execute a protocol for the electronic purchase of goods.

Basically, the buyer agent initiates the protocol by sending a request for quote for the goods. The seller then sends the price as the offer. If the offer is reasonable for the buyer, he accepts and the protocol terminates. Otherwise, he sends a reject, and the seller revises the offer.

The implementation for the e-commerce application can be downloaded here. Note that this application does not follow the standard GOLEM application development approach; it works as a stand alone program, and is simply an illustration of how agents are developed for GOLEM.

The zip file contains the following source files:

  • PurchaseProtocol.java is the main class for this application, and it initialises the environment.
  • ECommerceMind.java is the Java wrapper for the agent reasoning. The method executeStep() calls the Event Calculus engine to perform reasoning.
  • ECommerceBuyerMind.pl describes the knowledge base and the operational rules for the buyer agent.
  • ECommerceSellerMind.pl describes the knowledge base and the operational rules for the seller agent.