IberAgents Tutorial

In this tutorial we are going to build a sample application for IberAgents, ibertest. It shows some interesting features, and provides a skeleton for your application. In a second tutorial we explain how to build a personal agent.

We will base our discussion on the user guide. First we will define a set of requirements; then we will develop the code and the XSL template. The configuration file and build script are explained next, and we will finish by taking a look at the results.

The ibertest skeleton is available as a zip file.

Requirements

The requirements for ibertest are simple: store a configuration value and show it in a web page. The configuration value must be editable via web, and our application must accept the new value dynamically (without restarting).

Building the Component

This section explains, step by step, how to build a component for the chosen task.

Configuration

The configuration of the component will consist of a single string value; we will call it TestAppConfiguration. It is responsible for knowing its target component, i.e. the name of the class that uses it; and storing the value as an attribute with getter and setter. The attribute can have any name; all the configurator requires is to have a getter and setter with the same name, in this case stringValue. So, putting it all together:

	package com.ibertest;

	import com.iberagents.config.Configuration;

	public class TestAppConfiguration implements Configuration
	{
		private String string;
    
		public String getTargetComponent()
		{
			// return name of target component
			return TestAppComponent.class.getName();
		}

		public String getStringValue()
		{
			return this.string;
		}

		public void setStringValue(String stringValue)
		{
			this.string = stringValue;
		}
	}

Component

At this point we want to build the component that implements the desired behavior. We will call it TestAppComponent; it is both Configurable and a WebComponent.

	package com.ibertest;

	public class TestAppComponent implements Configurable, WebComponent
	{
		...
	}

Now we will fill it in. First we have to store the configuration that will be passed by the Configurator. This is usually done using an attribute.

		private TestAppConfiguration configuration;
		
		public void configure(Configuration configuration)
		{
			this.configuration = (TestAppConfiguration)configuration;
		}

Finally the methods of WebComponent: command() to run a task and show() to show a web page. We will use an XSL template for the web page, building an iberxml element and then transforming. As you will see, it can be done in a couple of lines.

		public void command(String arg0, RequestParameters arg1)
			throws PlatformException
		{
		}

		/**
	 	* Show a web page.
	 	*/
		public ResponsePage show(String arg0, RequestParameters arg1)
			throws PlatformException
		{
			Element element =
				new Element("platform", this.configuration.getStringValue());
			return new TransformationPage(element, "testPage.xsl");
		}

where we pass the ibexml element and the name of the XSL file to a TransformationPage. And the code is ready! You can see the resulting configuration and component.

Building the XSL Template

This task is very simple; although XSL files can get very complex, here we only have one dynamic item, taken from the <platform> element. So we simply wrap the desired web page in an <xsl:template> and place the configuration value as an <xsl:value-of>; this will extract the contents of the element and append it to the preceding text.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
	<xsl:output method="xml" indent="yes"/>

	<xsl:template match="/">
		<html>
			<head>
				<title>Platform Test Page</title>
			</head>
			<body>
				<center>
					<h1>This is a test page</h1>
				</center>
				<blockquote>
					<h2>For the deployment test.</h2>
					<p>
					Configuration value:
					<xsl:value-of select="platform" />
					</p>
				</blockquote>
			</body>
		</html>
	</xsl:template>
</xsl:stylesheet>

It is here.

Building the Configuration File

Usually the Editor takes care of creating configurations. In this case we are building a new application, so we need to either create the file configuration.xml or modify an existing one.

All applications have a Container to store their configurations. It has an array of configuration objects and another one with configuration components; we are using just one Configuration. So, we choose the correct type and place an element called stringValue inside, containing whatever we want.

<?xml version="1.0" encoding="UTF-8"?>
<bean type="com.iberagents.config.Container">
	<configurations type="array" arrayType="com.iberagents.config.Configuration">
		<configuration type="com.ibertest.TestAppConfiguration">
			<stringValue type="string">hi</stringValue>
		</configuration>
	</configurations>
	<components type="array" arrayType="com.iberagents.ConfigurationComponent" />
