de.lmu.ifi.dbs.elki.database
Class AbstractDatabase<O extends DatabaseObject>

java.lang.Object
  de.lmu.ifi.dbs.elki.logging.AbstractLoggable
      de.lmu.ifi.dbs.elki.utilities.optionhandling.AbstractParameterizable
          de.lmu.ifi.dbs.elki.database.AbstractDatabase<O>

Type Parameters:

O - the type of DatabaseObject as element of the database

All Implemented Interfaces:

Database<O>, Result, Parameterizable, Iterable<Integer>

Direct Known Subclasses:

IndexDatabase, SequentialDatabase

public abstract class AbstractDatabase<O extends DatabaseObject>
extends AbstractParameterizable
implements Database<O>

Provides a mapping for associations based on a Hashtable and functions to get the next usable ID for insertion, making IDs reusable after deletion of the entry.

Author:

Arthur Zimek

Field Summary

private AssociationMaps	associations Map to hold association maps.
private Map<Integer,O>	content Map to hold the objects of the database.
private int	counter Counter to provide a new Integer id.
private Associations	globalAssociations Map to hold global associations.
protected List<DatabaseListener>	listenerList Holds the listener of this database.
private List<Integer>	reusableIDs Provides a list of reusable ids.

Fields inherited from class de.lmu.ifi.dbs.elki.utilities.optionhandling.AbstractParameterizable

optionHandler

Fields inherited from class de.lmu.ifi.dbs.elki.logging.AbstractLoggable

debug, logger

Constructor Summary

protected

AbstractDatabase() Provides an abstract database including a mapping for associations based on a Hashtable and functions to get the next usable ID for insertion, making IDs reusable after deletion of the entry.

Method Summary

void	addDatabaseListener(DatabaseListener l) Adds a listener for the DatabaseEvent posted after the database changes.
<T> void	associate(AssociationID<T> associationID, Integer objectID, T association) Associates a association in a certain relation to a certain Object.
<T> void	associateGlobally(AssociationID<T> associationID, T association) Associates a global association in a certain relation to the database.
O	delete(Integer id) Removes and returns the object with the given id from the database.
void	delete(O object) Removes all objects from the database that are equal to the given object.
protected void	deleteAssociations(Integer id) Deletes associations for the given id if there are any.
int	dimensionality() Returns the dimensionality of the data contained by this database in case of O extends FeatureVector.
protected void	fireObjectInserted(Integer objectID) Notifies all listeners that have registered interest for notification on this event type.
protected void	fireObjectRemoved(Integer objectID) Notifies all listeners that have registered interest for notification on this event type.
protected void	fireObjectsChanged(List<Integer> objectIDs) Notifies all listeners that have registered interest for notification on this event type.
protected void	fireObjectsInserted(List<Integer> objectIDs) Notifies all listeners that have registered interest for notification on this event type.
protected void	fireObjectsRemoved(List<Integer> objectIDs) Notifies all listeners that have registered interest for notification on this event type.
O	get(Integer id) Returns the DatabaseObject represented by the specified id.
<T> T	getAssociation(AssociationID<T> associationID, Integer objectID) Returns the association specified by the given associationID and related to the specified Object.
Associations	getAssociations(Integer id) Returns all associations for a given ID.
<T> T	getGlobalAssociation(AssociationID<T> associationID) Returns the global association specified by the given associationID.
List<Integer>	getIDs() Returns a list of all ids currently in use in the database.
protected List<O>	getObjects(List<Pair<O,Associations>> objectAndAssociationsList) Helper method to extract the list of database objects from the specified list of objects and their associations.
void	insert(List<Pair<O,Associations>> objectsAndAssociationsList) Initializes the database by inserting the specified objects and their associations into the database.
Integer	insert(Pair<O,Associations> objectAndAssociations) Inserts the given object into the database.
boolean	isSet(AssociationID<?> associationID) Checks whether an association is set for at least one id in the database.
boolean	isSetForAllObjects(AssociationID<?> associationID) Checks whether an association is set for every id in the database.
boolean	isSetGlobally(AssociationID<?> associationID) Checks whether a global association is set in the database.
Iterator<Integer>	iterator() Returns an iterator iterating over all keys of the database.
Map<Integer,Database<O>>	partition(Map<Integer,List<Integer>> partitions) Returns a Map of partition IDs to Databases according to the specified Map of partition IDs to Lists of IDs.
Map<Integer,Database<O>>	partition(Map<Integer,List<Integer>> partitions, Class<? extends Database<O>> dbClass, List<String> dbParameters) Returns a Map of partition IDs to Databases of the specified class according to the specified Map of partition IDs to Lists of IDs.
Set<Integer>	randomSample(int k, long seed) Returns a random sample of k ids.
void	removeDatabaseListener(DatabaseListener l) Removes a listener previously added with addTreeModelListener.
protected void	restoreID(Integer id) Makes the given id reusable for new insertion operations.
protected void	setAssociations(Integer id, Associations idAssociations) Sets the specified association to the specified id.
protected Integer	setNewID(O object) Provides a new id for the specified database object suitable as key for a new insertion and sets this id in the specified database object.
int	size() Returns the number of objects contained in this Database.

