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

## 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:
  - `group`: every base belongs to a group of bases. Communication is possible only inside a group. This prameter gives the name of the group this base belongs to. If not defined then "default" is set, and also stored in the config properties.
  This coniguration is stored in `cfg`.

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

  - `java.io.tmpdir` gives the directory the base is allowed to use for storing temporary files as eg the jar files of the agents. Note that this is a standard system property. If the directory is not writable, or cannot be created the system exits.

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:
  - `drm.baseName` The name of the base.
  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)`

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