drm.agents
Class Agent

java.lang.Object
  |
  +--drm.agents.Agent
All Implemented Interfaces:
IAgent, java.lang.Runnable, java.io.Serializable
Direct Known Subclasses:
ContributorAgent

public abstract class Agent
extends java.lang.Object
implements IAgent

Base class for agents. The class is abstract because the run() method has no default implementation here.

It gives the most basic implementation of an agent possible. The implementation contains the following functionality that can be used by extending classes:

See Also:
Serialized Form

Field Summary
protected  IBase base
          The Base that hosts the agent.
protected  java.lang.String job
          This is the job name the agent participates in.
protected  java.lang.String name
          This is the name of the agent.
protected  boolean shouldLive
          If this flag is set the agent should stop executing.
protected  java.lang.String type
          This is the type identifyer of the agent.
protected static int VERSION
          The drm version the agent is designed for.
 
Constructor Summary
Agent(java.lang.String type, java.lang.String job, java.lang.String name)
          Cosntructs an Agent with the given name, jobname and type.
 
Method Summary
 IRequest fireMessage(Address recipient, java.lang.String type)
          Creates a message and fires it to a local destination.
 IRequest fireMessage(Address recipient, java.lang.String type, java.lang.Object object)
          Creates a message and fires it.
 IRequest fireMessage(java.lang.String recipient, java.lang.String type, java.lang.Object object)
          Creates a message and fires it to a local destination.
 IDRM getDRM()
          This returns a reference through which information about the hosting DRM can be requested.
 java.lang.String getJob()
          Returns job name.
 java.lang.String getName()
          Returns the name of the agent.
 java.lang.String getState()
          This is the function that returns the reply to a message of type "getState".
 java.lang.String getType()
          Returns type identifier.
 boolean handleMessage(Message m, java.lang.Object object)
          Handles incoming messages.
 void onArrival(Address from, Address to)
          Extending classes that override this method must make sure that they call super.onArrival.
 void onDestruction()
          Extending classes that override this method must make sure that they call super.onDestruction.
 void selfTest(java.io.PrintStream output)
           
 void setBase(IBase b)
          This is called by the base when the agent is received.
 void suicide()
          Removes the agent from the base.
 java.lang.String toString()
           
 int version()
          Returns the version of the agent.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.lang.Runnable
run
 

Field Detail

base

protected transient IBase base
The Base that hosts the agent. An agent can only live on a base.

shouldLive

protected transient volatile boolean shouldLive
If this flag is set the agent should stop executing. Every thread run by the agent should watch this flag unless it reimplements onDestruction().
See Also:
onDestruction()

name

protected final java.lang.String name
This is the name of the agent.

type

protected final java.lang.String type
This is the type identifyer of the agent.

job

protected final java.lang.String job
This is the job name the agent participates in.

VERSION

protected static final int VERSION
The drm version the agent is designed for.
See Also:
Base.RELEASE_VERSION
Constructor Detail

Agent

public Agent(java.lang.String type,
             java.lang.String job,
             java.lang.String name)
Cosntructs an Agent with the given name, jobname and type. The combination of these three things should be unique. The name that will be assigned to the agent (and later returned by getName()) is prefixed by type and job, in the format type.job.name, as required by the specification.
Parameters:
type - The type of the agent.
job - The job identifier.
name - The agent name. If null, a random name is generated.
Method Detail

onArrival

public void onArrival(Address from,
                      Address to)
Extending classes that override this method must make sure that they call super.onArrival. The suggested practice is that every implementation must begin with the line
 super.onArrival(from,to);
 
Specified by:
onArrival in interface IAgent
Following copied from interface: drm.agentbase.IAgent
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:
IAgent.setBase(IBase)

onDestruction

public void onDestruction()
Extending classes that override this method must make sure that they call super.onDestruction. The suggested practice is that every implementation must begin with the line
 super.onDestruction();
 
Specified by:
onDestruction in interface IAgent

getName

public final java.lang.String getName()
Description copied from interface: IAgent
Returns the name of the agent.
Specified by:
getName in interface IAgent

getJob

public final java.lang.String getJob()
Description copied from interface: IAgent
Returns job name. Every agent is part of a job. This returns the name of that job.
Specified by:
getJob in interface IAgent

getType

public final java.lang.String getType()
Description copied from interface: IAgent
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.
Specified by:
getType in interface IAgent

setBase

public final void setBase(IBase b)
Description copied from interface: IAgent
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.
Specified by:
setBase in interface IAgent
Following copied from interface: drm.agentbase.IAgent
Parameters:
b - The Base that hosts the agent.

handleMessage

public boolean handleMessage(Message m,
                             java.lang.Object object)
Handles incoming messages. The known message types are the following.

Extending classes that override this method must make sure that they call super.handleMessage. The suggested practice is that every implementation must begin with the line

 if( super.handleMessage(m,object) ) return true;
 
and after that handling of the class specific messages.
Specified by:
handleMessage in interface IAgent
Following copied from interface: drm.agentbase.IAgent
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 final int version()
Description copied from interface: IAgent
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.
Specified by:
version in interface IAgent
Following copied from interface: drm.agentbase.IAgent
See Also:
Base.RELEASE_VERSION

fireMessage

public final IRequest fireMessage(Address recipient,
                                  java.lang.String type,
                                  java.lang.Object object)
Creates a message and fires it.
Parameters:
recipient - Recipient of the message.
type - Type of the message.
contstr - The string content of the message.
object - Object to be wrapped in the message. If null, then no object is wrapped, null is written.
Returns:
The request to track the status of the sending process.
See Also:
IBase.fireMessage(Message)

fireMessage

public final IRequest fireMessage(java.lang.String recipient,
                                  java.lang.String type,
                                  java.lang.Object object)
Creates a message and fires it to a local destination.
Parameters:
recipient - The name of the recipient of the message. It is assumed to be a local agent.
type - Type of the message.
contstr - The string content of the message.
object - Object to be wrapped in the message. If null, then no object is wrapped, null is written.

fireMessage

public final IRequest fireMessage(Address recipient,
                                  java.lang.String type)
Creates a message and fires it to a local destination. The content is empty.
Parameters:
recipient - Recipient of the message.
type - Type of the message.

suicide

public final void suicide()
Removes the agent from the base. Look out! The method that calls this method will not exit, the thread will not be stopped as a result. It only calles base.destroyAgent(name). So this method must be followed by exiting from the method explicitly e.g. with a return.

selfTest

public void selfTest(java.io.PrintStream output)

getDRM

public final IDRM getDRM()
This returns a reference through which information about the hosting DRM can be requested.
Throws:
ClassCastException - If the IDRM interface is not implemented by the base proxy known by the agent.

getState

public java.lang.String getState()
This is the function that returns the reply to a message of type "getState". This information that can be displayed by eg a user interface. It is useful when debugging. If an implementation wants to forbid answering getState requests it has to throw a runtime exception. The requestor will get no answer this way, it will seem as if the request was not understood. This is the default behaviour.

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object