drm.agentbase
Class Base

java.lang.Object
  |
  +--drm.agentbase.Base
All Implemented Interfaces:
IAgent, IBase, java.lang.Runnable, java.io.Serializable
Direct Known Subclasses:
Node

public class Base
extends java.lang.Object
implements IBase, IAgent

A class to host mobile agents. It is able to dispatch and receive them, handles their requests and messages.

See Also:
Serialized Form

Inner Class Summary
protected  class Base.Firewall
          This is an implementation of IBase hiding the public functions which are not part of IBase.
 
Field Summary
static byte AGENT
           
protected  java.util.Map boxes
          Stores all agents and related information.
protected  java.util.Properties cfg
          The configuration properties.
static byte GET_JAR
           
 java.lang.String group
          To store the group name.
static int GROUP_MISMATCH
           
static byte ISALIVE
           
static byte MESSAGE
           
 java.lang.String name
          A unique name for the base.
static byte NOT_OK
           
static byte OK
           
static int PROTOCOL_VERSION
          The protocol version used by this implementation.
static int RELEASE_VERSION
          The version of this release.
static int SENDING_DIR
           
 
Constructor Summary
Base(java.util.Properties c)
          Constructs a Base.
 
Method Summary
 void addListener(IBaseListener l)
           
 void close()
          Destroys all the agents, stops all the threads, and goes offline.
 void destroyAgent(java.lang.String n)
          Destroys an agent with all necessary clean up.
 IRequest dispatchAgent(java.lang.String n, Address to)
          Dispatches an agent with all necessary clean up.
 IRequest fireMessage(Message m)
          Fires the given message.
static java.lang.String getBaseName(java.net.InetAddress h, int p, java.lang.String grp, int tout)
          Returns the name of the remote base if there is one at the given address and it answers requests.
protected  Base.Firewall getFirewall()
          This method should return the firewall that is given to the agents.
 java.lang.String getJob()
          returns group name
 java.lang.String getName()
          returns base name
 java.util.Set getNames()
          Gets the names of all agents on this base.
 java.lang.String getProperty(java.lang.String prop)
          Retuns a base property.
 java.lang.String getType()
          returns "Base"
protected  java.lang.String getUniqueName()
          Called only once to inicialize the name of the base.
 void goOffline()
          After going offline no network traffic is allowed and the base has no valid address.
 int goOnline(int portFrom, int portTo)
          The base tries to go online on one of the ports from the given range (inclusive the limits).
 boolean handleMessage(Message m, java.lang.Object object)
          This implementation does not handle any types of messages.
 boolean isOnline()
          Returns the online status of the base.
 IRequest launch(java.lang.String method, IAgent a, java.lang.Object par)
          Launches an agent to a specified destination.
 void onArrival(Address from, Address to)
          This implementation is empty, simply returns
 void onDestruction()
          This should never be called, if called, it is a bug.
 void removeListener(IBaseListener l)
           
 void run()
          Main housekeeping tasks.
 void setBase(IBase b)
          If the parameter is not a firewall to this, exists the jvm with a panic message.
 int version()
          returns Base.RELEASE_VERSION
 void wipeClean(long time)
          Cleans the base.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

cfg

protected final java.util.Properties cfg
The configuration properties. These mustn't be changed after initialization, extending classes must take care of that.

boxes

protected java.util.Map boxes
Stores all agents and related information. Key is the agent name, value is an AgentBox. Extending classes mustn't change this map, and they have to synchronise every access and iteration over it. Otherwise realiable behaviour is not guaranteed.

MESSAGE

public static final byte MESSAGE

AGENT

public static final byte AGENT

ISALIVE

public static final byte ISALIVE

GET_JAR

public static final byte GET_JAR

SENDING_DIR

public static final int SENDING_DIR

OK

public static final byte OK

NOT_OK

public static final byte NOT_OK

GROUP_MISMATCH

public static final int GROUP_MISMATCH

PROTOCOL_VERSION

public static final int PROTOCOL_VERSION
The protocol version used by this implementation. This is the version of the low level of the protocol used for communication between bases. see protocol specification.

RELEASE_VERSION

public static final int RELEASE_VERSION
The version of this release. The version consist of 3 numbers, in the format of aa.bb.ccc. This number is converted to an integer simply by writing aabbccc. Thus eg version 2.0.0 is 200000. Note that the API version is aa.bb and the implementation versions are denoted by the ccc postfix.

name

public final java.lang.String name
A unique name for the base. Initialized after cfg has been initialized using getUniqueName(). This later function can be overridden in extending classes and the function can use values from cfg. The generated name is stored in cfg as drm.baseName and can be asked via getProperty.
See Also:
cfg, getUniqueName(), IBase.getProperty(String)

group

public final java.lang.String group
To store the group name. The constructor sets it.
Constructor Detail

Base

public Base(java.util.Properties c)
Constructs a Base. The properties used at the moment are the following: This coniguration is stored in cfg.

System properties are also used for configuration. At the moment the following properties are used:

Method Detail

getUniqueName

protected java.lang.String getUniqueName()
Called only once to inicialize the name of the base. At calling time the properties cfg is already set.

getFirewall

protected Base.Firewall getFirewall()
This method should return the firewall that is given to the agents. It is useful to put it here because extending classes can extend the firewall with new functionality that agents can check for.

getBaseName

public static java.lang.String getBaseName(java.net.InetAddress h,
                                           int p,
                                           java.lang.String grp,
                                           int tout)
