anthill
Interface AntView

All Known Implementing Classes:
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$
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.
 void addResource(Resource resource)
          Add a resource to the nest.
 AntId createAntId()
          Creates a new ant identifier.
 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 nest hosting the ant using this AntView.
 java.lang.Object getPheromone()
          Get the pheromone information object related to this ant.
 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.
 NestId getReturnNest(AntId aid, boolean remove)
          Returns the identifier of the previous nest in the incoming path, as stored through during the forward trip through method storePreviousNest().
 Storage getStorage(java.lang.String name)
          Return a storage object identified by the given name.
 int getTTL()
           
 int intValue(java.lang.String name)
          Read from statistics
 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.
 void setPheromone(java.lang.Object pheromone)
          Set the pheromone information object related to this ant.
 boolean storeReturnNest(AntId aid, NestId nid)
          Store information about the last nest visited by the ant associated with this AntView on the current nest.
 

Method Detail

getNestId

public NestId getNestId()
Returns the identifier of the 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 java.io.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:
java.io.IOException - raised if the move operation fails, for example due to the unreachability of the nest

storeReturnNest

public boolean storeReturnNest(AntId aid,
                               NestId nid)
Store information about the last nest visited by the ant associated with this AntView on the current nest. This information is constituted of a pair (antId, nestId) where antId is the identifier of the ant and nestId is the identifier of the nest from which the ant has arrived. During the return trip, this information will be used to obtain the identifier of the previous nest in the incoming path.

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.

Returns:
true if this is the first visit of this ant to this nest (and thus, the information about the previous nest has been stored successfully), or false if this ant has already visited the nest (and thus, the inforamtion about the previous nest could not be stored).

getReturnNest

public NestId getReturnNest(AntId aid,
                            boolean remove)
Returns the identifier of the previous nest in the incoming path, as stored through during the forward trip through method storePreviousNest(). If the current nest is the requestor nest (i.e., the nest which has created this ant), the method returns null.

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:
remove - true if the association (ant id, nest id) should be removed after retrieval
Throws:
IllegalStateException - raised if no information about the previous nest visited by this ant is present (for example, due to expiration).

addNeighbour

public void addNeighbour(NestId id)
                  throws java.io.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:
java.io.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.


getStorage

public Storage getStorage(java.lang.String name)
                   throws StorageNotFoundException
Return a storage object identified by the given name.

getPheromone

public java.lang.Object getPheromone()
Get the pheromone information object related to this ant.

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.


setPheromone

public void setPheromone(java.lang.Object pheromone)
Set the pheromone information object related to this ant.

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:
CapacityException - if the nest cannot store the the pheromone object.

getResources

public Resource[] getResources(java.lang.Object request)
                        throws StorageNotFoundException
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)
                     throws StorageNotFoundException
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,
                        StorageNotFoundException
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

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

intValue

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