anon.infoservice
Class Database

java.lang.Object
  java.util.Observable
      anon.infoservice.Database

All Implemented Interfaces:

IXMLEncodable, java.lang.Runnable

public final class Database
extends java.util.Observable
implements java.lang.Runnable, IXMLEncodable

This class is the generic implementation of a database. It is used by the database implementations for the different services. It is also a registry for all databases used in the context of this application. Instances of this class are observable. Observers of the instances are notified, if an entry is added, renewed or removed from the database or if the whole database is cleared. The observers will always get a DatabaseMessage object as the argument of the update() method. The DatabaseMessage will identify the reason of the notification, see the DatabaseMessage class for more information.

Field Summary

private java.lang.Class	m_DatabaseEntryClass The DatabaseEntry class for that this Database is registered.
private static java.util.Hashtable	m_databases The registered databases.
private static IDistributor	m_distributor The distributor that forwards new database entries.
private java.util.Hashtable	m_serviceDatabase Stores services we know.
private java.util.Vector	m_timeoutList Chronological order (in relation to timeouts) of all objects in the database.

Fields inherited from interface anon.util.IXMLEncodable

FIELD_XML_ELEMENT_CONTAINER_NAME, FIELD_XML_ELEMENT_NAME, XML_ATTR_ID, XML_ATTR_VERSION

Constructor Summary

private

Database(java.lang.Class a_DatabaseEntryClass) Creates a new instance of a Database.

Method Summary

void	addObserver(java.util.Observer a_observer) Adds an observer to this database.
AbstractDatabaseEntry	getEntryById(java.lang.String entryId) Returns the DatabaseEntry with the given ID.
java.lang.Class	getEntryClass() Returns the DatabaseEntry class for that this Database is registered.
java.util.Hashtable	getEntryHash()
java.util.Vector	getEntryList() Returns a snapshot of all values in the serviceDatabase.
java.util.Enumeration	getEntrySnapshotAsEnumeration() Returns a snapshot of all entries in the Database as an Enumeration.
static Database	getInstance(java.lang.Class a_DatabaseEntryClass) Gets the Database for the specified database entries.
static java.util.Enumeration	getInstances() Get an Enumeration of all registered Databases.
int	getNumberOfEntries() Returns the number of DatabaseEntries in the Database.
AbstractDatabaseEntry	getRandomEntry() Returns a random entry from the database.
int	getTimeoutListSize()
boolean	isEntryIdInTimeoutList(java.lang.String a_entryId)
int	loadFromXml(org.w3c.dom.Element a_dbNode) Adds all database entries that are subnodes of the given element to the database.
static void	registerDistributor(IDistributor a_distributor) Registers a distributor that forwards new database entries.
private static Database	registerInstance(Database a_Database) Registers a Database object.
boolean	remove(AbstractDatabaseEntry a_deleteEntry) Removes an entry from the database.
boolean	remove(java.lang.String a_entryID) Removes an entry from the database.
void	removeAll() Removes all entries from the database.
void	run() This is the garbage collector for the database.
org.w3c.dom.Element	toXmlElement(org.w3c.dom.Document a_doc) If the entries of this database implement IXMLEncodable and has a proper value for the field XML_ELEMENT_CONTAINER_NAME, this database is transormed into an XML element.
org.w3c.dom.Element	toXmlElement(org.w3c.dom.Document a_doc, java.lang.String a_xmlContainerName) Creates an XML node with all database entries, but only for those entries that implement IXMLEncodable.
private static Database	unregisterInstance(java.lang.Class a_DatabaseEntryClass) Unregisters the Database object that contains instances of the specified DatabaseEntry class.
private static void	unregisterInstances() Unregisters all Database instances This method is used for testing purposes and should not be removed.
boolean	update(AbstractDatabaseEntry newEntry) Updates an entry in the database.
boolean	update(AbstractDatabaseEntry newEntry, boolean a_bDistribute) Updates an entry in the database.

Methods inherited from class java.util.Observable

clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

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

Field Detail

m_databases

private static java.util.Hashtable m_databases

The registered databases.

m_distributor

private static IDistributor m_distributor

The distributor that forwards new database entries.

m_DatabaseEntryClass

private java.lang.Class m_DatabaseEntryClass

The DatabaseEntry class for that this Database is registered. The Database can only hold instances of this class.

m_serviceDatabase

private java.util.Hashtable m_serviceDatabase

Stores services we know.

m_timeoutList

private java.util.Vector m_timeoutList

Chronological order (in relation to timeouts) of all objects in the database.

Constructor Detail

Database

private Database(java.lang.Class a_DatabaseEntryClass)
          throws java.lang.IllegalArgumentException

Creates a new instance of a Database.

Parameters:

a_DatabaseEntryClass - the DatabaseEntry class for that this Database is registered

Throws:

java.lang.IllegalArgumentException - if the argument is no valid DatabaseEntry class

Method Detail

registerDistributor

public static void registerDistributor(IDistributor a_distributor)

Registers a distributor that forwards new database entries.

Parameters:

a_distributor - a distributor that forwards new database entries

registerInstance

private static Database registerInstance(Database a_Database)

Registers a Database object. If a Database was previously registered for the same DatabaseEntry class, the method does nothing and returns the previously registered Database. Otherwise, the given Database is returned. This method is used for testing purposes and should not be removed.

Parameters:

a_Database - the registered Database

Returns:

the actually registered Database instance for the specified DatabaseEntry class

unregisterInstance

private static Database unregisterInstance(java.lang.Class a_DatabaseEntryClass)

Unregisters the Database object that contains instances of the specified DatabaseEntry class. This method is used for testing purposes and should not be removed.

