anthill.nest
Interface Nest

All Superinterfaces:
Clearable
All Known Subinterfaces:
GeneticNest
All Known Implementing Classes:
LocalNest

public interface Nest
extends Clearable

Nest is the interface used by nest users to communicate with nests. The basic methods contained in this interface enable the user to search resources, to insert resources in the Anthill network and to add knowledge about other nests.

Version:
$Revision$
Author:
Alberto Montresor

Method Summary
 void addAntNeighbour(NestId nid)
          Adds the identifier of a new neighbour nest to the set of neighbours known to this nest, on behalf of an ant visiting the nest.
 void addClientNeighbour(NestId nid)
          Adds the identifier of a new neighbour nest to the set of neighbours known to this nest, on behalf of the nest user.
 NestId getId()
          Returns the identifier of this nest
 Manager getManager()
          Returns the Manager object associated to this nest
 Neighbour[] getNeighbours()
          Returns information about the neighbours known to this nest.
 Storage getStorage(java.lang.String name)
          Obtains a storage reference from the nest.
 void insert(Resource resource)
          Inserts a new resource in this nest.
 void removeNeighbour(NestId nid)
          Removes the identifier of a neighbour nest from the set of neighbours known to this Nest.
 void request(RequestId rid, java.lang.Object request, ResponseListener listener)
          Accepts a resource request originated by the user of this nest.
 
Methods inherited from interface anthill.util.Clearable
clear
 

Method Detail

getId

public NestId getId()
Returns the identifier of this nest

getManager

public Manager getManager()
Returns the Manager object associated to this nest

getStorage

public Storage getStorage(java.lang.String name)
                   throws StorageNotFoundException
Obtains a storage reference from the 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.

request

public void request(RequestId rid,
                    java.lang.Object request,
                    ResponseListener listener)
Accepts a resource request originated by the user of this nest. The interpretation of the request object is left to the ant(s) created to satisfy the response. This method returns immediately. When the request is completed, one or more Resource object will be returned to the specified resource listener.
Parameters:
request - the request to be satisfied
listener - The listener object which will be notified when the request is completed.

insert

public void insert(Resource resource)
Inserts a new resource in this nest.

The exact behavior of this method depends on the implementation of the resource storage contained in the nest. Please refer to the documentation of the resource storage implementation for more details.

Parameters:
resource - the resource to be inserted.

addClientNeighbour

public void addClientNeighbour(NestId nid)
Adds the identifier of a new neighbour nest to the set of neighbours known to this nest, on behalf of the nest user.

The exact behavior of this method depends on the implementation of the gate object contained in the nest. Please refer to the documentation of the resource storage implementation for more details.

Parameters:
nid - the identifier of the neighbour to be added

addAntNeighbour

public void addAntNeighbour(NestId nid)
Adds the identifier of a new neighbour nest to the set of neighbours known to this nest, on behalf of an ant visiting the nest.

The exact behavior of this method depends on the implementation of the gate object contained in the nest. Please refer to the documentation of the resource storage implementation for more details.

Parameters:
nid - the identifier of the neighbour to be added

removeNeighbour

public void removeNeighbour(NestId nid)
Removes the identifier of a neighbour nest from the set of neighbours known to this Nest.

The exact behavior of this method depends on the implementation of the gate object contained in the nest. Please refer to the documentation of the resource storage implementation for more details.

Parameters:
nid - the identifier of the neighbour to be removed

getNeighbours

public Neighbour[] getNeighbours()
Returns information about the neighbours known to this nest.