anthill.nestor
Class LocalNest

java.lang.Object
  |
  +--anthill.nestor.LocalNest
All Implemented Interfaces:
AntListener, Clearable, Nest, java.rmi.Remote
Direct Known Subclasses:
LocalGeneticNest

public class LocalNest
extends java.lang.Object
implements Nest, AntListener

A Nest class collects the components of a Nest site: (i) a AntView object, which is the view of a Nest for an Ant; (ii) a Gate object, which manage the communication between nests; (iii) an Manager, i.e. the object which manage the activities performed by different agents.

Implementation note: this implementation is supposed to be used as simple implementation of Nest in the off-line environment. Here, we assume that the Manager object used is single-threaded; in this way, we avoid the costs of synchronized methods.

Version:
$Revision$
Author:
Alberto Montresor

Field Summary
static java.lang.String NEST_TTL
          String name of the parameter used to determine the ttl used by these nests.
 
Constructor Summary
LocalNest(Factory factory)
          Constructs a new nest.
 
Method Summary
 void addAntNeighbour(NestId aid)
          Add the identifier of a new neighbour nest to the set of neighbours known to this Nest, on behalf of an ant.
 void addClientNeighbour(NestId aid)
          Add the identifier of a new neighbour nest to the set of neighbours known to this Nest, on behalf of an Nest client.
 void addResource(Resource resource)
          Add a resource to the nest.
 void clear()
          Restores the object to its initial state.
 void deliver(AntDescriptor desc)
          Receive an agent from outside and deliver it to the to the activity manager.
 NestId getId()
          Return the identifier of this Nest
 Manager getManager()
          Return the Manager associated to this Nest
 Neighbour[] getNeighbours()
          Return the neighbours known to this Nest
 java.lang.Object getPheromone(java.lang.Class cl)
          Return the pheromone associated to the link to this neighbour.
 Resource getResource(java.lang.Object key)
          Performs the specified request on the local resource storage and returns the resources satisfying the request.
 Resource[] getResources(java.lang.Object request)
          Performs the specified request on the local resource storage and returns the resources satisfying the request.
 Storage getStorage(java.lang.String name)
          Return a storage object identified by the given name.
 void insert(Resource resource)
          Insert a new resource in this nest.
 int intValue(java.lang.String name)
          Read from statistics
 void removeNeighbour(NestId aid)
          Remove a neighbour identifier from the set of neighbour
 void request(RequestId rid, java.lang.Object request, ResponseListener listener)
          Accepts a request from the nest user.
 void setPheromone(java.lang.Object pheromone, java.lang.Class cl)
          Return the pheromone associated to the link to this neighbour.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

NEST_TTL

public static final java.lang.String NEST_TTL
String name of the parameter used to determine the ttl used by these nests.
Constructor Detail

LocalNest

public LocalNest(Factory factory)
Constructs a new nest.
Method Detail

clear

public void clear()
Restores the object to its initial state.
Specified by:
clear in interface Clearable

deliver

public void deliver(AntDescriptor desc)
Receive an agent from outside and deliver it to the to the activity manager.
Specified by:
deliver in interface AntListener
Following copied from interface: anthill.nest.AntListener
Parameters:
sender - the identifier of the nest from which this ant has been received
desc - the ant descriptor of the received ant
Throws:
java.rmi.RemoteException - added to the throw clause to respect the conventions for remote interfaces.

getId

public NestId getId()
Return the identifier of this Nest
Specified by:
getId in interface Nest

getManager

public Manager getManager()
Return the Manager associated to this Nest
Specified by:
getManager in interface Nest

request

public void request(RequestId rid,
                    java.lang.Object request,
                    ResponseListener listener)
Accepts a request from the nest user. Possible responses will be returned to the specified listener. One or more ants are generated and assigned to the request. Accept a resource request originated by an anthill client. The resource to be searched is identified by name. The method returns immediately. When the resource is found, a Resource object will be returned to the specified resource listener.

Implementation note: If the resource can be found locally, the listener is immediately contacted. Otherwise, a new Ant is generated and is delivered to the ant manager.

Specified by:
request in interface Nest
Parameters:
request - the request to be performed
listener - The listener object which will be notified when the request is completed.

insert

public void insert(Resource resource)
Insert a new resource in this nest. Delagates the insertion to the storage.
Specified by:
insert in interface Nest
Parameters:
resource - the resource to be inserted.

addClientNeighbour

public void addClientNeighbour(NestId aid)
Add the identifier of a new neighbour nest to the set of neighbours known to this Nest, on behalf of an Nest client.
Specified by:
addClientNeighbour in interface Nest
Parameters:
aid - neighbour identifier

addAntNeighbour

public void addAntNeighbour(NestId aid)
Add the identifier of a new neighbour nest to the set of neighbours known to this Nest, on behalf of an ant.
Specified by:
addAntNeighbour in interface Nest
Parameters:
aid - neighbour identifier

removeNeighbour

public void removeNeighbour(NestId aid)
Remove a neighbour identifier from the set of neighbour
Specified by:
removeNeighbour in interface Nest
Parameters:
aid - neighbour identifier

getNeighbours

public Neighbour[] getNeighbours()
Return the neighbours known to this Nest
Specified by:
getNeighbours in interface Nest

getPheromone

public java.lang.Object getPheromone(java.lang.Class cl)
Return the pheromone associated to the link to this neighbour. The class of the pheromone is left unspecified.

setPheromone

public void setPheromone(java.lang.Object pheromone,
                         java.lang.Class cl)
Return the pheromone associated to the link to this neighbour. The class of the pheromone is left unspecified.

getStorage

public Storage getStorage(java.lang.String name)
                   throws StorageNotFoundException
Return a storage object identified by the given name.
Specified by:
getStorage in interface Nest
Following copied from interface: anthill.nest.Nest
Parameters:
name - name of the storage to obtain a reference to.
Returns:
a Storage reference
Throws:
StorageNotFoundException - if the specified name does not correspond to a storage currently available from this nest.

getResources

public Resource[] getResources(java.lang.Object request)
Performs the specified request on the local resource storage and returns the resources satisfying the request.

The exact behavior of this method depends on the implementation of the current nest hosting the ant. Please refer to the documentation of the nest implementation for more details.

Parameters:
request - The request to be performed

getResource

public Resource getResource(java.lang.Object key)
Performs the specified request on the local resource storage and returns the resources satisfying the request.

The exact behavior of this method depends on the implementation of the current nest hosting the ant. Please refer to the documentation of the nest implementation for more details.

Parameters:
request - The request to be performed

addResource

public void addResource(Resource resource)
                 throws CapacityException
Add a resource to the nest. This method enables ants to move resources from one nest to another.

Depending on the implementation of Resource and Nest, adding a resource to a nest through an AntView may result to actual copy the content of the resource, or to simply insert a reference to the actual position of the resource itself.

This method may be invoked more than once from an ant, in order to insert more resources. Nevertheless, the actual insertion of a resource in a nest depends on the policies of the particular Nest implementation. For example, a nest may limit the number of resources originated by another nest, in order to avoid "spamming".

The exact behavior of this method depends on the implementation of the current nest hosting the ant. Please refer to the documentation of the nest implementation for more details.

Parameters:
resource - resource to be added

toString

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

intValue

public int intValue(java.lang.String name)
Read from statistics