From the most basic point of view, Messages must consist of four Maps and two AgentURIs. The Maps are used for the content and meta information, while the addresses specify the sender and receiver of the message.

The four maps are explained in the following diagram:

These maps can be reached through the API with the functions specified in the Javadoc.

As usual, these Maps are used to store key-value pairs. However, the Maps used in ARE Messages have some extra restrictions.

The first restriction is that keys must only be Strings. The Maps must use a case-insensitive comparison on those keys; however, they must be case-preserving.

The second restriction says that values, too, must be Strings. This is enforced for several reasons:

Note that the ARE must allow the contents of the message maps to contain XML data.

The sender and receiver part of a message are both AddressURIs. The receiver must be specified by the agent sending the message. The sender must automatically be filled in by the ARE.

Messages have sensible hashCode and equals methods. However, equality of messages is co-dependent on equality on addresses. AddressURI's are not resolved before equality is determined. See Section 3.3.6, “How are addresses resolved?” for rules on address equality.

At this point, only the contents for the meta and content maps have been defined. These contents are explained in Table 3.1, “Keys and values in the Meta map” and Table 3.2, “Keys and values in the Content map”.

Note also that the contents of the content map are different for every content-type. This specification only coverts the type application/x-tryllian-fipa.

Agents may add other fields to these maps. However, other agents are not required to understand those fields. For the sake of compatibility, it is advised that agents do not add those fields.

The Tryllian FIPA dialect was based on the FIPA specs that were available in January 1999. Therefore, the Tryllian dialect deviates somewhat from the current specs.

This section describes the general format of the Tryllian dialect and the mapping to Message keys and values.

In order to provide agents with a sense of certainty, the ARE must meet the following requirements:

When a message to a local agent can not be delivered, the ARE must throw a NoSuchAgentException. When a message to a non-local agent can not be delivered, the ARE must send a failure message of the type DeliveryFailure.

This version of the ARE does not specify security on a message level. However, the following assumptions are valid:

The external format of messages (i.e. the format of messages as used by messenger plugins) is dependent upon the messenger plugin and may impose additional restrictions on the the possible content of messages. Messenger plugins must however support the sending of XML encoded content.

The central idea behind the messenger plugin architecture is that the habitat should have as little to do with external messaging as possible. All responsibility for queueing, message format translation and error handling must be the responsibility of the messenger plugin.

The messenger plugin must send delivery failure notices back to the sending agent and it should send delivery success notices back to the sending agent when so desired.

In the event that the destination habitat is unknown, the plugin must notify the sending habitat as soon as possible, allowing that habitat to resend the message using another messenger plugin, if possible.

The messenger registry may assume that calls to the messenger pluging are synchronous and does not implement any form of queuing. A plugin should thus immediately return with a failure if the destination is not reachable. (However, the messenger registry may be smarter than that.)

There are two possibilities for deploying messenger plugins: either they are installed at startup inside the habitat VM, or they are started up in their own VM and contact the habitat through RMI. (Once the management framework has been defined, it will be possible to install, stop and start messenger plugins inside the habitat VM.)

messenger.registry.startmessengers=com.tryllian.messenger.jxta.JXTAMessengerPlugin
      

habitat.identification.port=50010
      

messenger.rmi.remote-allowed=true
        

A habitat can use zero or more messenger plugins to transport messages to and from the outside world. This outside world is not necessarily another habitat; it is equally likely that a habitat will want to communicate as directly as possible with another application, a J2EE server or a gui.

Consider the last example: a GUI intended to give a user control over the application formed by Tryllian's dynamic smart components. Previously, the GUI would have been built around the JXTA standalone messenger API. This meant that the GUI necessarily ran in a second JVM and that all communication between GUI and application was transported over JXTA pipes.

With the flexible messenger plugin architecture, it is an easy task to create a GUI that runs either inside the same JVM as the smart component application, or in a second JVM, as deployment considerations demand. In the first case, all GUI commands arrive at the smart components with the speed of local messaging. In the second case, there is an RMI layer between the GUI and the application, but that presents much less latency than JXTA.

The plugin must implement the following interfaces:

The MessengerRegistry implements or provides objects that implement the following interfaces:

The ping tool is a flexible ping application that can use any messenger plugin to determine whether a habitat is alive and reachable.

An address is essentially an URI, as defined in the URI Specification. A well-formed address follows the syntax that follows.

