jxtaimpl
Class Nest

java.lang.Object
  |
  +--jxtaimpl.Nest

All Implemented Interfaces:

AntListener, Clearable, Nest, Remote

public class Nest

extends Object

implements AntListener, Nest

This class implements the Nest interface and the AntListener interface as well. A GateServiceServer will notify its Nest instance upon receiving a new message containing an Ant via the method deliver(AntDescriptor).

Author:

Francesco Russo (frusso@cs.unibo.it)

Field Summary

Fields inherited from interface anthill.nest.Nest

NAME

Constructor Summary

Nest(Factory fact)
Default constructor which instantiates a RequestSet and a Trail

Method Summary

void	addAntNeighbour(NestId id) Add a new nest (peer) to the set of neighbours on behalf of an Ant client.
void	addClientNeighbour(NestId id) Add a new nest (peer) to the set of neighbours on behalf of a Nest client.
void	addResource(Resource resource, String species) Add a resource to the Nest.
void	clear() Restores the Nest instance to its initial state
ResourceManager	createResourceManager(String name, String species) Returns a reference to the Storage instance associated with the invoking ant's species.
void	deliver(AntDescriptor aDesc) Passes an AntDescriptor to the Manager instance
void	downloadResource(AnthillResource res) Method for downloading a resource from its originating nest.
void	finalize() Method for cleaning up before being garbage collected
Resource[]	getAllResources() This method will return all the resources locally stored in every storage.
InputStream	getInputStreamForResource(byte[] resID, byte[] spec) Returns the InputStream for reading the resource locally stored and identified by the given resource ID resID.
Manager	getManager() Return a reference to the Manager instance
Neighbour[]	getNeighbours() Return an array of known neighbours
NestId	getNestId() Returns the local Nest id
RequestSet	getRequestSet() Return the RequestSet instance
Resource	getResource(Object request, String species) Return a Resource instance associated with the given key.
ResourceManager	getResourceManager(String name, String species) Returns a reference to the Storage instance associated with the invoking ant's species.
Resource[]	getResources(Object request, String species) Return the set of resources which satisfy the request, shaped as a Resource[].
void	insert(Resource res, String species) Add a new resource to this Nest.
void	insRequest(RequestId rid, String keywords) Method to be used by higher level applications for spreading the knowledge about the local insertion of a new request.
void	leave() Method present in the Interface declaration, but not need and so not implemented in the jxtaimpl implementation.
protected void	move(NestId id, Ant ant, int ttl) Method invoked in order to send an Ant to another Nest.
void	removeNeighbour(NestId id) Remove the entry associated with the provided NestId from the set of known neighbours
void	request(RequestId rid, Object req, ResponseListener lstn) With this method a new request is passed to the Nest.
protected void	setAntFactory(AntFactory aFactory) Set the AntFactory instance to use
protected void	setAnthillGroup(AnthillGroup grp) Set the AnthillGroup instance.
protected void	setDownloadServicePipeAdv(PipeAdvertisement pipeAdv) Stores all the information useful for locating this nest's input pipe waiting for resource downloading requests.
protected void	setGateServiceID(ModuleClassID id) Method invoked by the AnthillPeerWS for setting the appropriate GateServiceID value which is needed in order to lookup the service itself.
protected void	setId(NestId nestId) Set the nest id
protected void	setManager(Manager manager) Set the Manager instance to use
protected void	setNeighbourManager(NeighbourManager mng) Set the NeighbourManager
protected void	setPeerFinder(PeerFinder finder) Set the PeerFinder instance
protected void	setTTL(int ttl) Method invoked by the AnthillPeerWS for setting the appropriate TTL value which is read directly from the xml configuration file
void	shareResource(byte[] file, String name, String type, String description, String species) This method has to be used by higher level application in order to share a resource in the Anthill network.
void	shareResource(File file, String name, String type, String description, String species) This method has to be used by higher level application in order to share a resource in the Anthill network.
void	unShare(Resource res) This method has to be invoked in order to unshare a resource locally stored.
void	updatePheromone(String antSpecies, Object ph) Updates the local pheromone object and stores it to disck in order to be able to recover from crashes.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Nest

public Nest(Factory fact)

Default constructor which instantiates a RequestSet and a Trail

Parameters:

fact - The Factory instace useful for reading in configuration parameters

Method Detail

leave

public void leave()

Method present in the Interface declaration, but not need and so not implemented in the jxtaimpl implementation.

clear

public void clear()

