6.Creating and Launching a Generic Agent

6.1 Agent Credentials

An agent is a principal in the system with a unique identity (its URN). When an agent is created, a
credentialsobject is assigned to it. An agent can be created by instantiating a subclass of the base
Agent class. A newly created agent is a passive object. It is activated by executing its start method,
which is defined by the base agent class. An agent can itself create and launch child agents to perform
parts of a task concurrently at different hosts.

The agent's creator launches it to an agent server and optionally specifies a method to be invoked on the
agent. The method specification is detailed below under the discussion on migration primitives. If the
method specification is omitted, by default the server executes the (parameter-less) run method. The
base class provides an empty implementation of the run method, which does nothing. This method can
be overridden by a derived class as appropriate.

The generic agent class defines the following public methods. Their functions are discussed below:

   public void start (URN destination, MethodSpec action)
        public void start (URN destination) // default "run" method is executed
        public final void agentEntry ()
        public final void agentExit ()
        public abstract void arrive()
        public abstract void depart()
        public void run()
        public void colocate (URN target)
        public void colocate (URN target, MethodSpec as)
        public void meet (URN reportTo, MethodSpec as)
        public void recallCommand (URN whoInvoked, URN reportTo)

The following example shows a simple agent which is derived from the base agent class. Once created,
this agent is dispatched to an agent server using the start method. When relocated at that server, the agent
will execute the run method. This method prints a hello message. It obtains the agent's name from the credential
object, and it obtains the name of its current host server using the agent environment variable host and its
method getHostURN.This simple agent will terminate at that server unless one defines some other migration action i
n the depart method, which is the last method executed by an agent at its current server.

    public class HelloAgent extends Agent
   {
       public HelloAgent(Credentials credential) {
            super(credential);
       }
        public void run() {
            System.out.println("Agent "+ credential.name +"says Hello to "+ host.getHostURN());
        }
    }

6.1 Agent Credentials

When an agent is created, its construction is given an object of credentials class. A credentials object
contains the URNs of the following objects:

                    Owner            User URN under whose authority the agent is created,
                    Creator          URN of the application creating the agent
                    Guardian       URN for the guardian object to handle agents with exceptions
                    Name             URN for the agent
                    CodeBase      URN for the code base server which contains agent's classes. Typically the
                                              application launching an agent would itself act as the agent's code server.

A credentials object can contain other objects, such as its agent's El-Gamal public key and DSA
public key. Most application do not need to include these keys with an agent's credentials.

The following code fragment is a simplified version of the HelloWorld.java class of the HelloWorld
demo program. The main difference is that the HelloAgent is not an ItinAgent, but derived from
the base Agent class.

    URN agName = null;
    try {
        agName = new URN ( myURN.toString() + "/helloagent");
    }
    catch (MalformedURNException e) {}

    AjantaUser user = new AjantaUser();
    /* Owner should be set to the user who is running this client program */
    AjantaIdentity owner = new AjantaIdentity (user.getUserURN().toString());

    /* Guardian for any agent created by this client will be this "server"*/
    AjantaIdentity creator = new AjantaIdentity(myURN.toString());
    AjantaIdentity guardian = creator;

Credentials agCred = new Credentials (owner, creator, guardian, agName, myURN);

The above code fragment first constructs a URN for the agent. The agent's name is constructed
by appending the string "helloagent" to the URN of its creator application.

AjantaUser class object allows a program to access the properties related to the user running
a program. The owner is set to the URN of the user running this agent creating this application.
The guardian for this agent is the same as its creator.

The code base server for this agent is set to be the URN of its creator. Thus, when this agent's
classes are needed by a remote server, it would contact the creator to supply those classes.

A HelloAgent object can now be created by simply calling its constructor as shown below:

HelloAgent ha = new HelloAgent(agCred);
ha.signOwner();

    registerAgent(ha);                                     // Register the agent with the Ajanta Name Service
    ha.start( host, DestServerURN, null);         //   Launch agent to the DestServer to execute the
                                                                  // default run method.

In the above code fragment, first an agent object of class HelloAgent is created. It is then signed by
the owner's DSA key. Next , this agent's URN is registered with the Ajanta name service. Finally, using
the start method of the base Agent class, this agent is sent to a server, whose name is DestServerURN.
This start method requires three parameters: the first is a reference to the agent creator's host reference
i.e. AgentEnv object, the second parameter is the URN of the destination server, and the third
parameter is the a MethodSpec object. If the method specification in the third parameter is null, then the
agent executes its default run method at the destination server.

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