Methods inherited from class de.lmu.ifi.dbs.elki.utilities.optionhandling.AbstractParameterizable

addOption, addParameterizable, addParameterizable, checkGlobalParameterConstraints, collectOptions, getAttributeSettings, getParameters, rememberParametersExcept, removeOption, removeParameterizable, setParameters, shortDescription

Methods inherited from class de.lmu.ifi.dbs.elki.logging.AbstractLoggable

debugFine, debugFiner, debugFinest, exception, progress, verbose, warning

Methods inherited from class java.lang.Object

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

Methods inherited from interface de.lmu.ifi.dbs.elki.database.Database

bulkKNNQueryForID, kNNQueryForID, kNNQueryForObject, rangeQuery, reverseKNNQuery

Methods inherited from interface de.lmu.ifi.dbs.elki.utilities.optionhandling.Parameterizable

checkGlobalParameterConstraints, collectOptions, getParameters, setParameters, shortDescription

Field Detail

globalAssociations

private final Associations globalAssociations

Map to hold global associations.

associations

private final AssociationMaps associations

Map to hold association maps.

counter

private int counter

Counter to provide a new Integer id.

reusableIDs

private List<Integer> reusableIDs

Provides a list of reusable ids.

content

private Map<Integer,O extends DatabaseObject> content

Map to hold the objects of the database.

listenerList

protected List<DatabaseListener> listenerList

Holds the listener of this database.

Constructor Detail

AbstractDatabase

protected AbstractDatabase()

Provides an abstract database including a mapping for associations based on a Hashtable and functions to get the next usable ID for insertion, making IDs reusable after deletion of the entry. Make sure to delete any associations when deleting an entry (e.g. by calling deleteAssociations(id)).

Method Detail

insert

public void insert(List<Pair<O,Associations>> objectsAndAssociationsList)
            throws UnableToComplyException

Description copied from interface: Database

Initializes the database by inserting the specified objects and their associations into the database.

Specified by:

insert in interface Database<O extends DatabaseObject>

Parameters:

objectsAndAssociationsList - the list of objects and their associations to be inserted

Throws:

UnableToComplyException - if initialization is not possible

insert

public Integer insert(Pair<O,Associations> objectAndAssociations)
               throws UnableToComplyException

Description copied from interface: Database

Inserts the given object into the database.

Specified by:

insert in interface Database<O extends DatabaseObject>

Parameters:

objectAndAssociations - the object and its associations to be inserted

Returns:

the ID assigned to the inserted object

Throws:

UnableToComplyException - if database reached limit of storage capacity

delete

public void delete(O object)

Description copied from interface: Database

Removes all objects from the database that are equal to the given object.

Specified by:

delete in interface Database<O extends DatabaseObject>

Parameters:

object - the object to be removed from database

delete

public O delete(Integer id)

Description copied from interface: Database

Removes and returns the object with the given id from the database.

Specified by:

delete in interface Database<O extends DatabaseObject>

Parameters:

id - the id of an object to be removed from the database

Returns:

the object that has been removed

size

public final int size()

Description copied from interface: Database

Returns the number of objects contained in this Database.

Specified by:

size in interface Database<O extends DatabaseObject>

Returns:

the number of objects in this Database

get

public final O get(Integer id)

Description copied from interface: Database

Returns the DatabaseObject represented by the specified id.

Specified by:

get in interface Database<O extends DatabaseObject>

Parameters:

id - the id of the Object to be obtained from the Database

Returns:

Object the Object represented by to the specified id in the Database

iterator

public final Iterator<Integer> iterator()

Returns an iterator iterating over all keys of the database.

Specified by:

