The Ajanta computation model supports execution of  entry and exitactions whenever an agent
arrives  at a server or eaves. The base agent class implements system-defined entry and exit actions
using agentEntry and agentExit methods, respectively. These methods are declared  final.

The application specific entry action is defined by the arrive method of the agent. The base Agent
class defines an abstract arrive method, which must be defined in the application specific agent class
inheriting from the Agent class, to execute an entry protocol at every host it visits. The agent thread
first executes the arrive method, and then invokes the method specified in the agent's migration
request. This method can perform any desired  consistency checks for the secure containers
mentioned  above,  and raise an exception if any tampering is detected. It can also execute some
resource  acquisition actions using the resource access primitive described below. When the agent
finishes its task at a server, its application specific exit action, defined by the depart method, is
executed. The base agent class defines  an abstract method depart. In a derived class, the
programmer can appropriately implement this method to control the course of the agent by specifying
migration to another host.

5.1 Agent's Host Environment:

Each agent is bound to its host environment object through an object reference named host .  This is
an object of  AgentEnv class. Using this, an agent can request various services from its local host.
These include obtaining access to local resources,  registering itself as a resource, or requesting migration.
This host interface's methods are shown  in Figure 1. The functionalities of these methods are described
below.
 

public class AgentEnv
{
    // Migrate the caller to the specified destination and execute the
    // (parameterless) "run" method
    public void go (URN destination) throws java.net.UnknownHostException;

   // Execute the specified method on migration.
    public void go (URN destination, MethodSpec action)
                throws java.net.UnknownHostException;

   // launch an agent to a server to execute the specified action
   public void launch (Agent ag, URN destination, MethodSpec action)
        throws LaunchFailedException

    // Return the current host's name
    public URN getHostURN () ;

    // Resource registration
    public void registerResource (URN name, Resource obj);

    // Request an instance of (a proxy for) the named resource
    public Resource getResource (URN resourceName) ;

    // Create and install an RMI proxy for this agent.
    public void createRMIProxy (String remoteInterface) ;

    // recall, retract, or abort  an agent.
    public void recall  ( URN agentName );
    public void retract ( URN agentName );
    public void abort   ( URN agentName );
}

5.2 Resource Access Protocol

An agent can request access to a server's resources using the getResource primitive supported  by the
host environment. The  URN of the resource is specified as  a parameter to this method. The server
maintains a  registry of its local resources which  it wishes to make available to the visiting agents. The
getResource method returns a reference to a proxy object for a requested resource  based on the resource's
access control policy. The agent accesses the resource by invoking the methods of this proxy object. An agent
can also request its host to install for itself an RMI proxy interface. The server can enforce any desired policy in
granting or denying this kind of network resource access to an agent.

5.3 Agent Migration

Here we describe the basic migration mechanism that allows an agent to go from its current server to another
server. Higher level abstractions for travel plans, such as itineraries described later in this guide, are
implemented using the basic migration primitive described here.

Requesting Migration to a Server

An agent invokes the gomethod of its host environment object to migrate to another server. There are two
forms of the go primitive. In the first form, the agent specifies the URN of the server to which it wants to move
to;  after migration, agent's run method is executed at the destination server. In the second form,  an additional
parameter specifies the method to be executed at the destination server. Ajanta system uses Java's reflection
facility for specifying this. A method specification consists of a method name, the list of its formal parameter
types, and the list of actual parameters to be passed to this method on execution at the destination  server.
As in case of initial launch using the start method, if the method specification is omitted, the run method is
invoked.  If the agent transfer completes successfully, the go method never returns and the thread executing it
is terminated.  If however an error occurs during the transfer, it throws an exception, allowing the agent to
handle  the error.

Typically, go is called by an agent in its depart method.

Requesting Colocation

In some situations, the agent may prefer to colocate itself with another agent or an object/resource that
it needs to access or report to.  It can use the colocate primitive, specifying the URN of the target to
colocate with, and the method to invoke on it. If no method specification is given as a parameter to the
colocation  primitive, it invokes the default report method of the target object.

   colocate (URN target)         // Invoke target's report method
   colocate (URN target, MethodSpec action)