The habitat part of an address is the name of the addressed habitat. A habitat's name must have at least its last part starting with a letter. This is done in order to maintain compatibility with DNS. Habitat names are therefore treated case-insensitive as well.

The agent part of an address is corresponding with the agent's registration on the destination habitat. The agent part is treated case-sensitive. This part is considered to be hierarchical.

The query part of an address can be used for special directives, e.g. an explicit marker for a group or multicast address. (Support for the query part is not included in the current release of the ARE.)

Any character that is not allowed as a regular character, can be included in an agent part of the address. This can be done by escaping each octet of its UTF-8 representation. An octet is escaped by using the two digits of its hexadecimal representation, preceded with a "%".

A few examples of well-formed addresses. The first is a location address, the others form addresses of agents. The last is used for an agent named Léon.

A habitat name is set by the habitat on startup. This can be set in various ways. If no name is set, the ARE must set an appropriate name.

The agent part of an address is handled by the habitat referred to in the address (the habitat in the habitat part of the address). How an agent has to register itself within this habitat is left to that habitat.

An address can be created by combining the scheme name with a habitat name. This will create an location address. Appending a (properly escaped) path of an agent will create an agent address. Both types are implemented in AddressURI.

An API is provided for creating addresses. It is strongly recommended developers use this API, instead of manipulating addresses directly as Strings.

An address is resolved when it is used. This happens for instance when a message is sent. Resolving a message occurs in two steps:

If the habitat or the agent in the designated habitat cannot be found, the address is unresolvable.

An address is equal to another address, if the following rules are fulfilled:

Habitat IDs are used to uniquely identify a habitat. When a habitat is started, its ID is extracted from its associated certificate. If no certificate could be found, or if no ID was specified in the certificate, a local ID is generated from the IP address of the host the habitat is running on and the value of the Identification Port property. (Note that in earlier versions of the ADK the JXTA tcp-port was used in the computation of the habitat ID. Since a single habitat can now use more than one JXTA messenger and consequently can be associated with more than one JXTA tcp-port, this has been changed.) It is also possible to set the property messenger.habitat-id to a fixed value.

Habitats with local IDs can be restricted in communication with other habitats. If more than one habitat using the same version and type of a messenger plugin that have the same habitat id reside in a local area network, the result is undefined but likely to result in disrupted communication.

For more information on extracting IDs from a certificate, refer to Section 6.1.3, “X.509 Certificates”

AgentIDs can be used to uniquely identify an agent on a habitat. If both the grantor and the grantee part of the agent are not local, the ID is considered globally unique ^[4].

As opposed to Habitat IDs, Agent IDs can not be stored in a certificate.

The ARE supports three ways of using JNDI. They are

Obtaining the InitialContext can be done in two ways. The first one is by calling the ExecutionEnvironment.getJNDIContext() method. However, the ExecutionEnvironment is only available to agents.

A more generalized method for obtaining the InitialContext is already specified in the JNDI spec. By filling a Hashtable with specific properties and passing this to the InitialContext constructor, a relevant Context can be obtained.

The properties are described in Table 3.5, “”

All Contexts should only allow AddressURIs to be bound. This is done to prevent abuse of the namespace and to ensure a correctly functioning garbage collection process.

The ADK provides an elaborate namespace which reflects its infrastructure and provides a great deal of flexibility. The namespace consists of atomic names, separated by the forward slash (“/”), ordered from left to right.

The top-level namespace of the ADK is aptly called adk. No other namespaces have been defined so far. However, implementations may provide extra namespaces such as ejb if needed.

Within the adk namespace, every Habitat^[5] has its own namespace. The canonical name of this namespace is its HabitatID. The ARE may provide symbolic links such as the habitat name.

The Habitat namespace can be subdivided into other namespaces in a hierarchical fashion.

Hierarchically under the habitat namespace, there are three predefined namespaces. The first one is tryllian, this namespace must be managed by the ARE.

The second namespace is services, which is used with the service-address and related protocols. It contains a context for each provided service, which contains bindings for each agent that offers (registered itself as) that service.

The last predefined namespace is user. This namespace is open, meaning that everyone has read and write access to it.

The tryllian namespace is further subdivided in two namespaces: agents and system-agents. The first contains the canonical addresses of the agents resident in this habitat. The second contains the addresses of the System Agents by their name.

        adk/12345678-8765432165487657/tryllian/agents/12345678-8765432112345678
        adk/12345678-8765432165487657/services/echo
        adk/98765432-F52CED77423978AB/user/telephony/mrtelephone
        adk/769714FB-C57831BD89784321/tryllian/system-agents/transporter
      