iterator in interface Database<O extends DatabaseObject>

Specified by:

iterator in interface Iterable<Integer>

Returns:

an iterator iterating over all keys of the database

See Also:

- for a Database {@code db}, this allows the construct {@code for(Integer id : db) // work with database ids }.

associate

public <T> void associate(AssociationID<T> associationID,
                          Integer objectID,
                          T association)

Description copied from interface: Database

Associates a association in a certain relation to a certain Object.

Specified by:

associate in interface Database<O extends DatabaseObject>

Type Parameters:

T - association data type

Parameters:

associationID - the id of the association, respectively the name of the relation

objectID - the id of the Object to which the association is related

association - the association to be associated with the specified Object

associateGlobally

public <T> void associateGlobally(AssociationID<T> associationID,
                                  T association)
                       throws ClassCastException

Associates a global association in a certain relation to the database.

Specified by:

associateGlobally in interface Database<O extends DatabaseObject>

Type Parameters:

T - association data type

Parameters:

associationID - the id of the association, respectively the name of the relation

association - the association to be associated with the database

Throws:

ClassCastException - if the association cannot be cast as the class that is specified by the associationID

getAssociation

public <T> T getAssociation(AssociationID<T> associationID,
                            Integer objectID)

Description copied from interface: Database

Returns the association specified by the given associationID and related to the specified Object.

Specified by:

getAssociation in interface Database<O extends DatabaseObject>

Type Parameters:

T - association data type

Parameters:

associationID - the id of the association, respectively the name of the relation

objectID - the id of the Object to which the association is related

Returns:

Object the association which is associated with the specified Object or null, if there is no association with the specified associationID nor with the specified objectID

getGlobalAssociation

public <T> T getGlobalAssociation(AssociationID<T> associationID)

Returns the global association specified by the given associationID.

Specified by:

getGlobalAssociation in interface Database<O extends DatabaseObject>

Type Parameters:

T - association data type

Parameters:

associationID - the id of the association, respectively the name of the relation

Returns:

Object the association or null, if there is no association with the specified associationID

setNewID

protected Integer setNewID(O object)
                    throws UnableToComplyException

Provides a new id for the specified database object suitable as key for a new insertion and sets this id in the specified database object.

Parameters:

object - the object for which a new id should be provided

Returns:

a new id suitable as key for a new insertion

Throws:

UnableToComplyException - if the database has reached the limit and, therefore, new insertions are not possible

restoreID

protected void restoreID(Integer id)

Makes the given id reusable for new insertion operations.

Parameters:

id - the id to become reusable

deleteAssociations

protected void deleteAssociations(Integer id)

Deletes associations for the given id if there are any.

Parameters:

id - id of which all associations are to be deleted

getAssociations

public Associations getAssociations(Integer id)

Returns all associations for a given ID.

Specified by:

getAssociations in interface Database<O extends DatabaseObject>

Parameters:

id - the id for which the associations are to be returned

Returns:

all associations for a given ID

setAssociations

protected void setAssociations(Integer id,
                               Associations idAssociations)

Sets the specified association to the specified id.

Parameters:

id - the id which is to associate with specified associations

idAssociations - the associations to be associated with the specified id

partition

public Map<Integer,Database<O>> partition(Map<Integer,List<Integer>> partitions)
                                                          throws UnableToComplyException

Description copied from interface: Database

Returns a Map of partition IDs to Databases according to the specified Map of partition IDs to Lists of IDs. Returns the same result as partition(partitions, null, null).

Specified by:

partition in interface Database<O extends DatabaseObject>

Parameters:

partitions - a Map of partition IDs to Lists of IDs defining a partition of the database

Returns:

a Map of partition IDs to Databases of the specified class according to the specified Map of Lists of IDs - the databases in this map may contain the same objects, but the managing IDs are generally independent from the IDs in the original database

Throws:

UnableToComplyException - in case of problems during insertion

partition

public Map<Integer,Database<O>> partition(Map<Integer,List<Integer>> partitions,
                                          Class<? extends Database<O>> dbClass,
                                          List<String> dbParameters)
                                                          throws UnableToComplyException

Description copied from interface: Database

Returns a Map of partition IDs to Databases of the specified class according to the specified Map of partition IDs to Lists of IDs.

Specified by:

partition in interface Database<O extends DatabaseObject>

Parameters:

partitions - a Map of partition IDs to Lists of IDs defining a partition of the database

dbClass - the class of the databases to be returned, if this argument is null the returned databases have the same class as this database

dbParameters - the parameter array of the returned database class, only necessary if parameter dbClass is not null

Returns:

a Map of partition IDs to Databases of the specified class according to the specified Map of Lists of IDs - the databases in this map may contain the same objects, but the managing IDs are generally independent from the IDs in the original database

Throws:

UnableToComplyException - in case of problems during insertion or class instantiation

isSetForAllObjects

public boolean isSetForAllObjects(AssociationID<?> associationID)

Checks whether an association is set for every id in the database.

Specified by:

isSetForAllObjects in interface Database<O extends DatabaseObject>

Parameters:

associationID - an association id to be checked

Returns:

true, if the association is set for every id in the database, false otherwise

isSet

public boolean isSet(AssociationID<?> associationID)

Checks whether an association is set for at least one id in the database.

Specified by:

isSet in interface Database<O extends DatabaseObject>

Parameters:

associationID - an association id to be checked

Returns:

true, if the association is set for every id in the database, false otherwise

isSetGlobally

public boolean isSetGlobally(AssociationID<?> associationID)

Description copied from interface: Database

Checks whether a global association is set in the database.

Specified by:

isSetGlobally in interface Database<O extends DatabaseObject>

Parameters:

associationID - an association id to be checked

Returns:

true, if the global association is set in the database, false otherwise

randomSample

public final Set<Integer> randomSample(int k,
                                       long seed)

Description copied from interface: Database

Returns a random sample of k ids.

Specified by:

randomSample in interface Database<O extends DatabaseObject>

Parameters:

k - the number of ids to return

seed - for random generator

Returns:

a list of k ids

getIDs

public List<Integer> getIDs()

Returns a list of all ids currently in use in the database. The list is not affected of any changes made to the database in the future nor vice versa.

Specified by:

getIDs in interface Database<O extends DatabaseObject>

Returns:

a list comprising all IDs currently in use

See Also:

Database.getIDs()

dimensionality

public int dimensionality()
                   throws UnsupportedOperationException

Description copied from interface: Database

Returns the dimensionality of the data contained by this database in case of O extends FeatureVector.

Specified by:

dimensionality in interface Database<O extends DatabaseObject>

Returns:

the dimensionality of the data contained by this database in case of O extends FeatureVector

Throws:

UnsupportedOperationException - if O does not extend FeatureVector or the database is empty

getObjects

protected List<O> getObjects(List<Pair<O,Associations>> objectAndAssociationsList)

Helper method to extract the list of database objects from the specified list of objects and their associations.

Parameters:

objectAndAssociationsList - the list of objects and their associations

Returns:

the list of database objects

addDatabaseListener

public void addDatabaseListener(DatabaseListener l)

Adds a listener for the DatabaseEvent posted after the database changes.

Specified by:

addDatabaseListener in interface Database<O extends DatabaseObject>

Parameters:

l - the listener to add

See Also:

removeDatabaseListener(de.lmu.ifi.dbs.elki.database.DatabaseListener)

removeDatabaseListener

public void removeDatabaseListener(DatabaseListener l)

Removes a listener previously added with addTreeModelListener.

Specified by:

removeDatabaseListener in interface Database<O extends DatabaseObject>

Parameters:

l - the listener to remove

See Also:

addDatabaseListener(de.lmu.ifi.dbs.elki.database.DatabaseListener)

fireObjectsChanged

protected void fireObjectsChanged(List<Integer> objectIDs)

Notifies all listeners that have registered interest for notification on this event type.

Parameters:

objectIDs - the ids of the database objects that have been removed

fireObjectsInserted

protected void fireObjectsInserted(List<Integer> objectIDs)

Notifies all listeners that have registered interest for notification on this event type.

Parameters:

objectIDs - the ids of the database objects that have been removed

fireObjectInserted

protected void fireObjectInserted(Integer objectID)

Notifies all listeners that have registered interest for notification on this event type.

Parameters:

objectID - the ids of the database object that has been removed

fireObjectsRemoved

protected void fireObjectsRemoved(List<Integer> objectIDs)

Notifies all listeners that have registered interest for notification on this event type.

Parameters:

objectIDs - the ids of the database objects that have been removed

fireObjectRemoved

protected void fireObjectRemoved(Integer objectID)

Notifies all listeners that have registered interest for notification on this event type.

Parameters:

objectID - the id of the database object that has been removed