Restores the Nest instance to its initial state

Specified by:

clear in interface Clearable

setDownloadServicePipeAdv

protected void setDownloadServicePipeAdv(PipeAdvertisement pipeAdv)

Stores all the information useful for locating this nest's input pipe waiting for resource downloading requests.

setTTL

protected void setTTL(int ttl)

Method invoked by the AnthillPeerWS for setting the appropriate TTL value which is read directly from the xml configuration file

setGateServiceID

protected void setGateServiceID(ModuleClassID id)

Method invoked by the AnthillPeerWS for setting the appropriate GateServiceID value which is needed in order to lookup the service itself.

getNestId

public NestId getNestId()

Returns the local Nest id

Specified by:

getNestId in interface Nest

getResourceManager

public ResourceManager getResourceManager(String name,
                                          String species)
                                   throws StorageNotFoundException

Returns a reference to the Storage instance associated with the invoking ant's species. If the storage didn't exist, null would be returned. Name is used for specifieing the storage type (i.e. Storage.DOC_STORAGE, Storage.PHR_STORAGE, Storage.URL_STORAGE). At the moment Storage.DOC_STORAGE, Trail.NAME, Storage.PHR_STORAGE are supported.

Specified by:

getResourceManager in interface Nest

Parameters:

name - The type of Storage

species - The ant species

Returns:

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

StorageNotFoundException

createResourceManager

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

Returns a reference to the Storage instance associated with the invoking ant's species. If the storage didn't exist, it would be created. Name is used for specifieing the storage type (i.e. Storage.DOC_STORAGE, Storage.PHR_STORAGE, Storage.URL_STORAGE). At the moment just the DOC_STORAGE is supported.

Specified by:

createResourceManager in interface Nest

Parameters:

name - The type of Storage

species - The ant species

Returns:

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

ResourceManagerException

request

public void request(RequestId rid,
                    Object req,
                    ResponseListener lstn)

With this method a new request is passed to the Nest. The Object req argument has to be a jxtaimpl.CmsStorage.Query instance. If the request could be satisfied locally no Ants would be generated, otherwise a set of ants will be sent across the network in order to satisfy the request. The response will be passed to the specified listener.

Specified by:

request in interface Nest

Parameters:

rid - The ID identifieing the request

req - The request object. It has to be a jxtaimpl.storage.Query instance

lstn - The listener to be notified when receiving replies

insRequest

public void insRequest(RequestId rid,
                       String keywords)
                throws IOException

Method to be used by higher level applications for spreading the knowledge about the local insertion of a new request.

Parameters:

rid - a valid request identifier

keywords - a String of possible keywords for the resource

IOException

insert

public void insert(Resource res,
                   String species)
            throws CapacityException

Add a new resource to this Nest. The resource has to be inserted into the local storage. The system will look for a Storage instance associated with the invoking ant's species. If the storage didn't exist, it would be created.

Parameters:

res - The jxtaimpl.storage.AnthillResource instance describing the resource to store

species - The ant species of the ant invoking this method

CapacityException

shareResource

public void shareResource(File file,
                          String name,
                          String type,
                          String description,
                          String species)
                   throws SpeciesNotFoundException,
                          ResourceAlreadyStoredException,
                          CapacityException

This method has to be used by higher level application in order to share a resource in the Anthill network.

Parameters:

file - The file containing the resource to share

name - The resource logical name

type - The resource type

description - A logical description of the reaource

species - The species of the invoking ant

SpeciesNotFoundException

ResourceAlreadyStoredException

CapacityException

shareResource

public void shareResource(byte[] file,
                          String name,
                          String type,
                          String description,
                          String species)
                   throws SpeciesNotFoundException,
                          ResourceAlreadyStoredException,
                          CapacityException

This method has to be used by higher level application in order to share a resource in the Anthill network.

Parameters:

file - The byte array containing the resource to share

name - The resource logical name

type - The resource type

description - A logical description of the reaource

species - The species of the invoking ant

SpeciesNotFoundException

ResourceAlreadyStoredException

CapacityException

getAllResources

public Resource[] getAllResources()

This method will return all the resources locally stored in every storage. If nothing is found, null will be returned.

addClientNeighbour

public void addClientNeighbour(NestId id)

Add a new nest (peer) to the set of neighbours on behalf of a Nest client.

Specified by:

addClientNeighbour in interface Nest

Parameters:

id - the identifier of the neighbour to be added

addAntNeighbour

public void addAntNeighbour(NestId id)

