Environment for
DeveLoping
KDD-Applications
Supported by Index-Structures

de.lmu.ifi.dbs.elki.database
Interface Database<O extends DatabaseObject>

Type Parameters:
O - the type of DatabaseObject as element of the database
All Superinterfaces:
Iterable<Integer>, Parameterizable, Result
All Known Implementing Classes:
AbstractDatabase, IndexDatabase, MetricalIndexDatabase, SequentialDatabase, SpatialIndexDatabase

public interface Database<O extends DatabaseObject>
extends Parameterizable, Result, Iterable<Integer>

Database specifies the requirements for any database implementation. Note that any implementing class is supposed to provide a constructor without parameters for dynamic instantiation.

Author:
Elke Achtert

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.
<D extends Distance<D>>
List<List<DistanceResultPair<D>>>
bulkKNNQueryForID(List<Integer> ids, int k, DistanceFunction<O,D> distanceFunction)
          Performs k-nearest neighbor queries for the given object IDs.
 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.
 int dimensionality()
          Returns the dimensionality of the data contained by this database in case of O extends FeatureVector.
 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 comprising all IDs currently in use.
 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.
<D extends Distance<D>>
List<DistanceResultPair<D>>
kNNQueryForID(Integer id, int k, DistanceFunction<O,D> distanceFunction)
          Performs a k-nearest neighbor query for the given object ID.
<D extends Distance<D>>
List<DistanceResultPair<D>>
kNNQueryForObject(O queryObject, int k, DistanceFunction<O,D> distanceFunction)
          Performs a k-nearest neighbor query for the given object.
 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.
<D extends Distance<D>>
List<DistanceResultPair<D>>
rangeQuery(Integer id, String epsilon, DistanceFunction<O,D> distanceFunction)
          Performs a range query for the given object ID with the given epsilon range and the according distance function.
 void removeDatabaseListener(DatabaseListener l)
          Removes a listener previously added with addTreeModelListener.
<D extends Distance<D>>
List<DistanceResultPair<D>>
reverseKNNQuery(Integer id, int k, DistanceFunction<O,D> distanceFunction)
          Performs a reverse k-nearest neighbor query for the given object ID.
 int size()
          Returns the number of objects contained in this Database.
 
Methods inherited from interface de.lmu.ifi.dbs.elki.utilities.optionhandling.Parameterizable
checkGlobalParameterConstraints, collectOptions, getParameters, setParameters, shortDescription
 

Method Detail

insert

void insert(List<Pair<O,Associations>> objectsAndAssociationsList)
            throws UnableToComplyException
Initializes the database by inserting the specified objects and their associations into the database.

Parameters:
objectsAndAssociationsList - the list of objects and their associations to be inserted
Throws:
UnableToComplyException - if initialization is not possible

insert

Integer insert(Pair<O,Associations> objectAndAssociations)
               throws UnableToComplyException
Inserts the given object into the database.

Parameters:
objectAndAssociations - the object and its associations to be inserted
Returns:
the ID assigned to the inserted object
Throws:
UnableToComplyException - if insertion is not possible

delete

void delete(O object)
Removes all objects from the database that are equal to the given object.

Parameters:
object - the object to be removed from database

delete

O delete(Integer id)
Removes and returns the object with the given id from the database.

Parameters:
id - the id of an object to be removed from the database
Returns:
the object that has been removed

size

int size()
Returns the number of objects contained in this Database.

Returns:
the number of objects in this Database

randomSample

Set<Integer> randomSample(int k,
                          long seed)
Returns a random sample of k ids.

Parameters:
k - the number of ids to return
seed - for random generator
Returns:
a list of k ids

rangeQuery

<D extends Distance<D>> List<DistanceResultPair<D>> rangeQuery(Integer id,
                                                               String epsilon,
                                                               DistanceFunction<O,D> distanceFunction)

Performs a range query for the given object ID with the given epsilon range and the according distance function.

The query result is sorted in ascending order w.r.t. the distance to the query object.

Type Parameters:
D - distance type
Parameters:
id - the ID of the query object
epsilon - the string representation of the query range
distanceFunction - the distance function that computes the distances between the objects
Returns:
a List of the query results

kNNQueryForID

<D extends Distance<D>> List<DistanceResultPair<D>> kNNQueryForID(Integer id,
                                                                  int k,
                                                                  DistanceFunction<O,D> distanceFunction)

Performs a k-nearest neighbor query for the given object ID.

The query result is sorted in ascending order w.r.t. the distance to the query object.

The general contract for the result of kNN queries in ELKI is that the resulting list contains exactly k nearest neighbors including the query object. Generally, ties will be resolved by the order of objects in the database. Any implementing method should inform about the exact policy of resolving ties.

Generally, it is assumed that the database does not contain less than k objects.

Type Parameters:
D - distance type
Parameters:
id - the ID of the query object
k - the number of nearest neighbors to be returned
distanceFunction - the distance function that computes the distances between the objects
Returns:
a List of the query results

kNNQueryForObject

<D extends Distance<D>> List<DistanceResultPair<D>> kNNQueryForObject(O queryObject,
                                                                      int k,
                                                                      DistanceFunction<O,D> distanceFunction)

Performs a k-nearest neighbor query for the given object.

