anthill
Interface AntView

All Known Implementing Classes:

AntView, LocalAntView

public interface AntView

Interface AntView contains the set of methods which are accessible to ants when visiting nests. These methods enable ants to cooperate with nests in a controlled way. For example, ants may retrieve resources from or add resources to a nest; obtain routing information related to other nests; move to other nests, and so on.

Version:

$Revision: 1.16 $

Author:

Alberto Montresor

, Hein Meling

Method Summary

void	addAnt(Ant ant) Add a new ant to this nest.
void	addNeighbour(NestId id) Ants invoke this method to add the identifier of a new neighbour nest to the set of neighbours known to the current nest.
AntId	createAntId() Creates a new ant identifier.
ResourceManager	createResourceManager(String name) Returns a reference to the resource manager identified by the given name, if present.
Ant	getAnt() Returns the ant which is associated to this AntView.
NestId	getLastVisited() Returns the identifier of the last nest visisted by this ant.
Neighbour[]	getNeighbours() Ants invoke this method to obtain the list of nest neighbors known to the current nest.
NestId	getNestId() Returns the identifier of the current nest hosting the ant using this AntView.
ResourceManager	getResourceManager(String name) Returns a reference to the resource manager identified by the given name.
int	getTTL()
void	move(NestId id) Method invoked by an ant in order to be sent to another Nest.
void	removeNeighbour(NestId id) Ants invoke this method to remove a neighbor nest from the list of neighbors known to this nest.
boolean	returnResources(RequestId rid, Resource[] resources) This method is invoked by ants to notify the nest that the ant associated to this AntView, created to satisfy a request, has found the specified set of resources.

Method Detail

getNestId

public NestId getNestId()

Returns the identifier of the current nest hosting the ant using this AntView.

getLastVisited

public NestId getLastVisited()

Returns the identifier of the last nest visisted by this ant.

getTTL

public int getTTL()

getAnt

public Ant getAnt()

Returns the ant which is associated to this AntView. Normally not used by ants, as they may access the same information using this.

createAntId

public AntId createAntId()

Creates a new ant identifier.

addAnt

public void addAnt(Ant ant)

Add a new ant to this nest. For example, this method could be used to create a backward ant for returning information to the requestor nest.

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:

ant - the ant to be added to the current nest

move

public void move(NestId id)
          throws IOException

Method invoked by an ant in order to be sent to another Nest. It is possible that particular AntView implementation limit the operations which can be performed after a move operation. For example, movement to more than one nest (i.e., duplication) may not be enabled.

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:

id - the identifier of the destination nest

Throws:

IOException - raised if the move operation fails, for example due to the unreachability of the nest

addNeighbour

public void addNeighbour(NestId id)
                  throws IOException

Ants invoke this method to add the identifier of a new neighbour nest to the set of neighbours known to the current nest. Depending on the implementation, this operation may require the establishment of a connection to the new nest. In this case, an IOException may be raised in the case a connection cannot be established.

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.

Throws:

IOException - if a connection with the nest cannot be established.

removeNeighbour

public void removeNeighbour(NestId id)

Ants invoke this method to remove a neighbor nest from the list of neighbors known to this nest. Depending on the implementation, this operation may require the closure of a previously created nest connection.

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.

getNeighbours

public Neighbour[] getNeighbours()

Ants invoke this method to obtain the list of nest neighbors known to the current nest.

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.

getResourceManager

public ResourceManager getResourceManager(String name)

Returns a reference to the resource manager identified by the given name. Returns null if no resource manager is associated with the given name to this ant.

createResourceManager

public ResourceManager createResourceManager(String name)
                                      throws ResourceManagerException

Returns a reference to the resource manager identified by the given name, if present. Otherwise, creates a new resource manager, using name as lookup identifier in the factory object to obtain the current configuration.

Throws:

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

ResourceManagerException

returnResources

public boolean returnResources(RequestId rid,
                               Resource[] resources)

This method is invoked by ants to notify the nest that the ant associated to this AntView, created to satisfy a request, has found the specified set of resources.

Parameters:

resources - the resources satisfying the request