net.obsearch
Interface Index<O extends OB>

Type Parameters:

O - The object that will be indexed in the database

All Known Subinterfaces:

IndexByte<O>, IndexDouble<O>, IndexFloat<O>, IndexInt<O>, IndexLong<O>, IndexShort<O>

All Known Implementing Classes:

AbstractBucketIndex, AbstractBucketSorter, AbstractDistancePermutations, AbstractDistPerm, AbstractOBIndex, AbstractPivotOBIndex, AbstractSketch64, AesaFloat, DistPermByte, DistPermDouble, DistPermFloat, DistPermInt, DistPermLong, DistPermShort, Sketch64Byte, Sketch64Double, Sketch64Float, Sketch64Int, Sketch64Long, Sketch64Short

public interface Index<O extends OB>

This the main contract for OBSearch indexes. The normal lifecycle of an index is: 1) Insert many records 2) Perform a freeze A freeze is an operation that calculates different information on the data. The idea is to "learn" how the sample data is distributed to improve performance. You cannot perform searches on an unfrozen index. Note that freezing the index does not mean you cannot insert new data. You can! 3) Insert/Delete new records/ and search. There are indexes that wrap other indexes to provide extended functionality. Please consult the documentation for each index. The index assumes that for any two objects a, b: if a.equals(b) then for their corresponding byte arrays ba,bb ba.equals(bb) must also hold.

Since:

0.7

Author:

Arnoldo Jose Muller Molina

Field Summary

static int

ID_SIZE Size in bytes of the object IDs used in OBSearch.

Method Summary

void	close() Closes the database.
long	databaseSize() Returns the database size.
String	debug(O object) Routine that helps to debug objects.
OperationStatus	delete(O object) Deletes the given object from the database.
OperationStatus	exists(O object) Returns true if the given object exists in the database.
void	freeze() Freezes the index.
long	getBox(O object) Returns the box where the given object is stored.
O	getObject(long i) This method returns the object with internal id "i".
Statistics	getStats()
Class<O>	getType() Return the type that is stored in the index.
void	init(OBStoreFactory fact) This method *must* be called after de-serializing the database object and after instantiating the index.
OperationStatus	insert(O object) Inserts the given object into the index.
OperationStatus	insert(O object, long id) Inserts the given object into the index.
OperationStatus	insertBulk(O object) Inserts the given object into the index.
OperationStatus	insertBulk(O object, long id) Inserts the given object into the index.
boolean	isFrozen() Returns true if the index is frozen.
void	loadObject(long i, O object) Load the data of object # i into the given object
void	resetStats() Resets all the stats counters.
void	setPreFreezeCheck(boolean preFreezeCheck) If the index should check for existent objects before freeze.
long	totalBoxes() Returns the total number of boxes this index can hold.

Field Detail

ID_SIZE

static final int ID_SIZE

Size in bytes of the object IDs used in OBSearch.

See Also:

Constant Field Values

Method Detail

insert

OperationStatus insert(O object)
                       throws OBStorageException,
                              OBException,
                              IllegalAccessException,
                              InstantiationException

Inserts the given object into the index.

Parameters:

object - The object to be added.

Returns:

Status.OK if the object was inserted. Status.EXISTS if the object existed in the DB. The method getId() of OperationStatus will return the id used by the object.

Throws:

OBStorageException - If something goes wrong with the DB

OBException - User generated exception

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

Since:

0.0

getType

Class<O> getType()

Return the type that is stored in the index.

Returns:

loadObject

void loadObject(long i,
                O object)
                throws OBException

Load the data of object # i into the given object

Parameters:

i -

object -

Throws:

OBException

insertBulk

OperationStatus insertBulk(O object)
                           throws OBStorageException,
                                  OBException,
                                  IllegalAccessException,
                                  InstantiationException

Inserts the given object into the index. It does not check if the object to be inserted exists in the database.

Parameters:

object - The object to be added.

Returns:

Status.OK

Throws:

OBStorageException - If something goes wrong with the DB

OBException - User generated exception

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

Since:

0.0

insert

OperationStatus insert(O object,
                       long id)
                       throws OBStorageException,
                              OBException,
                              IllegalAccessException,
                              InstantiationException

Inserts the given object into the index.

Parameters:

object - The object to be added.

id - The id that will be used for the object.

Returns:

If Status.OK or Status.EXISTS then the result will hold the id of the inserted object and the operation is successful. Otherwise an exception will be thrown.

Throws:

OBStorageException - If something goes wrong with the DB

OBException - User generated exception

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

Since:

0.0

insertBulk

OperationStatus insertBulk(O object,
                           long id)
                           throws OBStorageException,
                                  OBException,
                                  IllegalAccessException,
                                  InstantiationException

Inserts the given object into the index. It does not check if the object to be inserted exists in the database.

Parameters:

object - The object to be added.

