Table of Contents
This chapter discusses configuring the ADK. It explains the provided ANT build script, describes how to use and configure it. It also describes habitat.properties, agent descriptors, habitat.xml, classes directory, jars directory, and agents directory. Includes information on JBuilder, as it relates to configuration of the runtime environment. Information regarding configuring the ADK environment for first time usage is found in the Quickstart Guide which should be read prior to developing agent applications.
The most important feature of mobile agents is the mobility; that is, agents can move from host to host to perform their tasks. And not only that, agents can communicate across the network with agents residing on another host. The ADK provides a rich choice in network protocols. You have the choice between HTTP, JXTA (which supports TPC/IP, SSL and HTTP) and JMS. Your network of habitats needs to be configured to use one or more of these protocols to allow agents to communicate across habitat boundaries.
The ADK provides these capabilities in the form of Messenger Plugins -- small network protocol providers that can be loaded either inside the same virtual machine as the habitat, or in a separate virtual machine resident on the same host as the habitat. It is fairly trivial to create dedicated messenger plugins if you need support for a new network transport, or if you want, for instance, to create an application that communicates with agents but is not an agent itself. The Tryllian Habitat Service Manager, which embeds the Tryllian ADK in the Windows service registry and system tray is an example of a dedicated messenger plugin.
The most generally usable messenger plugin is the JXTA messenger plugin; the http messenger plugin is provided as an example, and the JMS messenger plugin is more suited to specific enterprise environments.
Messenger plugins can be loaded at habitat startup, inside the same JVM as the host habitat, or at any time, by starting a separate JVM that loads the messenger plugin. Messenger plugins that are to be loaded in the same JVM as the habitat are configured in the habitat.properties file, using the option messenger.registry.startmessengers, which takes a comma-separated list of messenger plugin classnames, like com.tryllian.messenger.jxta.JXTAMessengerPlugin.
If you want to load a messenger plugin in a separate JVM, you need to set the property messenger.rmi.remote-allowed to true; it is false by default. Then you can start messengers using the provided batch files or shell scripts, like jxtamessenger.bat.
Please note that each messenger plugin needs some specific configuration options to be present, and in some cases, jarfiles. If the messenger plugin is to be loaded inside the same JVM as the habitat, these configuration options go into the habitat.properties file; if the messenger plugin is to be started in its own JVM, the properties can either be placed in a file called messenger.properties, or on the commandline of the shell script or batch file that starts the plugin.
This section contains information on how to set up a networking environment using JXTA. This section applies to ADK releases 3.0 beta and above. In these releases, the ADK can handle more than one messenger and more than one protocol. JXTA is still the default protocol, but can be replaced by another protocol.
You can select the JXTA Messenger Plugin by setting the messenger.registry.startmessengers option in habitat.properties to com.tryllian.messenger.jxta.JXTAMessengerPlugin
JXTA (pronounced Juxta) is a peer-to-peer protocol specification, with a reference implementation in Java. We decided to start using JXTA, instead of SSL socket connections to deal with various problems, like discovery of habitats, routing of messages through firewalls, and solving dynamic IP and IP masquerading (network translation protocol, and NAT) issues. JXTA is smart in detecting routes for communication.
The ADK is released with a jxta-based messenger plugin. The plugin can be loaded in the same JVM as the habitat, or can run in a separate JVM and connect to the habitat using RMI. The JXTA plugin is wrapped in the legace JXTA Standalone Messenger API, as demonstrated in the StandaloneClient program. This shows how regular Java programs (non-agents and non-habitats) can communicate with agents in a habitat using the standalone messenger.
An alternative to using the Standalone Messenger is to implement the messenger plugin API in your application. Using this API is useful if you need a non-agent extension to your application that must communicate with agents using messages and must be able to run both inside and outside the habitat JVM.
When we talk about JXTA peers in this section, we refer to both habitats and standalone messengers. Capabilities and configuration issues of habitats and standalone messengers are very much the same.
JXTA uses various methods to communicate between peers. The two major modes of communication are
Peers can be configured to listen for incoming TCP streams and HTTP streams by setting the appropiate habitat properties. Refer to the ARE Specifications document for a listing of properties, their definition and example values.
On a Local Area Network (LAN), JXTA uses multicasts to discover other peers. In most cases, multicasts cannot pass routers or firewalls; therefore, some peers need to collect discovery information and make this informatiuon availabele to other peers. These peers are called Rendez-vous peers. Peers can be configured to act as a rendez-vous, and peers can be instructed to use a list of rendez-vous servers.
In most cases it is preferable to have multiple rendez-vous peers, to increase robustness: if one rendez-vous peer is down, the discovery information might still be obtained from another rendez-vous peer.
In a typical scenario, there will be a set of peers that cannot discover each other directly by multicasts since they are located in different networks. Some of these peers will be configured to act as a rendez-vous, while all peers will be configured to use the rendez-vous peers. It is important to note that all peers need to reach a rendez-vous peer. Since HTTP communication is not able to do multicasts, you must define at least one rendez-vous peer if your only way of communication is HTTP.
In the case of a firewall that uses Network Address Translation (NAT), you need to define the endpoints that are located on the public side of the firewall. Both the TCP section and the HTTP section of the messenger properties have entries for doing this.
If your peer wants to communicate with other peers, it needs to reach those peers by using either TCP streams or HTTP requests. Yet, if these peers are also located behind a firewall, a third peer is required to accept incoming HTTP traffic from both peers and act as an intermediary. These intermediary peers are called relays .
Peers can be instructed to act as a relay, and peers can be configured to use a set of relays. Relays must accept HTTP messages and may be configured to accept TCP streams. If two peers use a relay and both use HTTP to communicate, the relay will store messages from one peer until the other peer polls for messages. It is also possible to specify a NAT endpoint if a peer is configured as a relay.
In most cases it is preferable to have multiple relay peers, to increase robustness: if one relay peer is down, messages can still be relayed via other relays. If multiple routes are available JXTA tries to use the best route between peers
A demilitarized zone (DMZ) is a typical enterprise setup that uses two firewalls. There are three network zones:
The public Internet. This is the world wide Internet.
The DMZ, containing the public web servers and other servers. Traffic is allowed to pass from the public Internet to the DMZ only for specific ports and protocols. The same applies for traffic from the intranet to the DMZ. No traffic is allowed from the intranet to the public Internet or vice versa.
The intranet. This is the office network of the enterprise.
No traffic is allowed to pass from the intranet to the public Internet and no traffic is allowed to pass from the public Internet to the intranet. A request from the intranet to external servers are passed to proxy servers in the DMZ. The proxy server performs the requests on behalf of the client and passes back the results to the client in the intranet.
In the case of JXTA, an HTTP proxy server needs to be configured to handle JXTA HTTP traffic from the intranet to the public Internet. This can be an ordinary HTTP proxy. Since the HTTP messages handled by this proxy are encrypted in most cases, the proxy will not be able to do any content screening of the messages. To perform content screening, install a habitat in the DMZ containing application-specific agents that do content screening.
If your setup requires incoming HTTP requests, an HTTP proxy sever could be configured to accept HTTP requests and route them to the appropiate peer in the DMZ or on the intranet. To allow this peer to pass the traffic to other peers, you must configure the peer as a relay, and specify the proxy address and port as the NAT endpoint address of the relay. You could also choose to place the peer in the DMZ and let it accept incoming HTTP request directly, without a proxy for incoming HTTP requests. This setup is somewhat more vulnerable to DOS attacks, since the proxy server cannot be used to block malformed HTTP requests.
The most simple case is to use the standard settings of JXTA The defaults settings will work on a closed environment, i.e. all peers are in the same subnet; all peers run on machines with different IP addresses and all peers are able to reach each other via TCP streams. JXTA uses multicasts on the local subnet to find other peers, so no central peers are needed to collect discovery information.
Using the above setting, the habitat will determine its habitat ID based on its IP address combined with the habitat identity portnumber. This method may sound easy, but has some drawbacks. Sometimes determining the IP address is difficult, some hosts may change their IP address etc. To avoid this problem, you can set the habitat ID manually in the habitat.properties file:
habitat.id=12345678-abcdef00012345678
Another way is to embed the habitat ID in a habitat certificate. This is the certificate that is used to authenticate a habitat. Recent habitat certificates generated by the key tool can include a habitat ID. This is the preferred way of creating a habitat id for your habitats.
To setup a habitat to use a different habitat keystore, you have to edit the following properties, which are listed in the example habitat.property file.
# The keystore containing the private key. Requires a valid URL.
messenger.security.private-keystore=file:${are.configdir}/habitat-private-keyst
ore.dat
# The password of the keystore containing the private key, no default
messenger.security.private-keystore.password=12345678
# The alias of the entry containing the private key, default habitat
#messenger.security.private-keystore.entry.alias=habitat
# The password of the entry containing the private key, default same
# as keystore password.
#messenger.security.private-keystore.entry.password=
If your environment has strict security requirements, reading the habitat ID from the certificate is the only supported way. More details on this can be found in the ARE specifications document (see README.html->ARE technical specifications).
Whatever setup you choose, you must make sure that every habitat uses a unique habitat ID in your environment! This also holds for standalone messengers. You wil have to pay special attention to the habitat ID's used in environments where the set of habitats is not fixed. Also, network environments that use DHCP other other dynamicly assigned IP addresses will have to setup their habitat ID's by hand.
The ADK JXTA Messenger Plugin performs a sophisticated analysis of the present network configuration upon startup. As sophisticated as Java 1.3.x allows, in fact. However, it it still possible that you will encounter network configuration troubles that will prevent the JXTA plugin from functioning. In most cases, the ADK will print a diagnosis on the console or command box output. This section explains the diagnostic checks the ADK performs for you and gives the equivelent checks you can perform yourself.
The following section describes some basic ways on how to trouble-shoot networking issues. It assumes understanding of concepts such as hostnames and IP addresses.
The ADK requires a network configuration with the following properties to work out of the box using JXTA:
The availability of an IP number not equal to 127.0.0.1 that is assigned to a network interface that supports multicasting. The standard TCP/IP drivers of the supported platforms support multicasting.
The hostname of the machine must resolve to the above IP address on the host itself. If this is not the case, set the property are.localhost.name in the file habitat.properties.
The hosts must be able to reach each other using TCP connections.
The hosts that want to communicate need to be in the same multicast domain. In practice, this means that they must be on the same physical network and subnet. If the hosts are not in the same multicast domain or subnet, JXTA rendez-vous servers are needed.
If any of the above requirements are not met or firewalls exist in the network path between the hosts, configuration becomes more complex and requires detailed insight into the workings of JXTA. For further information and details on these types of configurations, refer to the earlier sections of this chapter and visit www.jxta.org.
On GNU/Linux, you can check if your hosts supports multicasting by issuing the command:
netstat -g
If this command lists the various multicasts group memberships, multicasting works fine. As an extra check, you can issue the command while a habitat is running. The multicast groups should include the group JINI-REQUEST.MCAST.NET (224.0.1.85). If the netstat -g prints a message saying that igmp is not supported, reconfigure your kernel with multicast enabled.
On Windows, issue the command:
netstat -r
The routes listed should include a route for network destination 224.0.0.0 to the IP address of your network interface.
On GNU/Linux, issue the command
hostname
The output of this command should be the proper hostname. The name localhost is not a proper hostname. Next, issue the command
host <output of hostname command>
The IP address listed should be the proper IP address of the host. Retrieve the IP address of your host by issuing the command
/sbin/ifconfig <primary interface, probably eth0>
The IP address 127.0.0.1 is not a proper IP address. The most common remedy is to either set the are.localhost.name property in the habitat.properties file, or make sure that the hostname does not resolve to 127.0.0.1 by editing yur /etc/hosts file.
On Windows, issue the command
hostname
The output of this command should be the proper hostname. The name localhost is not a proper hostname. Next, issue the command
ping <output of hostname command>
The IP address listed should be the proper IP address of the host. Retrieve the IP address of your host by issuing the command
ipconfig /all
The IP address is listed on the line IP Address. The IP address 127.0.0.1 is not a proper IP address. The most common remedy is to either set the are.localhost.name property in the habitat.properties, or make sure that the hostname does not resolve to 127.0.0.1 by editing your /etc/hosts file.
A habitat can be configured to act as a rendez-vous server by setting the property
messenger.is.rendez-vous=true
Other habitats can be instructed to use one or more rendez-vous servers by setting the property
messenger.use.rendez-vous.urls=URLs
where URLs is a list of URLs of the form
tcp://host:port
or
http://host:port
It is preferred to list both TCP and HTTP URLs for a rendez-vous server, if a the server is listening on both TCP and HTTP.
To be able to run as a relay server, two jars files need to be present in the lib/runtime directory. These jars are servlet.jar and jetty.jar, and noramlly they are already available in the lib/runtime directory.
If these jars are not present in the above directory, you may encounter an exception, with the following message as the first line:Exception in thread "main" java.lang.NoClassDefFoundError: org/mortbay/util/ThreadPool. To remedy this, place the above jars in the lib/runtime dir.
A habitat can be configured to act as a relay server by setting the property
messenger.is.relay=true
To act as a relay, the habitat must be configured to accept HTTP traffic: the following property must be set
messenger.listen.http=true
Futhermore, a relay server must also be configured as a rendez-vous server, by setting the property
messenger.is.rendez-vous=true
Other habitats can be instructed to use one or more relay servers by setting the property
messenger.use.http.relay.endpoints=endpoints
Where endpoints is a list of
host:port
entries. Each entry specifies a HTTP endpoint of a relay server. Note that the entries are not URLs, do not specify tcp:// or http://. Since each relay server should also be configured as a rendez-vous server, the list of rendez-vous servers should also be specified.
The JXTA code creates a directory called .jxta in the current working directory. This directory is used to cache discovery information. At this point in time, it is not possible to create this directory in a different place. Make sure that if you use multiple VMs that they are started up in a different directory.
http://www.jxta.org. Contains general information on JXTA. You can also subscribe to various JXTA related mailing lists through this site.
Project JXTA: A Technology Overview (http://www.jxta.org/project/www/white_papers.html) contains an overview of JXTA concepts and terminology.
The javadoc of tryllian.are.messenger.MessengerProperties and tryllian.are.messenger.jxta.JXTAMessengerProperties and the ARE specification contain detailed usage information for all JXTA related properties.
The HTTP Messenger Plugin is the least complex of the messenger plugin Tryllian offers. It provides communication over TCP/IP using the HTTP Post protocol. This plugin does not support delivery failures/success notifications and does not support tunnelling through firewalls.
If you want to use the HTTP Messenger Plugin the only configuration option you need to make sure is correct, is the habitat name. The habitat name of your habitats must be a resolvable hostname.
You can select the HTTP Messenger Plugin by setting the messenger.registry.startmessengers option in habitat.properties to com.tryllian.messenger.jxta.HttpMessengerPlugin
The JMS messenger plugin can use one of the standard J2EE JMS providers such as JBOSS or Sun's J2EE reference implementation to facilitate message interchange between habitats. JMS is a robust, enterprise level messaging system. You can select the JMS Messenger Plugin by setting the messenger.registry.startmessengers option in habitat.properties to com.tryllian.messenger.jxta.JMSMessengerPlugin
As an enterprise-level messaging solution, JMS demands more manual configuration than any of the other options. This section describes the configuration of JMS for JBOSS or the Sun reference implementaion. It is also possible to use IBM Websphere, but this has not been fully tested at the moment of writing.
Begin by downloading the Sun J2EE Reference Implementation, version 1.3.1, from http://java.sun.com/j2ee/sdk_1.3/. Tryllian cannot, for license reasons, package the j2ee.jar file with the ADK.
After download, install the j2sdkee1.3.1. You can install the J2EEsdk on a local or remote machine as long the remote machine is accessible using the HTTP protocol.
During this chapter, we use J2SDK2EE_DIR to refer to the directory where j2sdkee 1.3.1 has been installed. Also, we use ARE_DIR to refer to the destination directory where ADK/ARE has been installed.
Make a copy of the following property files from the J2SDK2EE_DIR\config directory to the ARE_DIR\config directory:
orb.properties: Contains the host name where the j2ee server is running. Make sure the host name is valid and refers to the correct machine/host name.
security.properties: All security-related properties including the cipher key used to authenticate.
ejb.properties: http port used to make a connection, by default set to 9191.
Copy the j2ee.jar file from the J2SDK2EE_DIR\lib directory to the ARE_DIR\lib directory.
Add the following properties to habitat.properties:
messenger.jms.connectionfactory=TopicConnectionFactory
messenger.jms.topic.discovery=tryllian.habitat.broadcast
messenger.jms.topic.messages=tryllian.habitat.Topic
The values assigned here include the connection factory and Topic names used by messenger plugin to interact with the JMS provider. Make sure the specified connection factory and topics are already created in the j2ee server. To create the connection factories and topics, open a prompt in J2SDK2EE_DIR\bin and type the following:
j2eeadmin -addJmsFactory TopicConnectionFactory topic
j2eeadmin -addJmsDestination tryllian.habtat.Topic topic
j2eeadmin -addJmsDestination tryllian.habtat.Topic broadcast
To check if these items have been created succesfully, uses the following commands to get a list of factories and topics available:
j2eeadmin -listJmsFactory
This will result in a list of factories. You should see the following output, among other lines:
< JMS Cnx Factory : TopicConnectionFactory , Topic , No properties >
The next check is to enter:
j2eeadmin -listJmsDestination
This will result in a list of destinations where the following is included:
< JMS Destination : tryllian.habtat.Topic , javax.jms.Topic >
< JMS Destination : tryllian.habitat.broadcast , javax.jms.Topic >
Before starting the habitat, you need to set the properties used to lookup the connection factory en corresponding Topic objects. The JMSMessengerPlugin uses this information in order to contact the j2ee environment and send and receive messages using the ConnectionFactories and Topic objects these properties refer to.
In other words, factory and topic names specified by these properties must exist in the j2ee environment and accessible through jndi context. To achieve this, make sure the last step in the previous section is performed correctly.
Before starting the habitat, make sure your j2ee server is already started and running. To run the j2ee server, open a prompt in J2SDK2EE_DIR\bin and type the following:
j2ee
This will start the j2ee server and initialize the connection factories and topics. Now you are ready to run the habitat and the messenger plugin. Open a prompt/Shell in ARE_DIR\bin and run the following batch file to start the habitat and JMS plugin messenger:
habitat+j2ee
This will start the habitat and a JMS Plugin Messenger instance using the j2ee reference implementation.
It is also possible to run the JMS Messenger plugin in a different VM than the habitat, as an external messenger. This will start an external JMS messenger that will register itself with the habitat. Open a prompt in ARE_DIR\bin and makes sure that the shell script or batchfile jmsmessenger+j2ee.bat is adjusted according to settings of your j2ee and habitat environment. Make sure the following arguments in this file are valid:
-Dorg.omg.CORBA.ORBInitialHost=YOUR_J2EE_HOST_NAME -Dmessenger.jms.connectionfactory=TopicConnectionFactory -Dmessenger.jms.topic.discovery=tryllian.habitat.broadcast -Dmessenger.jms.topic.messages=tryllian.habitat.Topic
Note that a habitat must be already running for this messenger to register and interact with. Open a prompt in ARE_DIR\bin and enter the following:
jmsmessenger+j2ee
Download jboss, version 3.X.X, from www.jboss.org
During this chapter, we use JBOSS_DIR to refer to the directory where jboss3.X.X has been installed. Also, we use ARE_DIR to refer to the destination directory where ADK/ARE has been installed.
Copy the following jar file(s) from the JBOSS_DIR\client\ directory to the ARE_DIR\lib directory:
jbossall-client.jar
jnet.jar
Add the following properties to habitat.properties:
java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
java.naming.provider.url=jnp://<YOUR J2EE HOST NAME>:1099
messenger.jms.connectionfactory=TopicConnectionFactory
messenger.jms.topic.discovery=tryllian.habitat.broadcast
messenger.jms.topic.messages=tryllian.habitat.Topic
Makes sure the values assigned to these properties are valid. The values assigned here include the connection factory and Topic names used by messenger plugin to interact with the JMS provider. Make sure the specified connection factory and topics are already created in Jboss.
To check if these items have been created succesfully, use the JMX console by opening a browser and going to http://<YOUR J2EE HOST NAME>:8080/jmx-console/
Before starting the habitat, you need to set properties used to lookup the connection factory and the corresponding Topic objects. The JMSMessenger Plugin uses this information in order to contact the j2ee environment and send and receive messages using the ConnectionFactories and Topic objects these properties refer to. In other words, the factory and topic names specified by these properties must exist in the j2ee environment and accessible through jndi context. To achieve this, make sure the last step in the previous section is performed correctly and succesfully.
Before starting the habitat, make sure your j2ee server is already started and running. To run the j2ee server, open a prompt in JBOSS_DIR\bin and type the following:
run
This will start the Jboss server and initialize the connection factories and topics. Now you are ready to run the habitat and the messenger plugin. Open a prompt/Shell in ARE_DIR\bin and run the following batch file to start the habitat and JMS plugin messenger:
habitat+jboss.bat
This will start the habitat and a JMS Plugin Messenger instance using the Jboss server.
It is also possible to run the JMS Messenger plugin in a different VM than the habitat, as an external messenger. This will start an external JMS messenger that will regsiter itself with the habitat. Open a prompt in ARE_DIR\bin and make sure the jmsmessenger+jboss.bat is adjusted according to settings of your j2ee and habitat environment. Make sure the following arguments in this file are valid:
-Dorg.omg.CORBA.ORBInitialHost=<YOUR J2EE HOST NAME> -Djava.naming.factory.initial=org.jnp.interfaces.NamingContextFactory -Djava.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces -Djava.naming.provider.url=jnp://<YOUR J2EE HOST NAME>:1099 -Dmessenger.jms.connectionfactory=TopicConnectionFactory -Dmessenger.jms.topic.discovery=tryllian.habitat.broadcast -Dmessenger.jms.topic.messages=tryllian.habitat.Topic
Note that a habitat must be already running (see previous section on running habitat+jboss) for this messenger to register and interact with. Open a prompt in ARE_DIR\bin and type the following:
jmsmessenger+jboss.bat
Normally you start the habitat by running habitat.bat, but it is also possible to start the habitat with:
java -jar lib\are-startup.jar [habitat.xml]
This is the command that is executed by the habitat.sh or habitat.bat script.
There are multiple ways to give agents access to extra libraries or make libraries available to the runtime. Normally when an agent need access to external libraries it is best to add them to the agent DNA file either by editing the agent descriptor by hand or by using the dnacomposer. By doing this agents can always be sure that the extra library is available when they travel to another habitat.
Another way is adding the extra libraries to the lib\jdbc directory when they are JDBC drivers that the platform need access to (for example when you setup persistence to use another database than the standard one) or to the lib\runtime directory if both the agent runtime environment and the agents need access to these libraries. Note that libraries added this way make them available on the local habitat only, when an agent moves to another habitat it cannot rely on the fact that these libraries will be available there.
If you do need to add extra libraries to the standard classpath (so they are available to both the ADK agent runtime environment, any submodules like the persistence JDBC driver support and the individual agents) you need to be aware of the following: When you use the -jar option to specify lib\are-startup.jar the java command ignores any other Classpath setting (either through the environment variable CLASSPATH or through the -classpath or -cp command line options). So if you really need to add extra libraries on the classpath then you must run the main class com.tryllian.are.startup.StartHabitat by hand as follows:
java -classpath lib\are-startup.jar
com.tryllian.are.startup.StartHabitat [habitat.xml]
The argument in all cases is the xml file defining the habitat. When you do not start the habitat through the normal habitat.sh or habitat.bat scripts make sure that your current working directory is your standard ADK_ROOT directory by starting the habitat in <ADK_ROOT>.
The habitat can be run within certain debugger programs. These include Borland JBuilder 4/5, Netbeans 3.2 and VisualCafe 4.5. Version and platform information is described below.
The settings for the various debuggers are for debugging current agents. Code development should be done using a separate project because agent classes should not be in the class path. Most IDE's automatically include class path entries pointing to the code being developed. This prevents the habitat from loading the agent classes via its own agent class loader. An agent class loader is needed to provide security and mobility of agents.
Version used: 4 Professional Edition on Windows 2000. Version 5 Personal Edition on GNU/Linux does NOT work.
Set the properties using the "Project Options" dialog, "Run" tab. Edit the "VM parameters" text box. Include the -classic flag as the first argument!
Set the classpath by defining a library and adding it to the required libraries in the "Paths" tab of the "Project Options" dialog. Also, set the working directory in this dialog.
Set the main class using the "Project Options" dialog, "Run" tab selecting the main class. Note this only works if you defined the correct library in the previous step.
Some issues need to be taken into account when starting a habitat from within a debugger. First, you should not put the compiled classes from your project into your classpath. Agents are started from DNA files, with a separate class loader. Putting the agent class files onto your classpath disturbs this.
Second, the afc.jar file should not be in your classpath for the same reasons. This means that it is not possible to develop your agent code in the same project as the one you want to debug. For developing agents you need the afc.jar file.
The classpath for starting a habitat from within a debugger should contain are-startup.jar from the lib directory only.
In JBuilder, it is relatively easy to set up a debugging environment for a habitat. The following steps explain these steps.
Open Project Properties... (Project -> Project properies...).
Goto the tab pane Paths.
Change the Output path to some non-existing directory. The output path is where JBuilder puts compiled Java code.
Open the Required Libraries tab.
Add a new library.
Edit this library. Add the are-startup.jar jar from the lib directory to the library.
Close the Project Properties window to save the new properties.
Open the Project Properties window.
Open the Run tab of the Project Properties window.
Set the Main class for the application. This has to be com.tryllian.are.startup.StartHabitat. This class should be available from the list of classes and packages. If this is not the case, the jar library file are-startup.jar has not been added correctly to the required libraries (step).
Set the VM parameters for the application. This has to be the list provided above.
In this same pane, make sure that the options Compile before running and Compile before debugging are NOT selected.
Provide your habitat file as Application parameters by using --clean-db. This --clean-db parameter will remove the previously persisted agents in the database. is the habitat xml file, located in the habitat directory.
In JBuilder 4 Foundation and JBuilder 5 Personal Edition, the steps described above will enable you to run a habitat in a debugger. However, you will not be able to set breakpoints in these versions. The professional edition of both versions is capable of handling break points correctly.
Version used: 4.5 Enterprise Edition on Windows 2000. Expert Edition may also work.
Set the properties using the "Environment Options", "Virtual Machines" tab. Select the virtual machine you are using. Edit the "VM command options" to include the property settings mentioned above.
Set the classpath using the "Project Options" dialog, "Directories" tab. Set the "input class files" entry. Set the source location using the "source files" entry.
Set the main class using the "Project Options" dialog, "Project" tab by typing in the main class name (see above) in the "Main class" text box. If needed, also set --clean-db and the xml filename argument using the "Project Arguments" text box.
Eclipse is the exciting new IDE co-created by IBM and the wider Open Source community. Eclipse supports creating agents, building agents using ANT and debugging agents. This is a short tutorial showing how to setup an Eclipse project for the agent-template included in the ADK using Eclipse Eclipse 2.1.2.
Paths will be shown "unix style", with forward slashes. On Windows use backslashes where appropriate.
We assume that you have already installed the ADK. We'll refer to the ADK root directory as 'ADK/'.
We don't want to do development within the ADK root directory, so first copy the ADK/agent-template directory and its contents to your wherever you prefer to do your development work. We'll refer to this working copy as 'agent-template/'.
Now the Java Settings for the project can be edited.
On the tab Source
- ADK/lib/afc.jar
- ADK/lib/are.jar
- ADK/lib/are-startup-jar.jar
tThis completes the Java settings. Click Finish. Eclipse now generates the project structure, resulting in tree with all project files in the Package Explorer pane.
To be able to deploy and run an agent, its Java classes and other parts should be combined into a DNA file. This is done using the DNA Composer which in turn is run using an Ant script. Eclipse will now be configured to run the DNA Composer when building the project.
First of all the Ant tool included in Eclipse should be given access to tasks for running the DNA Composer:
edit agent-template/build.xml, changing these lines:
<taskdef name="dna"
classname="com.tryllian.tools.DNAComposerAntTask"/>
into:
<taskdef name="dna"
classname="com.tryllian.tools.DNAComposerAntTask"
classpath="lib/trylliant.jar"/>
Now running Ant will be made part of the build process:
In tab Main
Now go to tab Targets
And click OK again to close the Project properties dialog.
Now check that building the project does indeed run the DNA Composer, by selecting Project - Rebuild all from the menu. The console should show the output of Ant building the agent.jar and the example.dna, ending in 'BUILD SUCCESSFUL'.
After the steps above you can build the example agent in Eclipse and then run it from the command line as described in the documentation. But running the agent within Eclipse can not only be convenient, it also allows you to use Eclipse's debugging facilities on your agents (breakpoints, tracing etc.).
This requires the creation of a configuration:
Go to tab JRE
Go to tab Classpath
Only are-startup.jar should be listed. The others are dynamically loaded by the habitat itself.
Now go to tab Main
Go to tab Arguments
Now you should be all set to run the Example agent: click on Run.
In the Console pane you should see the habitat startup ending with: '[Example] Hello World'. Stop the habitat by clicking the red Terminate button on the top right side of the Console pane.
You can re-run your agent by clicking one of the Run shortcuts on the tool bar. When changing the code of the agent, remember to rebuild your project in order to update the DNA-file of the agent.
To debug your agent, use the Debug... instead of the Run... option. You can for example set a breakpoint on the line:
addTask(new LogTask("Hello World"));
in ExampleMainTask.java and then use the stepping options from that point on. You may get some warnings when stepping into parts of the ADK since it's source code won't be available.