The query result is sorted in ascending order w.r.t. the distance to the query object.

The general contract for the result of kNN queries in ELKI is that the resulting list contains exactly k nearest neighbors including the query object if it is an element of this database. Generally, ties will be resolved by the order of objects in the database. Any implementing method should inform about the exact policy of resolving ties.

Generally, it is assumed that the database does not contain less than k objects.

Type Parameters:
D - distance type
Parameters:
queryObject - the query object
k - the number of nearest neighbors to be returned
distanceFunction - the distance function that computes the distances between the objects
Returns:
a List of the query results

bulkKNNQueryForID

<D extends Distance<D>> List<List<DistanceResultPair<D>>> bulkKNNQueryForID(List<Integer> ids,
                                                                            int k,
                                                                            DistanceFunction<O,D> distanceFunction)

Performs k-nearest neighbor queries for the given object IDs.

The query result is sorted in ascending order w.r.t. the distance to the query object.

The general contract for the result of kNN queries in ELKI is that the resulting lists contain exactly k nearest neighbors including the query objects. Generally, ties will be resolved by the order of objects in the database. Any implementing method should inform about the exact policy of resolving ties.

Generally, it is assumed that the database does not contain less than k objects.

Type Parameters:
D - distance type
Parameters:
ids - the IDs of the query objects
k - the number of nearest neighbors to be returned
distanceFunction - the distance function that computes the distances between the objects
Returns:
a List of List of the query results

reverseKNNQuery

<D extends Distance<D>> List<DistanceResultPair<D>> reverseKNNQuery(Integer id,
                                                                    int k,
                                                                    DistanceFunction<O,D> distanceFunction)

Performs a reverse k-nearest neighbor query for the given object ID.

The query result is sorted in ascending order w.r.t. the distance to the query object.

Generally, it is assumed that the database does not contain less than k objects.

Type Parameters:
D - distance type
Parameters:
id - the ID of the query object
k - the size of k-nearest neighborhood of any database object o to contain a database object in order to include o in the result list
distanceFunction - the distance function that computes the distances between the objects
Returns:
a List of the query results

get

O get(Integer id)
Returns the DatabaseObject represented by the specified id.

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

associate

<T> void associate(AssociationID<T> associationID,
                   Integer objectID,
                   T association)
               throws ClassCastException
Associates a association in a certain relation to a certain Object.

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
Throws:
ClassCastException - if the association cannot be cast as the class that is specified by the associationID

associateGlobally

<T> void associateGlobally(AssociationID<T> associationID,
                           T association)
                       throws ClassCastException
Associates a global association in a certain relation to the database.

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

getAssociations

Associations getAssociations(Integer id)
Returns all associations for a given ID.

Parameters:
id - the id for which the associations are to be returned
Returns:
all associations for a given ID

getAssociation

<T> T getAssociation(AssociationID<T> associationID,
                     Integer objectID)
Returns the association specified by the given associationID and related to the specified Object.

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

<T> T getGlobalAssociation(AssociationID<T> associationID)
Returns the global association specified by the given associationID.

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

iterator

Iterator<Integer> iterator()
Returns an iterator iterating over all keys of the database.

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 }.

getIDs

List<Integer> getIDs()
Returns a list comprising all IDs currently in use. The list returned shall not be linked to any actual list possibly hold in the database implementation.

Returns:
a list comprising all IDs currently in use

partition

Map<Integer,Database<O>> partition(Map<Integer,List<Integer>> partitions,
                                   Class<? extends Database<O>> dbClass,
                                   List<String> dbParameters)
                                                          throws UnableToComplyException
Returns a Map of partition IDs to Databases of the specified class according to the specified Map of partition IDs to Lists of IDs.

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

partition

Map<Integer,Database<O>> partition(Map<Integer,List<Integer>> partitions)
                                                          throws UnableToComplyException
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).

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

isSetForAllObjects

boolean isSetForAllObjects(AssociationID<?> associationID)
Checks whether an association is set for every id in the database.

Parameters:
associationID - an association id to be checked
Returns:
true, if the association is set for every id in the database, false otherwise

isSet

boolean isSet(AssociationID<?> associationID)
Checks whether an association is set for at least one id in the database.

Parameters:
associationID - an association id to be checked
Returns:
true, if the association is set for every id in the database, false otherwise

isSetGlobally

boolean isSetGlobally(AssociationID<?> associationID)
Checks whether a global association is set in the database.

Parameters:
associationID - an association id to be checked
Returns:
true, if the global association is set in the database, false otherwise

dimensionality

int dimensionality()
                   throws UnsupportedOperationException
Returns the dimensionality of the data contained by this database in case of O extends FeatureVector.

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

addDatabaseListener

void addDatabaseListener(DatabaseListener l)
Adds a listener for the DatabaseEvent posted after the database changes.

Parameters:
l - the listener to add
See Also:
removeDatabaseListener(de.lmu.ifi.dbs.elki.database.DatabaseListener)

removeDatabaseListener

void removeDatabaseListener(DatabaseListener l)
Removes a listener previously added with addTreeModelListener.

Parameters:
l - the listener to remove
See Also:
addDatabaseListener(de.lmu.ifi.dbs.elki.database.DatabaseListener)

Release 0.2.1 (2009-07-13_1605)