Table of Contents
The following minimum system requirements are recommended prior to installing the ADK:
| Requirement | Description |
|---|---|
| Hard disk | 70Mb available |
| Memory | 128Mb minimum, 256Mb recommended |
| Processor | Pentium 500MHz or higher |
| Software | Sun Java Runtime Environment version 1.3.1 or 1.4. If you need to run the ADK on JDK 5.0, please contact Tryllian. The ADK will not work out of the box with version 5.0 of the JDK. The ADK has also been tested with Bea's JRockit JVM and with IBM's JVM; both appear to support running the ADK. |
| Network | For mobility, a network connection supporting TCP/IP is required |
| Database software | The out-of-the-box persistence requires database software. This product includes Hypersonic SQL. Persistence is also supported with the following databases : Oracle version 8.1 or higher (has been tested for Oracle 8i release 2 (8.1.7)), MS-SQL version 2.27, Mckoi version 0.92, Cloudscape 5.0, MySQL 4.1, PostgreSQL 7.2 or DB2 8.1. If you have additional database requirements, please contact Tryllian. |
| OS Requirements | The ADK runs on any OS for which Sun has made available a JVM. Windows 2000 and XP, Solaris and GNU/Linux are supported by Tryllian. Additionally, the ADK has been tested on OS/400, OS/370. Tryllian can offer paid suport for running the ADK on IBM mainframes or AS/400 machines. Apple's OS X is not supported, but part of the development of the ADK is done on OS X. |
After downloading the ADK from the Tryllian website or receiving the CD-Rom, the software needs to be installed on your machine. Installation will vary depending on your operating system. This installation process will install all necessary Java code and example scripts onto your machine. Currently, the ADK requires JDK 1.3.x to run.
When the software is installed, you might want to first run sample scripts, and learn how to build an agent application. If you are directly connected to the Internet (i.e. not behind a firewall), be sure to read the security instructions after installing the ADK to secure your habitat from network access.
Depending on the operating system used, the ADK is available as either adk-3.0.zip, adk-3.0.exe or adk-3.0.tar.gz. The first two are meant for the use on Windows, the latter for use on Unix, GNU/Linux or OS X systems.
Tryllian now provides an Installshield Installer version of the ADK. You can simply double-click on the provided setup executable, and the ADK will be installed on your machine. Appropriate entries will be made in your start menu.
Note that if you use the InstallShield installer and you have more than one JDK installed, you will need to verify that the ADK uses version 1.3.x, and not 1.4.x. The ADK does work at all with version 1.4.x. Paying a little attention at this stage will save you much wasted time.
There is a separate InstallShield installer option to install the habitat manager service. This is a small application that embeds itself in your system tray and that can be used to start and stop habitats, and to verify that a habitat is still running.
The InstallShield installer installs exactly the same software as the Windows zipfile installation option.
To install it in a Windows 95/98/NT/2000 environment, create a directory called C:\Tryllian on your hard disk. (Note that due to a bug in Sun's JDK, installing the ADK in c:\Documents and Settings is not supported.) Unzip the adk-3.0.zip file into this directory. The ADK directory contains the following subdirectories, listed below:
agents: The agents used by the ADK.
agent-template: Agent template to help you to develop and build your first agent.
ant: ANT tasks which assist development with the ADK.
bin: The scripts of the ADK tools.
config: The configuration files of the ADK.
docs: Javadoc of the ADK needed to program your own agents and the documentation of the ADK.
examples: The start scripts for the examples, the XML configuration files, the source code and the DNA files of the examples.
kickstart: The sample project referenced in the ADK Scenarios.
lib: The AFC and the ARE jar files, along with third party jars.
scenarios: Scenarios for demonstrating ADK features.
Go to the C:\Tryllian\adk-3.0\bin directory.
The examples need to be run from a DOS Command Prompt. Sometimes, this may be cumbersome from a subdirectory. In order to do this properly, you need to change the DOS Command Prompts PIF file to make sure the DOS Command Prompt remains visible during the execution. When the example has run, be sure to use ^c (Ctrl-C) to stop the processing. After this, manually close the DOS Command Prompt by clicking the Close button. This can be done by performing the following steps:
Open a DOS Command Prompt.
Click on the properties button, or select it from the window's main icon.
Uncheck the Close on exit check box (if it exists).
Close the DOS Command Prompt.
Unpack the adk-3.0.tar.gz file.
(tar.gz file)
gunzip adk-3.0.tar.gz
tar xf adk-3.0.tar
This will result in the adk-3.0 directory in the current directory. Go to the examples directory called adk-3.0/bin to run the examples.
To make it possible to make agent projects reasonably independent of the location of the ADK installation, the ADK_ROOT environment variable was introduced. In startup scripts that will be run within the ADK itself, this environment variable is set automatically if needed. However, if you create your own project, you might not want to place your project within the ADK installation directory, but use the ADK in a similar way you would use the JDK when developing a regular Java program.
To do so, you can start using a copy of the Kickstart project placed wherever you prefer, and reference the ADK using the ADK_ROOT environment variable. Before using Kickstart, you must correctly set the ADK_ROOT variable. If the variable is not set and the system cannot find the <ADK_ROOT>lib\are-startup.jar then you will receive a similar message to: “The jar file '<ADK_ROOT>lib\are-startup.jar' does not exist. Check the ADK_ROOT variable and start again.”
Using Windows, this is set in the Control Panel. Select System, then choose the Advanced tab. Go to Environmental Variables, under either User Variables or System Variables (depending on your system, if shared or not), select New. Under Variable Name, type ADK_ROOT. Under Variable Value, add the setting C:\Tryllian\adk-3.0 depending on where you have installed the ADK. For Windows 95/98/ME, you can use the command set ADK_ROOT=C:\Tryllian\adk-3.0.
Controlling persistence within the habitat is managed by using command line options. Several commonly used command line options are described below.
| Command line option | Description |
|---|---|
| -h, --help | Print usage. |
| -s, --start-immediately | Start agents immediately after they have been restored. If this option is not present, agents are started after all agents have been restored. |
| -c, --clean-db | Clean the database before starting up the habitat. This removes all persisted agents from the database. |
| -C, --create-db | Create the database. This option requires --sql-file and optionally --db-url |
| -S, --sql-file=value | The file containing sql commands. Used with --create-db |
| -d, --db-url=value | Optional db url. Used with --create-db |
| -u, --upgrade | Do an upgrade. This option requires two arguments: --old-dna and --new-dna. All agents that use old DNA will be upgraded to use the new DNA. |
| -o, --old-dna=value | The old dna file. Used with -upgrade |
| -n, --new-dna=value | The new dna file. |
By default, the ADK uses JXTA to communicate with other habitats. When starting up, the ADK determines the network configuration of the machine. In most cases, the ADK is capable of determining the correct network configuration of the machine. The start-up banner prints some diagnostic information about the network configuration of the machine. If everything seems okay, it is still possible that JXTA will not work. In that case verify whether multicast is enabled on the primary network interface of the host, or ask your system administrator to do this for you.
In some cases, the ADK cannot determine the local host name and IP address correctly. This can happen in several cases:
The machine does not have an available network, because there is no active network adapter.
The host name of the machine is configured to be localhost.
The hostname of the machine resolves to IP address 127.0.0.1
The host has several network interfaces, but some of the network interfaces are not active, or does not have a correct IP address.
In these cases, the property are.localhost.name should be set to the host name or IP address of the network interface which is used by the ADK.
The ADK will complain loudly and verbosely about these circumstances.
The default security settings of the ADK allow other agents to enter your runtime environment. Therefore, they are suitable only if you are protected from access via the Internet by a firewall.
However, if you are directly connected to the Internet, it is advised you take the following steps:
Make a backup of the following files: config/habitat.properties, config/roles.prop and config/keystore.dat.
Using the keytool, create your own keystore containing a self-signed certificate with private key. Save this keystore as config/keystore.dat. More information on the keytool and keystores is found in the Developer's Guide.
Set the following lines in your config/habitat.properties file: security.roles_prop.location = ${are.configdir}/roles.maxsecurity.prop
Add the following line to the config/roles.maxsecurity.prop file: developer.role.ALIAS = ROLE where ALIAS is the name assigned to the self-signed certificate created in step 2, and ROLE is the desired role for agents with this certificate, as described in the Security chapter, "ARE security files" section in the Developer's Guide.
Update your build scripts so your DNA files will be created using the private key generated in step (2).
Using Sun's jarsigner tool, sign the afc.jar (and any other shared-refs you might use) with the private key generated in step (2).
In some situations, it may be desirable to run a habitat without network. To do this set the option messenger.registry.startmessengers to nothing in the habitat.properties file.
For more information on how to setup a habitat in a more complex network environment, refer to the Configuration Issues Chapter in the Developer's Guide.