Add a new nest (peer) to the set of neighbours on behalf of an Ant client.

Specified by:

addAntNeighbour in interface Nest

Parameters:

id - the identifier of the neighbour to be added

removeNeighbour

public void removeNeighbour(NestId id)

Remove the entry associated with the provided NestId from the set of known neighbours

Specified by:

removeNeighbour in interface Nest

Parameters:

id - the identifier of the neighbour to be removed

getNeighbours

public Neighbour[] getNeighbours()

Return an array of known neighbours

Specified by:

getNeighbours in interface Nest

deliver

public void deliver(AntDescriptor aDesc)
             throws RemoteException

Passes an AntDescriptor to the Manager instance

Specified by:

deliver in interface AntListener

Parameters:

aDesc - the ant descriptor of the received ant

Throws:

RemoteException - added to the throw clause to respect the conventions for remote interfaces.

setAnthillGroup

protected void setAnthillGroup(AnthillGroup grp)

Set the AnthillGroup instance. This method is invoked by the AnthillPeerWS while performing its start up.

setId

protected void setId(NestId nestId)

Set the nest id

setPeerFinder

protected void setPeerFinder(PeerFinder finder)

Set the PeerFinder instance

setAntFactory

protected void setAntFactory(AntFactory aFactory)

Set the AntFactory instance to use

setManager

protected void setManager(Manager manager)

Set the Manager instance to use

getManager

public Manager getManager()

Return a reference to the Manager instance

setNeighbourManager

protected void setNeighbourManager(NeighbourManager mng)

Set the NeighbourManager

updatePheromone

public void updatePheromone(String antSpecies,
                            Object ph)

Updates the local pheromone object and stores it to disck in order to be able to recover from crashes. If the pheromone instance did not exist, it would be created using the Object ph parameter.

Parameters:

antSpecies - The species of the invoking ant

ph - The pheromone object

getResources

public Resource[] getResources(Object request,
                               String species)
                        throws StorageNotFoundException

Return the set of resources which satisfy the request, shaped as a Resource[]. The Object request has to be an instance of the class jxtaimpl.CmsStorage.Query. The system will look for a Storage instance associated with the "species" parameter. If such a Storage didn't exist a StorageNotFoundException would be thrown.

Parameters:

request - The jxtaimpl.CmsStorage.Query instance

species - The ant species

StorageNotFoundException

getResource

public Resource getResource(Object request,
                            String species)

Return a Resource instance associated with the given key. The Object key has to be an instance of the class jxtaimpl.CmsStorage.Query. The system will look for a Storage instance associated with the "species" parameter. If such a Storage didn't exist a StorageNotFoundException would be thrown.

Parameters:

request - The jxtaimpl.CmsStorage.Query instance

species - The ant species

getInputStreamForResource

public InputStream getInputStreamForResource(byte[] resID,
                                             byte[] spec)
                                      throws StorageNotFoundException

Returns the InputStream for reading the resource locally stored and identified by the given resource ID resID. The spec parameter refers to the ant species the Storage is associated to.

Parameters:

resID - The byte array identifieing the resource whose InputStream will be returned

spec - The byte array representing the ant species

StorageNotFoundException

getRequestSet

public RequestSet getRequestSet()

Return the RequestSet instance

unShare

public void unShare(Resource res)
             throws StorageNotFoundException

This method has to be invoked in order to unshare a resource locally stored.

Parameters:

res - The jxtaimpl.storage.AnthillResource representing the resource we want to unshare

StorageNotFoundException

addResource

public void addResource(Resource resource,
                        String species)
                 throws CapacityException

Add a resource to the Nest. The storage indexed by the key "species" will be used, and possibly created.

Parameters:

resource - The AnthillResource to add

species - The ant species

CapacityException

move

protected void move(NestId id,
                    Ant ant,
                    int ttl)
             throws IOException

Method invoked in order to send an Ant to another Nest. An IOException is thrown if the destination nest won't be reachable.

Parameters:

id - The jxtaimpl.ids.NestId ID of the destination nest

ant - the ant to be sent

IOException

finalize

public void finalize()

Method for cleaning up before being garbage collected

Overrides:

finalize in class Object

downloadResource

public void downloadResource(AnthillResource res)
                      throws CapacityException,
                             StorageNotFoundException

Method for downloading a resource from its originating nest.

Parameters:

res - The jxtaimpl.storage.AnthillResource describing the resource to be downloaded

CapacityException

StorageNotFoundException