</bean>

The syntax may seem overly complex, and this is because it will be parsed automatically by IberAgents' serialization layer. It is possible to have the configuration editor add elements automatically, making this step much simpler.

Note: the configuration editor uses lists to show containers; the feature to add elements to lists is not finished at this stage.

Building the Build File

To make IberAgents run our test application, we have to package it into a .jar file. Code will be contained This can be done using the jar utility in the JDK. However, using Ant is much more flexible. The following sample build.xml compiles the code (in directory src), copies the configuration file and the XSL template (in directory files), and packages it in a .jar file into directory dist.

 <project name="ibertest" default="jar" basedir=".">
	<target name="init" description="Sets up the build system">
		<!-- create build directory -->
		<mkdir dir="build"/>

		<!-- create the dist directory -->
		<mkdir dir="dist"/>
	</target>
	<target name="compile" depends="init" description="Compiles the application">
		<!-- compile from src into build -->
		<javac srcdir="src" destdir="build">
			<classpath id="project.class.path">
				<pathElement path="build"/>
				<pathelement location="lib/iberagents.jar"/>
				<pathelement location="lib/iberxml.jar"/>
			</classpath>
		</javac>
	</target>
	<target name="jar" depends="compile" description="Jars class files and xsl's">
		<!-- put all classes and files into the jar -->
		<jar jarfile="dist/ibertest.jar" basedir="build">
			<fileset dir="${files}">
				<include name="*.xsl"/>
				<include name="configuration.xml"/>
			</fileset>
		</jar>
	</target>
</project>

Running command ant in the application directory automatically produces ibertest.jar, which can then be copied to the directory ext in IberAgents.

The enclosed build file is more complete: it contains additional targets and performs many tasks not included here, e.g. it copies the resulting file into IberAgents. You should use it as a starting point for building your application; in practice you only need to replace the jarfile variable at the top of the file.

Testing the Result

In this section we will take a look at the results.

Start IberAgents

First we have to start the platform, using the provided scripts. In Linux (or Solaris) this is done with

	$ ./iberagents.sh

and in Windows

	> iberagents.bat

The script should show something like this:

	2004-07-29 16:07:55,961 [main] INFO  - Loading jar file: ibertest.jar
	2004-07-29 16:07:58,481 [main] INFO  - Platform started successfully

Access the Test Page

The URL to access our new component is http://localhost:8004/iberagents/platform?component=com.ibertest.TestAppComponent; it should show something like the screenshot below.

Test page.

Modify the Configuration

We now want to change the configuration. For this we access the configuration Editor at this URL: http://localhost:8004/iberagents/platform?component=com.iberagents.config.Editor.

Configuration containers.

We see a list with all containers; one for the platform itself and one for our test application. We select the last one.

ibertest configurations.

Now we see all of the configurations in ibertest: one, which we have just created. Additional configurations would appear here. So of course we select it.

Our configuration.

In this view of the configuration, we can see every value and modify it. After changing the value of stringValue, we click on "modify". (If we want this change to be stored in the configuration file, we can click on "store" afterwards.)

Modified configuration.

Now we reload the test page, and see that the value has been changed.

Modified test page.

This means that the Configurator component has called our configure() method with a new Configuration, we have stored it in our attribute, and when requested to show the test page we have used it.

Application Reloading

IberAgents keeps an agent running all the time, the Deployer, that checks if an application has been modified. In case we make a mistake we only have to replace ibertest.jar with a new version and it will automatically be reloaded.

So if we make any mistake we can modify any necessary files, rebuild ibertest and let the deployer agent reload it in a few seconds.

Conclusion

We have seen how to build an iberagents application in a few simple steps. You can proceed to download the skeleton for ibertest, or go on to the personal agent tutorial. Please contact us if you have any comments about this tutorial.