After moving to the target's host server, the agent obtains access to the target resource and invokes a
method  on it as specified by the action parameter. The default method to be invoked on the target is the
report method. This requires that the target object must be registered as a resource at its host server
and it must implement the  Reportable interface, which defines the report method. This method has one
parameter, which is a reference to  an agent object. The calling agent  provides to the target a reference
to  itself through this parameter. Hence, the  target can then examine the agent's state to take the required
action.

5.4 Agent Monitoring and Control

Ajanta provides three primitives -- recall, retract,  and abort-- to control an agent's mobility. It
might be sometimes  necessary to recall an agent back, because its owner/creator/guardian thinks the
agent has been  tampered with and  must not be allowed to continue, or because it has received results
from another agent sent  out to perform the same  task. At times the owner might have lost control over the
agent,  and may even need  help  from the hosting server to  ship the agent back. All these primitives are
invoked on the server hosting the  agent,  which  can be determined by  querying the name service. For
security reasons,  all of these control  primitives  are  executed only  when  invoked by  the agent's owner,
creator, or guardian.

recall

This method of an  agent server can be invoked through its RMI interface to recall an agent hosted at that
server.  The  server sends the agent  to its guardian or another object when the agent has completed its
execution at that  server. There are two forms of this primitive. In the one shown below, the agent is directed
to colocate with its guardian  and then  execute the guardian's report method.

   recall (URN agent)                       // report to Guardian

Using the other form, as shown below, the agent is directed to colocate with a specified target object, and
then  execute  its report method.

   recall (URN agent, URN ObjectToReportTo)   // report to the specified target

As an implementation detail, when an agent colocates at the target's host server, it first executes the meet
method,  which is passed as a parameter to the go primitive. This is an internal method in the base Agent
class,  not visible  to the programmer. This method obtains access to the target resource using the
getResource  primitive and invokes the specified method (or the default report method)  on it.
]
The server hosting the agent first authenticates the invoker of the recall method. If the invoker is either the
owner,  creator, or guardian, then t  sets some information in the agent's status object for it to migrate and
report to the designated target object after it has  completed its computation at the current server. This is
done  by the host server  by calling the agent's recallCommand method. As a part of the system-defined
exit protocol,  every agent checks its  status object for any pending recall. If a recall command is pending,
the agent invokes the  colocate primitive to  migrate to the target object's server. Once relocated there,
the agent invokes the report method of the target object.

retract

This primitive allows the caller to retract an agent back or send it to its guardian or another target  object
``immediately".  The agent is interrupted in whatever action it may be performing at the current host and is
directed  to  report to the  target immediately. The parameters to this call are the same as for recall.

abort

This primitive allows the caller to kill the agent immediately. This primitive is useful if, for example, an agent's
creator  feels that the agent should be immediately terminated because it  has been tampered with or has lost
control.This primitives is also useful to terminate all agents of an aborted application.

5.5 Exception Handling

During its execution, an agent may sometimes encounter exception conditions.  Some of these may be
anticipated by the programmer and handled within the agent's code.  If however, an exception is not handled
by the agent, the server then deactivates the agent and transports it to its guardian with the appropriate
status  information, including the exception that caused the agent to fail.  This migration is done using the
colocation mechanism described above.

Every agent also contains an AgentStatusobject, which is a vector containing the status of its execution at
the hosts visited so far. The state of the agent is described by the AgentStatus object. This vector contains
NotificationRecords. These records show whether the status of the agent is okay. If not, it contains the various
exceptions that the agent encountered and could not recover from. Each {\tt NotificationRecord} consists of
the  following attributes.

          boolean status OK;
          Exception ex;
          URN setAtServer;
          Date setAtTime;

A notification record with the appropriate exception object is added to the status,vector by the current server
when an agent is to be sent to its guardian for error recovery. The agent invokes the report method of its
guardian, which performs the necessary recovery actions as a part of the  report method's execution. The
guardian acts as the agent's global exception handler. The guardian  can inspect the agent's state, and if a
ppropriate, modify it and re-launch the agent.  The agent may be asked to restart its itinerary, or sent back
to the host where it encountered the exception for resumption of its activities.

 GO  TO- Top of this page    Previous Chapter   Next  Chapter    Table of Contents of this Guide