anthill.nest
Interface Nest

All Superinterfaces:

Clearable

All Known Subinterfaces:

GeneticNest, SimulatedNest

All Known Implementing Classes:

LocalGeneticNest, LocalNest, Nest

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: 1.10 $

Author:

Alberto Montresor

Field Summary

static String

NAME Identifier used in the configuration files

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.
ResourceManager	createResourceManager(String name, String species) Returns a reference to the resource manager associated to the specified ant species and identified by the given name.
Neighbour[]	getNeighbours() Returns information about the neighbours known to this nest.
NestId	getNestId() Returns the identifier of this nest
ResourceManager	getResourceManager(String name, String species) Returns a reference to the resource manager associated to the specified ant species and identified by the given name.
void	removeNeighbour(NestId nid) Removes the identifier of a neighbour nest from the set of neighbours known to this Nest.
void	request(RequestId rid, Object request, ResponseListener listener) Accepts a resource request originated by the user of this nest.

Methods inherited from interface anthill.util.Clearable

clear

Field Detail

NAME

public static final String NAME

Identifier used in the configuration files

See Also:

Constant Field Values

Method Detail

getNestId

public NestId getNestId()

Returns the identifier of this nest

getResourceManager

public ResourceManager getResourceManager(String name,
                                          String species)

Returns a reference to the resource manager associated to the specified ant species and identified by the given name. Different ant species may be associated to different resource managers; parameter species is used to discriminate among ant species. If no resource manager is associated to species and is identified by name, the method returns null.

Parameters:

name - the name of the manager to obtain a reference to

species - the name of the ant species to which the manager is associated

Returns:

a reference to the requested resource manager, or null if no such resource manager is found.

createResourceManager

public ResourceManager createResourceManager(String name,
                                             String species)
                                      throws ResourceManagerException

Returns a reference to the resource manager associated to the specified ant species and identified by the given name. Different ant species may be associated to different resource managers; parameter species is used to discriminate among ant species. If no resource manager is associated to species and is identified by name, a new resource manager is created, using name as lookup identifier in the factory object to obtain the current configuration.

Parameters:

name - the name of the manager to obtain a reference to

species - the name of the ant species to which the manager is associated

Returns:

a reference to the requested resource manager, or null if no such resource manager is found.

Throws:

ResourceManager - this exception is thrown if, for some reason, it is impossible to create a resource manager

ResourceManagerException

request

public void request(RequestId rid,
                    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:

rid - the request identifier, created and managed by the invoker of this method.

request - the request to be satisfied

listener - The listener object which will be notified when the request is completed.

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.