Parameters:

a_DatabaseEntryClass - the DatabaseEntry class for that the corresponding Database is unregistered

Returns:

the Database instance for the specified DatabaseEntry class that was unregistered or null if no corresponding Database could be found

unregisterInstances

private static void unregisterInstances()

Unregisters all Database instances This method is used for testing purposes and should not be removed.

getInstance

public static Database getInstance(java.lang.Class a_DatabaseEntryClass)
                            throws java.lang.IllegalArgumentException

Gets the Database for the specified database entries. Creates the Database if it does not exist already.

Parameters:

a_DatabaseEntryClass - the DatabaseEntry class for that the method returns the corresponding Database object

Returns:

the Database object that contains DatabaseEntries of the specified type

Throws:

java.lang.IllegalArgumentException - if the argument is no valid DatabaseEntry class

getInstances

public static java.util.Enumeration getInstances()

Get an Enumeration of all registered Databases.

Returns:

an Enumeration of all registered Databases

run

public void run()

This is the garbage collector for the database. If an entry becomes outdated, it will be automatically removed from the database.

Specified by:

run in interface java.lang.Runnable

update

public boolean update(AbstractDatabaseEntry newEntry)
               throws java.lang.IllegalArgumentException

Updates an entry in the database. If the entry is an unknown or if it is newer then the one stored in the database for this service, the new entry is stored in the database and forwarded to all neighbour infoservices.

Parameters:

newEntry - The database entry to update.

Returns:

if the database has been changed

Throws:

java.lang.IllegalArgumentException - if the database entry is not of the type the Database can store

update

public boolean update(AbstractDatabaseEntry newEntry,
                      boolean a_bDistribute)
               throws java.lang.IllegalArgumentException

Updates an entry in the database. If the entry is an unknown or if it is newer then the one stored in the database for this service, the new entry is stored in the database and forwarded to all neighbour infoservices.

Parameters:

newEntry - The database entry to update.

a_bDistribute - distribute to other InfoServices if distributor object is set; should be default

Returns:

if the database has been changed

Throws:

java.lang.IllegalArgumentException - if the database entry is not of the type the Database can store

getEntryClass

public java.lang.Class getEntryClass()

Returns the DatabaseEntry class for that this Database is registered.

Returns:

the DatabaseEntry class for that this Database is registered

remove

public boolean remove(java.lang.String a_entryID)

Removes an entry from the database.

Parameters:

a_entryID - The ID of the entry to remove. If it is not in the database, nothing is done.

Returns:

if the database has been changed

remove

public boolean remove(AbstractDatabaseEntry a_deleteEntry)

Removes an entry from the database.

Parameters:

a_deleteEntry - The entry to remove. If it is not in the database, nothing is done.

Returns:

if the database has been changed

removeAll

public void removeAll()

Removes all entries from the database.

loadFromXml

public int loadFromXml(org.w3c.dom.Element a_dbNode)

Adds all database entries that are subnodes of the given element to the database. The class must have a constructor with a single argument, a org.w3c.dom.Element, so that this is successful.

Parameters:

a_dbNode - The xml node that contains db entries.

Returns:

number of updated entries

toXmlElement

public org.w3c.dom.Element toXmlElement(org.w3c.dom.Document a_doc)

If the entries of this database implement IXMLEncodable and has a proper value for the field XML_ELEMENT_CONTAINER_NAME, this database is transormed into an XML element.

Specified by:

toXmlElement in interface IXMLEncodable

Parameters:

a_doc - a Document

Returns:

the database als XML Element or null if transformation was not possible

toXmlElement

public org.w3c.dom.Element toXmlElement(org.w3c.dom.Document a_doc,
                                        java.lang.String a_xmlContainerName)

Creates an XML node with all database entries, but only for those entries that implement IXMLEncodable.

Parameters:

a_doc - The XML document, which is the environment for the created XML node.

a_xmlContainerName - the name of the XML element that should contain the entries

Returns:

the newly created XML node.

getEntryHash

public java.util.Hashtable getEntryHash()

getEntryList

public java.util.Vector getEntryList()

Returns a snapshot of all values in the serviceDatabase.

Returns:

A Vector with all values which are stored in the serviceDatabase.

getEntrySnapshotAsEnumeration

public java.util.Enumeration getEntrySnapshotAsEnumeration()

Returns a snapshot of all entries in the Database as an Enumeration.

Returns:

a snapshot of all entries in the Database as an Enumeration

getNumberOfEntries

public int getNumberOfEntries()

Returns the number of DatabaseEntries in the Database.

Returns:

the number of DatabaseEntries in the Database

getEntryById

public AbstractDatabaseEntry getEntryById(java.lang.String entryId)

Returns the DatabaseEntry with the given ID. If there is no DatabaseEntry with this ID is in the database, null is returned.

Parameters:

entryId - The ID of the database entry.

Returns:

The entry with the specified ID or null, if there is no such entry.

getRandomEntry

public AbstractDatabaseEntry getRandomEntry()

Returns a random entry from the database. If there are no entries in the database, null is returned.

Returns:

A random entry from the database or null, if the database is empty.

addObserver

public void addObserver(java.util.Observer a_observer)

Adds an observer to this database. The observer will obtain an initial message including a snapshot of the current database (this message is also sent, if the observer was already observing the database).

Overrides:

addObserver in class java.util.Observable

Parameters:

a_observer - The observer to add to this database.

isEntryIdInTimeoutList

public boolean isEntryIdInTimeoutList(java.lang.String a_entryId)

getTimeoutListSize

public int getTimeoutListSize()