id - The id that will be used for the object.

Returns:

Status.OK

Throws:

OBStorageException - If something goes wrong with the DB

OBException - User generated exception

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

Since:

0.0

isFrozen

boolean isFrozen()

Returns true if the index is frozen.

Returns:

true if the index is frozen, false otherwise

exists

OperationStatus exists(O object)
                       throws OBStorageException,
                              OBException,
                              IllegalAccessException,
                              InstantiationException

Returns true if the given object exists in the database. This method was created for OBSearch internal use. If you are relying on this method a lot, isn't it better to use a hash table or a B-tree instead of OBSearch? O.equals(...) is used to calculate the equality of two objects.

Parameters:

object - The object that will be searched.

Returns:

Status.EXISTS and the object's id if the object exists in the database, otherwise Status.NOT_EXISTS is returned.

Throws:

OBStorageException - If something goes wrong with the DB

OBException - User generated exception

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

freeze

void freeze()
            throws IOException,
                   AlreadyFrozenException,
                   IllegalIdException,
                   IllegalAccessException,
                   InstantiationException,
                   OBStorageException,
                   OutOfRangeException,
                   OBException,
                   PivotsUnavailableException

Freezes the index. From this point data can be inserted, searched and deleted. The index might deteriorate at some point so every once in a while it is a good idea to rebuild the index. A PivotSelector must be executed before calling this method.

Throws:

IOException - if the index serialization process fails

AlreadyFrozenException - If the index was already frozen and the user attempted to freeze it again

OBStorageException - If something goes wrong with the DB

OBException - User generated exception

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

OutOfRangeException - If the distance of any object to any other object exceeds the range defined by the user.

IllegalIdException - This exception is left as a Debug flag. If you receive this exception please report the problem to: http://code.google.com/p/obsearch/issues/list

PivotsUnavailableException

delete

OperationStatus delete(O object)
                       throws OBStorageException,
                              OBException,
                              IllegalAccessException,
                              InstantiationException,
                              NotFrozenException

Deletes the given object from the database.

Parameters:

object - The object to be deleted

Returns:

Status.OK and the deleted object's id if the object was found and successfully deleted. Status.NOT_EXISTS if the object is not in the database.

Throws:

NotFrozenException - if the index has not been frozen.

OBStorageException - If something goes wrong with the DB

OBException - User generated exception

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

Since:

0.0

getObject

O getObject(long i)
                       throws IllegalIdException,
                              IllegalAccessException,
                              InstantiationException,
                              OBException

This method returns the object with internal id "i". Mainly used for internal validation purposes, users should not have to use this method directly

Parameters:

i - The id to be retrieved

Returns:

The object associated to the given id. if the index has not been frozen. was deleted successfully

Throws:

OBStorageException - If something goes wrong with the DB

OBException - User generated exception

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

IllegalIdException

close

void close()
           throws OBException

Closes the database.

Throws:

OBStorageException - If something goes wrong with the DB.

OBException

totalBoxes

long totalBoxes()

Returns the total number of boxes this index can hold. This is an optional operation, not all indexes need to support this.

Returns:

The total number of boxes the index can eventually support.

getBox

long getBox(O object)
            throws OBException

Returns the box where the given object is stored. This is an optional operation, not all indexes need to support this.

Parameters:

object - The object to be analyzed

Returns:

The box that corresponds to object

Throws:

OBException - User generated exception

databaseSize

long databaseSize()
                  throws OBStorageException

Returns the database size.

Returns:

Number of elements in the database

Throws:

OBStorageException - If something goes wrong with the DB

OBStorageException - If the underlying storage device signaled an error.

init

void init(OBStoreFactory fact)
          throws OBStorageException,
                 NotFrozenException,
                 IllegalAccessException,
                 InstantiationException,
                 OBException,
                 IOException

This method *must* be called after de-serializing the database object and after instantiating the index. This method is called by the #org.obsearch.ambient.Ambient, users do not need to worry about this method.

Parameters:

fact - The storage factory that will be used to store the data.

Throws:

OBStorageException - If something goes wrong with the DB

OBException - User generated exception

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

NotFrozenException - if the index has not been frozen.

OBStorageException - If something goes wrong with the DB.

IOException - if the index serialization process fails

resetStats

void resetStats()

Resets all the stats counters.

getStats

Statistics getStats()
                    throws OBStorageException

Returns:

A human-readable list of stats relevant for this index.

Throws:

OBStorageException

debug

String debug(O object)
             throws OBException,
                    InstantiationException,
                    IllegalAccessException

Routine that helps to debug objects. Returns some human-readable information regarding the given object. This method is optional.

Throws:

IllegalAccessException

InstantiationException

OBException

setPreFreezeCheck

void setPreFreezeCheck(boolean preFreezeCheck)

If the index should check for existent objects before freeze.

Parameters:

preFreezeCheck - Set the flag.