Agents are deployed by storing their code and resources in a so called DNA file^[14]. DNA files are signed by their developer, thus making it possible to assign permissions to agents. From a single DNA file, multiple agents can be created.

The ARE makes it possible for agents defined in different dna files to share jarfiles. The agent descriptor DTD defines the shared-ref tag for this. Shared references point to jarfiles external to the DNA file. Jarfiles contained in a DNA file can not be shared by agents created from different DNA files.

DNA files are created using the command-line DNA-composition utility dnacomposer, which has the following features:

A DNA file is a jarfile that contains jarfiles, an agentdescriptor file, and zero or more resources. The individual jarfiles are signed, just like the entire DNA file. Signing the entire DNA file ensures that the composition itself is not changed, while signing individual jarfiles makes it possible to optimize the transport of individual jarfiles.

The agentdescriptor file is a description of the various parts that are needed for an agent to function, using XML syntax and the DTD specified below.

Graphically, DNA files have the following structure.

myagent.dna
|
+----META-INF
|    |
|    `<security information>
|
+----descriptor.xml
|
+----jarfile.jar
|    |
|    +----META-INF
|    |    |
|    |    `<security information>
|    |
|    `----<class files>
|
`----resources.jar
     |
     +----META-INF
     |    |
     |    `<security information>
     |
     `----<resource files>


    

The agent descriptor is an XML file specifying the constituent parts of the agent. Furthermore, it contains some meta information on the agent itself. The agent descriptor must conform to the following DTD:

<!--
The top tag is "agentdescriptor".
It has a "version" attribute which should be set to the value "1.0"
-->
<!ELEMENT agentdescriptor (agenttypedescription, target+)>
<!ATTLIST agentdescriptor
        version   CDATA      "1.0"
>

<!-- 
The first subtag under agentdescriptor is agenttypedescription.
This is a string describing, in human language, the functionality
of this type of agent.
-->
<!ELEMENT agenttypedescription (#PCDATA)>

<!--
The second subtag under agentdescriptor is target.
There can be multiple targets for one agentdescriptor.
It has a unique id for an attribute.
-->
<!ELEMENT target (environment, shared-ref*, file*)>
<!ATTLIST target
        target-id   ID      #REQUIRED
>

<!--
The first subtag under target is environment.
Because of the fact that programming languages define themselves in various
ways, each environment has its own subtag. For now, only java is permitted.
-->
<!ELEMENT environment (java)>

<!--
A specific version of the Java language can be defined in terms of
various specifications:

One or more comma separated supported ARE versions
One main class for the agent
-->
<!ELEMENT java (EMPTY)>

<!ATTLIST java
        areversions CDATA   "1.3"
        agentclass  CDATA   #REQUIRED
>

<!--
Another subtag of target is file. This is a string defining a file
that is part of the necessary 'luggage' required for running the
agent on this/these target(s). If located in a subdirectory of
the jar, forward slashes are used to indicate subdirectories.
-->
<!ELEMENT file (EMPTY)>
<!ATTLIST file
    name    CDATA   #REQUIRED
>

<!--
Some files are more basic than others. They are usually shared among
multiple agents, regardless of other luggage. Special files are used to
indicate such files.

The type of a shared reference indicates how to the system should treat
the file. Currently only the value 'stdlib' is allowed; its value is
currently not used.
-->
<!ELEMENT shared-ref (EMPTY)>
<!ATTLIST shared-ref
	type    (stdlib)       "stdlib"
	name    CDATA           #REQUIRED>

    

<!-- A descriptor for the DNA file of the Hello World agent. -->

<agentdescriptor>
    <target target-id="standard">
        <environment>
            <java areversions="1.3"
                agentclass="tryllian.scenarios.helloworld.HelloWorldAgent"
            />
        </environment>
        <file name="helloworld.jar"/>
        <shared-ref type="stdlib" name="afc"/>
    </target>
</agentdescriptor>

      

Shared references are references to jarfiles outside the DNA file. In the agent descriptor they are specified using a short name. When an agent is deployed, this name must be resolved. When the DNA file is created, the name should not be resolved.

Name resolution is done through a catalog file, which must be named dna.catalog. This file resides in the ARE configuration directory^[15].

The catalog is a simple property file which maps names to URLs. These URLs can point to other computers, as long as the associated data can be retrieved. URLs can contain properties defined in the habitat properties.

# Example DNA catalog
my_reference=file:${are.home}/lib/somefile.jar
your_reference=http://www.your_host.eu/euro.jar
        
      

It is important that the files pointed to by the shared references are themselves signed as well. If they are not signed, they will get the security role assigned to unsigned code, which is very restrictive.

Resources, such as images or XML files, can be stored inside the DNA file by first wrapping them in a jarfile. This can be a jarfile already used for storing code, or a separate jarfile.

Agents can then retrieve these resources from their DNA file as they would with ordinary jarfiles, i.e. by using the Class.getResource and Class.getResourceAsStream methods. As in any other Java application, such resources are not modifiable.

When a DNA file is created, the following happens:

When a DNA file is updated, the following happens.

Agents can use the dnacomposer by requesting an object of the type tryllian.are.security.DNAComposer.

It is also possible to use the dnacomposer command-line tool, as specified in The DNA composer tool.

While the command-line tool has a sensible default for the jarpath, the API does not; it must be set.

There are a few properties that can not be set in the habitat.properties file because they are required for bootstrapping. These properties can be given at the command line using the java -D options.

All other properties can be set in the habitat.properties file or on the command-line.

These options are referred to from the habitat.properties file.

Sometimes the ARE is not able to discover its own identity. There are three properties that can be set in these cases.

Even though Java does not offer much resource protection, the ARE provides some safeguards to prevent a Habitat from starving your system of memory or CPU.

Apart from all the certificate related settings, the ARE also offers some properties to influence secure behavior.

The behavior of the logging system can be slightly modified using a number of properties. For vastly different behavior, it is necessary to create a subclass of com.tryllian.log.LogSystem.

The ARE currently supports three kinds of LogSystems: the com.tryllian.log.system.DefaultLogSystem, which writes monolithical logfiles, the com.tryllian.log.nullsystem.NullSystem, which does not output any logging information, and the com.tryllian.log.system.RotatingLogSystem, which sends its logs to the Unix rotatelogs command, resulting in more, smaller logfiles. The latter is especially useful for server situations.

The persistency support in the ARE is regulated by the following properties.

Besides persistency support with an external database, there are other persistent data that are stored outside of the database. See Section 7.4, “Habitats and Databases”.

The ARE messenger architecture consists of two parts: the messenger plugins on the one side, and the messenger registry on the other side. Messenger plugins utilize some transport mechanism, like JXTA or SOAP, to transport messages. Which properties are appropriate depends upon the type of messenger plugin.

The ARE officially supports seven kinds of databases. These are the following:

The database layer tries to do as much as possible in a generic way. However, due to small deviations from ANSI SQL 92 and optimalization, the setup of the database (creating tables and indexes) can not be generalized. The ARE must try to minimize the number of steps required for setting up a database.

All other database-related activities will be done using JDBC 2.0 and ANSI SQL 92. This will make it possible to quickly extend database support, if so desired. However, JDBC has two drawbacks: