org.gridlab.gat.advert
Interface AdvertService

All Superinterfaces:
Monitorable

public interface AdvertService
extends Monitorable

The AdvertService allows Advertisable instances to get published to and queried in an advert directory. Such an advert directory is a meta data directory with an hierarchical namespace attached, it exists in memory, but can be exported to, or imported from persistent memory (hard disk).

Author:
rob

Method Summary
 void add(Advertisable advert, MetaData metaData, String path)
          Add an Advertisable instance and related meta data to the AdvertService, at path (absolute or relative to PWD).
 void delete(String path)
          Remove an Advertisable instance and related meta data from the AdvertService, at path (absolute or relative to PWD).
 void exportDataBase(URI target)
          Exports the advert database to persistent memory located at the given URI.
 String[] find(MetaData metaData)
          Query the AdvertService for entries matching the specified set of meta data in the MetaData.
 Advertisable getAdvertisable(GATContext context, String path)
          Gets an Advertisable instance from the given path (absolute or relative to PWD).
 Advertisable getAdvertisable(String path)
          Gets an Advertisable instance from the given path (absolute or relative to PWD).
 MetaData getMetaData(String path)
          Gets the MetaData of an Advertisable instance from the given path (absolute or relative to the PWD).
 String getPWD()
          Returns the current element of the AdvertService name space used as reference for relative paths.
 void importDataBase(URI source)
          Imports the advert database from persistent memory located at the given URI.
 void setPWD(String path)
          Specify the element of the AdvertService name space to be used as reference for relative paths.
 
Methods inherited from interface org.gridlab.gat.monitoring.Monitorable
addMetricListener, getMeasurement, getMetricDefinitionByName, getMetricDefinitions, removeMetricListener
 

Method Detail

add

void add(Advertisable advert,
         MetaData metaData,
         String path)
         throws GATInvocationException
Add an Advertisable instance and related meta data to the AdvertService, at path (absolute or relative to PWD). If an AdvertService entry exists at the specified path, that entry gets overwritten, and a warning is issued.

Parameters:
advert - instance to be entered into the AdvertService.
metaData - Meta data to be associated with the passed Advertisable.
path - Path (either absolute or relative to PWD) of the new entry.
Throws:
GATInvocationException - this exception is thrown when all adaptors fail on this method it contains a tree of exceptions that were the causes.

delete

void delete(String path)
            throws NoSuchElementException,
                   GATInvocationException
Remove an Advertisable instance and related meta data from the AdvertService, at path (absolute or relative to PWD).

Parameters:
path - Path (either absolute or relative to PWD) of the entry to be deleted.
Throws:
NoSuchElementException - The path is incorrect.
GATInvocationException - this exception is thrown when all adaptors fail on this method it contains a tree of exceptions that were the causes.

getAdvertisable

Advertisable getAdvertisable(String path)
                             throws GATInvocationException,
                                    NoSuchElementException
Gets an Advertisable instance from the given path (absolute or relative to PWD). The context used to create the Advertisable object is the context that was used to create this AdvertService.

Parameters:
path - Path (either absolute or relative to PWD) of the entry.
Returns:
The Advertisable instance at the given path
Throws:
NoSuchElementException - The path is incorrect.
GATInvocationException - this exception is thrown when all adaptors fail on this method it contains a tree of exceptions that were the causes.

getAdvertisable

Advertisable getAdvertisable(GATContext context,
                             String path)
                             throws GATInvocationException,
                                    NoSuchElementException
Gets an Advertisable instance from the given path (absolute or relative to PWD).

Parameters:
context - The context to create the Advertisable object with.
path - Path (either absolute or relative to PWD) of the entry.
Returns:
The Advertisable instance at the given path
Throws:
NoSuchElementException - The path is incorrect.
GATInvocationException - this exception is thrown when all adaptors fail on this method it contains a tree of exceptions that were the causes.

getMetaData

MetaData getMetaData(String path)
                     throws NoSuchElementException,
                            GATInvocationException
Gets the MetaData of an Advertisable instance from the given path (absolute or relative to the PWD).

Parameters:
path - Path (either absolute or relative to PWD) of the entry.
Returns:
A MetaData containing the meta data.
Throws:
NoSuchElementException - The path is incorrect.
GATInvocationException - this exception is thrown when all adaptors fail on this method it contains a tree of exceptions that were the causes.

find

String[] find(MetaData metaData)
              throws GATInvocationException
Query the AdvertService for entries matching the specified set of meta data in the MetaData.

Parameters:
metaData - MetaData describing the entries to be searched for.
Returns:
a String[] of absolute paths, each pointing to a matching entry. If no matches are found, null is returned.
Throws:
GATInvocationException - this exception is thrown when all adaptors fail on this method it contains a tree of exceptions that were the causes.

setPWD

void setPWD(String path)
            throws GATInvocationException
Specify the element of the AdvertService name space to be used as reference for relative paths. This method is equivalent to perform a 'cd' in the name space. A relative path will be appended to the current path.

Parameters:
path - New absolute or relative reference path.
Throws:
GATInvocationException - this exception is thrown when all adaptors fail on this method it contains a tree of exceptions that were the causes.

getPWD

String getPWD()
              throws GATInvocationException
Returns the current element of the AdvertService name space used as reference for relative paths.

Returns:
absolute reference path.
Throws:
GATInvocationException - this exception is thrown when all adaptors fail on this method it contains a tree of exceptions that were the causes.

exportDataBase

void exportDataBase(URI target)
                    throws GATInvocationException
Exports the advert database to persistent memory located at the given URI.

Parameters:
target - the location where the advert database should be exported to.
Throws:
GATInvocationException - if something fails during the export

importDataBase

void importDataBase(URI source)
                    throws GATInvocationException
Imports the advert database from persistent memory located at the given URI.

Parameters:
source - the location where the advert database should be imported from.
Throws:
GATInvocationException - if something fails during the import