Returns the name of the remote base if there is one at the given address and it answers requests. Otherwise it returns null.
Parameters:
h - The IP address of the base.
p - The port of the base.
grp - The group of the calling entity.
tout - The timeout to wait for a reply in ms. If zero then we wait until there's a reply, if the connection can be built.

goOnline

public int goOnline(int portFrom,
                    int portTo)
The base tries to go online on one of the ports from the given range (inclusive the limits). Being online means that the base starts to listen to incoming connections, and initiates a houskeeping thread as a default agent. If the base was already online then the given port number is ignored and the method simply returns with the old port number.
Parameters:
portFrom - The number of the port to start with.
portTo - The last port to try.
Returns:
If negative then the base is offline, otherwise the port on which the base listens. It might be that this port is outside the given range if the base was already online listening to the port when calling this method.

goOffline

public void goOffline()
After going offline no network traffic is allowed and the base has no valid address. Apart from that the agents continue to do their thing only they are separated from the world until the base goes online again.

close

public void close()
Destroys all the agents, stops all the threads, and goes offline. The behaviour of the base after calling close is undefined. It must be called before releasing the base object for a clean shutdown.

addListener

public void addListener(IBaseListener l)

removeListener

public void removeListener(IBaseListener l)

wipeClean

public void wipeClean(long time)
Cleans the base. It shuts down every agent, and makes the base go offline for the given milliseconds. The function returns immediately, it does not block.

The base will go online again if it was online when calling this method. Although it is not very likely, but it can happen that the port the base listens to will change.


handleMessage

public boolean handleMessage(Message m,
                             java.lang.Object object)
This implementation does not handle any types of messages. Returns always false.
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)

onArrival

public void onArrival(Address from,
                      Address to)
This implementation is empty, simply returns
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 final void onDestruction()
This should never be called, if called, it is a bug. Exits the jvm with a panic message
Specified by:
onDestruction in interface IAgent

getName

public final java.lang.String getName()
returns base name
Specified by:
getName in interface IAgent
See Also:
name

getJob

public java.lang.String getJob()
returns group name
Specified by:
getJob in interface IAgent

getType

public java.lang.String getType()
returns "Base"
Specified by:
getType in interface IAgent

setBase

public final void setBase(IBase b)
If the parameter is not a firewall to this, exists the jvm with a panic message.
Specified by:
setBase in interface IAgent
Following copied from interface: drm.agentbase.IAgent
Parameters:
b - The Base that hosts the agent.

version

public final int version()
returns Base.RELEASE_VERSION
Specified by:
version in interface IAgent
See Also:
RELEASE_VERSION

run

public final void run()
Main housekeeping tasks. If the base is not online, does nothing, until the base goes online. Exits only after close() is called.
Specified by:
run in interface java.lang.Runnable

getProperty

public java.lang.String getProperty(java.lang.String prop)
Description copied from interface: IBase
Retuns a base property. Properties are mostly set and documented at construction time of implementor classes (see also the constructors of the extending classes). The following properties must be defined in every case:
Specified by:
getProperty in interface IBase
Following copied from interface: drm.agentbase.IBase
Parameters:
prop - Name of the property.
Returns:
As in java.util.Properties.
See Also:
Base(java.util.Properties)

launch

public IRequest launch(java.lang.String method,
                       IAgent a,
                       java.lang.Object par)
Description copied from interface: IBase
Launches an agent to a specified destination. It is assumed that the agent to be launched is not in the base. The operation is assynchronous.
Specified by:
launch in interface IBase
Parameters:
method - has to be "DIRECT"
a - has to be non null
par - has to be an Address or null

getNames

public java.util.Set getNames()
Description copied from interface: IBase
Gets the names of all agents on this base. Returns a newly allocated Set of Strings. This is the only solution that is guaranteed to be thread safe.
Specified by:
getNames in interface IBase

isOnline

public boolean isOnline()
Description copied from interface: IBase
Returns the online status of the base. If the base is not online, communication with the outside world is not possible.
Specified by:
isOnline in interface IBase

destroyAgent

public final void destroyAgent(java.lang.String n)
Description copied from interface: IBase
Destroys an agent with all necessary clean up. The method IAgent.onDestruction() will be called before removing the agent from the base. The agent has to stop all its threads (java offers no possibility at the moment (version 1.4) to stop threads). The agent will be cut off of the outside world, even if it fails to stop its threads.
Specified by:
destroyAgent in interface IBase
Following copied from interface: drm.agentbase.IBase
Parameters:
name - Name of the agent.

dispatchAgent

public final IRequest dispatchAgent(java.lang.String n,
                                    Address to)
Description copied from interface: IBase
Dispatches an agent with all necessary clean up. The succesful operation means sending the agent to the address, then destroying the local copy. Permission to send an agent implies destroying it so it is not possible that sending is succesful but destruction is not. If succesful then the local agent is destroyed after sending by calling destroyAgent. The operation is assynchronous.
Specified by:
dispatchAgent in interface IBase
Following copied from interface: drm.agentbase.IBase
Parameters:
name - Name of the agent.
destination - Where to send the agent.
Returns:
Returns a request so that the user can check the status of the operation.
See Also:
IBase.destroyAgent(String)

fireMessage

public IRequest fireMessage(Message m)
Description copied from interface: IBase
Fires the given message. The recipient can be local or global. From the sender address only the name is used the rest is filled in by the base and the recipient base. The message is sent by a separate thread in case of a remote destination.
Specified by:
fireMessage in interface IBase
Following copied from interface: drm.agentbase.IBase
Returns:
Returns a request so that the user can check the status of the operation. The method call IRequest.getInfo("reply") returns the reply object to the message (after it arrives of course).
See Also:
IRequest.getInfo(String)