anthill.nest
Interface Trail

All Superinterfaces:
Clearable
All Known Implementing Classes:
LocalTrail

public interface Trail
extends Clearable

This interface represents a container for associations (ant identifier, previous nest identifier) stored in nests. These associations may be used by ants to return to the requestor nest which has originated them, without having to carry this information with them.

The interface contains two methods, one to add an association (ant identifier, previous nest), the other to obtain, given the ant identifier, the identifier of the previous nest.

Trail is one of the components of a nest; the other are Manager), RequestSet, Storage and Gate.

Trail methods are invoked by AntView objects to implement methods storePreviousNest() and getPreviousNest(). The exact behavior of these methods depends on the implementation of Trail.

Version:
$Revision$
Author:
Alberto Montresor

Method Summary
 boolean add(AntId id, NestId source)
          Add a pair (ant identifier, previous nest identifier) to Trail object.
 NestId lookup(AntId id, boolean remove)
          Lookup the Trail object in order to obtain the identifier of the nest from which the specified ant arrived.
 
Methods inherited from interface anthill.util.Clearable
clear
 

Method Detail

add

public boolean add(AntId id,
                   NestId source)
Add a pair (ant identifier, previous nest identifier) to Trail object. Returns true if the ant identifier is not already included in this Trail object; return false otherwise. The "false" notification can be used to detect duplicated visits to a nest.

lookup

public NestId lookup(AntId id,
                     boolean remove)
Lookup the Trail object in order to obtain the identifier of the nest from which the specified ant arrived.
Parameters:
id - the identifier of the ant
remove - true if the association (ant id, nest id) should be removed after retrieval