drm.agentbase
Interface IAgent

All Superinterfaces:
java.lang.Runnable, java.io.Serializable
All Known Implementing Classes:
Base, Agent

public interface IAgent
extends java.lang.Runnable, java.io.Serializable

This interface defines the agent functionality required by the Base. To be able to live on a Base, an object has to implements this interface.

An agent has a name. This name has to conform to the rule that getType()+"."+getJob()+"." has to be a prefix of getName(). The job name must be unique, ie two different jobs must not use the same name. Of course, one job can contain many agents.


Method Summary
 java.lang.String getJob()
          Returns job name.
 java.lang.String getName()
          Returns the name of the agent.
 java.lang.String getType()
          Returns type identifier.
 boolean handleMessage(Message m, java.lang.Object object)
          Called when the agent has a new message.
 void onArrival(Address from, Address to)
          This is called when the agent is put into a base.
 void onDestruction()
          This is called before the agent is destroyed by the base.
 void setBase(IBase b)
          This is called by the base when the agent is received.
 int version()
          Returns the version of the agent.
 
Methods inherited from interface java.lang.Runnable
run
 

Method Detail

onDestruction

public void onDestruction()
This is called before the agent is destroyed by the base. This includes the case when the agent is dispatched. It is called after the serialization of the agent being sent to another base. IMPORTANT: Every implementation must make sure that every thread of the agent stops (if running) or doesn't start after the invocation of this method. After calling this method the base will deny all services to the agent.

onArrival

public void onArrival(Address from,
                      Address to)
This is called when the agent is put into a base. At this time the base is already set using the setBase(IBase) method.
Parameters:
from - The address of the base from which the agent was sent. If the agent has never been on any base it is null.
to - The address of the local base at the time of the arrival. It is not guaranteed to remain valid trough the lifetime of the agent. If the agent has never been on a base it is null.
See Also:
setBase(IBase)

getName

public java.lang.String getName()
Returns the name of the agent.

getJob

public java.lang.String getJob()
Returns job name. Every agent is part of a job. This returns the name of that job.

getType

public java.lang.String getType()
Returns type identifier. Apart from being part of a job, every agent has a type. This is useful when having to make a difference between agents within a job.

setBase

public void setBase(IBase b)
This is called by the base when the agent is received. On one base it is called only once. The implementation of the method should store this object so that the agent can use the services offered by this interface.
Parameters:
b - The Base that hosts the agent.

handleMessage

public boolean handleMessage(Message m,
                             java.lang.Object object)
Called when the agent has a new message. The agent can reply to the message by simply using the method m.setReply(Object) in this method. The sender of the message can read the reply through the IRequest interface returned by fireMessage, via calling getInfo("reply").
Parameters:
m - The message to handle.
object - The object that is wrapped in the message. If null then there is no binary content or it is not a serialized object (in which case it can be read using Message.getBinary()).
Returns:
If the message could be handled succesfully (i.e. it was known to the implementation and no errors occured) returns true, otherwise false.
See Also:
Message.setReply(Object), IBase.fireMessage(Message)

version

public int version()
Returns the version of the agent. This version is the DRM version the agent was designed to run on. Hosting the agent will be attempted in each case by the base anyway, but it allows a finer error control.
See Also:
Base.RELEASE_VERSION