Normal agents should register themselves within the user space. This is done using an ordinary bind operation. For every application, agents should register themselves under an application specific context, which should be named like their Java package names.

Service Agents are allowed to register themselves under the services namespace. However, they must follow the following conventions:

In order to prevent unreadable JNDI names, the ARE must also understand the “Symbolic names”. There are currently only one symbolic name.

Resolving JNDI names using the lookup method is done in several stages. First, the symbolic name .: is resolved.

When all .:s have been resolved, the name must be looked up according to the JNDI spec.

At this point it should become apparent why Service Agents must use the conventions shown in Section 3.5.3, “Registering an address”. Since all Service Agents registered under the same context should perform exactly the same task, it does not matter which Service Agent is actually addressed ^[6]. This makes the actual number of Service Agents completely transparent.

Within the adk namespace, every known habitat is represented by its Habitat ID. So calling listBindings("adk") should give you a NamingEnumeration containing all currently known Habitat IDs (including the Habitat ID of the running platform).

Normally a habitat is known when the messenger plugin has received a message from another habitat or has received an advertisement of the other habitat through peer discovery. The ARE should make sure that a newly discovered habitat can be found in the adk namespace within a reasonable time (30 seconds). The ARE may discard Habitat IDs from the adk namespace after a certain period of inactivity (5 minutes).

In the Habitat namespace on the running habitat the tryllian and user namespaces are visible. For remote Habitat namespaces the ARE may replicate this information from the remote habitat but this is not required (and currently not implemented). If this information is required it may be available through The jndi-resolve protocol

For most contexts it is required to have the tryllian.naming.JNDIPermission in order to bind in them. The only exceptions to this are

The JNDIPermission is currently an all-or-nothing permission.

As explained in Section 3.3, “Addresses”, an address is resolved in two steps. The last part of an address is resolved by the addressed habitat. The habitat resolves the local part of an address, the agent part, using JNDI.

The agent part of an address is a 1-on-1 mapping to the context of the current (effective) habitat. In other words, the agent part of an address can be translated to a JNDI binding, by prepending adk/.:/ to it.

The reverse is true as well. A full JNDI Name can be used to create an address, by using the full name minus the two first parts, which are adk and the habitat-ID.

With the above described mapping of addresses to JNDI, addresses can be resolved to the actual addressed agent in the referenced habitat. This is done according the following mechanism:

If no address was found with the above procedure within the given limitations, the conclusion will be that there is no such agent. This will therefore result in a NoSuchAgentException, a delivery failure message or another applicable error.

Although addresses are used throughout the ADK for communication between agents, any agent has a unique identity, its ID. This ID is the only unique, unchangeable, identification an agent has. Therefore, an address should resolve to an ID, before the ARE is able to deliver messages.

All IDs of the agents in a habitat are registered in JNDI as well. These are all registered in the context adk/.:/tryllian/agents. The name of a binding in this context is restricted to the format of an IDReference. Therefore, if an address points to a JNDI binding in the agents context, this results in the ID of the addressed agent. This allows addresses to be resolved to IDs, as described above. The object bound under the ID-name, is the canonical address of the agent, which is described below.

Since each agent has a unique ID, which is bound in JNDI, each agent has an unique address as well. This address is used for instance on all messages the agent sends. The default value for this address is directly derived from its ID. For example, an agent will have the default canonical address agent://habitat.name/tryllian/agents/12345678-9876543210ABCDEF. This matches the ID of the agent in the adk/.:/tryllian/agents context on the habitat with the name "habitat.name".

Although this will properly identify the agent, it is not always the most human readable form of addresses. Therefore, an agent is allowed to alter its own canonical address. An agent can set its primairily used address to a more applicable named one.

An agent can set its canonical address in two steps:

The (incomplete) example below shows a way to set ones canonical address.

String desiredName = "user/App/foo";
ExecutionEnvironment env = ExecutionEnvironment.get();
Context context = env.getJNDIContext();
// Register the ID-based address under the new name
context.bind(NamingConstants.CURRENT_HABITAT_CONTEXT + desiredName,
             env.getCurrentAgentAddress());
// rebind the canonical address to the new address
context.rebind(NamingConstants.AGENTS_CONTEXT + myID,
               new AddressURI(desiredName));
      

There are a couple of constraints applied on the canonical address of an agent. These constraints ensure consistency and security.