Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:

- Signs the state of the agent via the flag `shouldLive` that must be used by extending classes to properly shut down any threads when this flag becomes false.
- It provides a couple of convinience functions that simplify sending messages via simpler interfaces.
- It defines methods for debugging suitable for redefinition in extending classes. These are `selfTest(PrintStream)` and `getState()`. These functions can be invoked through messages as well, see `handleMessage(Message,Object)` for more information.
- Access to the hosting environment is provided through the object `base`, and through the function `getDRM()`.

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.
  - `selfTest` Prints some debugging info on the standard error.
  - `getState` Returns the output of `getState()`.

  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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD