net.obsearch.index
Class AbstractOBIndex<O extends OB>

java.lang.Object
  net.obsearch.index.AbstractOBIndex<O>

All Implemented Interfaces:

Index<O>

Direct Known Subclasses:

AbstractPivotOBIndex

public abstract class AbstractOBIndex<O extends OB>
extends Object
implements Index<O>

AbstractOBIndex contains functionality regarding object storage. Children of this class should define a way of searching those objects. This class provides default implementations of methods that are considered optional in the Index interface.

Author:

Arnoldo Jose Muller Molina

Field Summary

protected OBStoreLong	A Objects are stored by their id's here.
protected OBStoreFactory	fact Factory used by this class and by subclasses to create appropiate storage devices.
protected boolean	isFrozen True if this index is frozen.
protected Statistics	stats Statistics related to this index.
protected Class<O>	type The type used to instantiate objects of type O.

Fields inherited from interface net.obsearch.Index

ID_SIZE

Constructor Summary

	AbstractOBIndex()
protected	AbstractOBIndex(Class<O> type) Constructors of an AbstractOBIndex should receive only parameters related to the operation of the index.

Method Summary

protected void	assertFrozen() If the database is frozen returns silently if it is not throws NotFrozenException.
protected O	bytesToObject(byte[] data) Instantiates an object O from the given data array.
protected O	bytesToObject(ByteBuffer data) Instantiates an object O from the given data array.
protected void	clearACache() Clear A cache.
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.
protected abstract OperationStatus	deleteAux(O object) Deletes the entry of this object in the index.
protected double	distance(O a2, O b)
O[]	emptyPivotsArray(int size) Create an empty pivots array.
protected OperationStatus	findAux(O object) Find the Id of the given object.
void	freeze() Freezes the index.
long	getBox(O object) Returns the box where the given object is stored.
O	getObject(long id) This method returns the object with internal id "i".
Statistics	getStats()
Class<O>	getType() Returns the type of the object to be stored.
void	init(OBStoreFactory fact) Initialize the index.
protected void	initCache() Initializes the object cache aCache.
protected void	initStorageDevices() Initializes storage devices required by this class.
OperationStatus	insert(O object) Inserts the given object into the index.
OperationStatus	insert(O object, long id) Inserts the given object into the index.
protected abstract OperationStatus	insertAux(long id, O object) Inserts the given object into the particular index.
protected abstract OperationStatus	insertAuxBulk(long id, O object) Inserts the given object into the particular 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.
double	intrinsicDimensionality(int sampleSize) Calculate the intrinsic dimension of the underlying database
boolean	isFrozen() Returns true if the index is frozen.
boolean	isPreFreeze() If we are going to check for the existence of data before freezing.
boolean	isPreFreezeCheck()
void	loadObject(long i, O object) Loads object i into the given object
protected O[]	loadPivots(byte[][] serializedPivots)
protected byte[]	objectToByteBuffer(O object)
protected byte[]	objectToBytes(O object) Converts an object into an array of bytes.
void	resetStats() Resets all the stats counters.
protected byte[][]	serializePivots(long[] ids) Finds the given objects in A and serializes them.
void	setFixedRecord(boolean fixedRecord)
void	setFixedRecord(int fixedRecordSize)
void	setIdAutoGeneration(boolean auto)
void	setPreFreeze(boolean isPreFreeze) If we are going to check for the existence of data before freezing preFreezeCheck should be set to true.
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.

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.obsearch.Index

exists

Field Detail

stats

protected transient Statistics stats

Statistics related to this index.

A

protected transient OBStoreLong A

Objects are stored by their id's here.

fact

protected transient OBStoreFactory fact

Factory used by this class and by subclasses to create appropiate storage devices.

isFrozen

protected boolean isFrozen

True if this index is frozen.

type

protected Class<O extends OB> type

The type used to instantiate objects of type O.

Constructor Detail

AbstractOBIndex

public AbstractOBIndex()

AbstractOBIndex

protected AbstractOBIndex(Class<O> type)
                   throws OBStorageException,
                          OBException

Constructors of an AbstractOBIndex should receive only parameters related to the operation of the index. The factory and the initialization will be executed by init(OBStoreFactory)

Parameters:

type -

Throws:

OBStorageException

OBException

Method Detail

isPreFreezeCheck

public boolean isPreFreezeCheck()

setPreFreezeCheck

public void setPreFreezeCheck(boolean preFreezeCheck)

Description copied from interface: Index

If the index should check for existent objects before freeze.

Specified by:

setPreFreezeCheck in interface Index<O extends OB>

Parameters:

preFreezeCheck - Set the flag.

clearACache

protected void clearACache()

Clear A cache.

getType

public final Class<O> getType()

Returns the type of the object to be stored.

Specified by:

getType in interface Index<O extends OB>

Returns:

type

assertFrozen

protected void assertFrozen()
                     throws NotFrozenException

If the database is frozen returns silently if it is not throws NotFrozenException.

Throws:

NotFrozenException - if the index has not been frozen.

init

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

Initialize the index.

Specified by:

init in interface Index<O extends OB>

Parameters:

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

Throws:

OBStorageException

OBException

NotFrozenException - if the index has not been frozen.

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

initStorageDevices

protected void initStorageDevices()
                           throws OBStorageException,
                                  OBException

Initializes storage devices required by this class.

Throws:

OBStorageException - If the storage device could not be created.

OBException

setFixedRecord

public void setFixedRecord(boolean fixedRecord)

setFixedRecord

public void setFixedRecord(int fixedRecordSize)

initCache

protected void initCache()
                  throws OBException

Initializes the object cache aCache.

Throws:

DatabaseException - If something goes wrong with the DB.

OBException

loadObject

public void loadObject(long i,
                       O object)
                throws OBException

Loads object i into the given object

Specified by:

loadObject in interface Index<O extends OB>

Parameters:

i - The object to load.

object - Where we will upload the data.

Throws:

IOException

OBException

intrinsicDimensionality

public double intrinsicDimensionality(int sampleSize)
                               throws IllegalIdException,
                                      IllegalAccessException,
                                      InstantiationException,
                                      OBException

Calculate the intrinsic dimension of the underlying database

Parameters:

sample -

Returns:

Throws:

OBException

InstantiationException

IllegalAccessException

IllegalIdException

distance

protected double distance(O a2,
                          O b)
                   throws OBException

Throws:

OBException

isPreFreeze

public boolean isPreFreeze()

If we are going to check for the existence of data before freezing.

Returns:

true if we are going to check for the existence of data before freezing.

setPreFreeze

public void setPreFreeze(boolean isPreFreeze)

If we are going to check for the existence of data before freezing preFreezeCheck should be set to true. If you know each object is unique then you can set this to false and with this improve performance.

Parameters:

preFreezeCheck - true (quality, data integrity) false (performance)

bytesToObject

protected O bytesToObject(ByteBuffer data)
                              throws OBException,
                                     InstantiationException,
                                     IllegalAccessException,
                                     IllegalIdException

Instantiates an object O from the given data array.

Throws:

OBException

InstantiationException

IllegalAccessException

IllegalIdException

bytesToObject

protected O bytesToObject(byte[] data)
                              throws OBException,
                                     InstantiationException,
                                     IllegalAccessException,
                                     IllegalIdException

Instantiates an object O from the given data array.

Throws:

OBException

InstantiationException

IllegalAccessException

IllegalIdException

close

public void close()
           throws OBException

Description copied from interface: Index

Closes the database.

Specified by:

close in interface Index<O extends OB>

Throws:

OBStorageException - If something goes wrong with the DB.

OBException

databaseSize

public long databaseSize()
                  throws OBStorageException

Description copied from interface: Index

Returns the database size.

Specified by:

databaseSize in interface Index<O extends OB>

Returns:

Number of elements in the database

Throws:

OBStorageException - If something goes wrong with the DB

debug

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

Description copied from interface: Index

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

Specified by:

debug in interface Index<O extends OB>

Throws:

OBException

InstantiationException

IllegalAccessException

delete

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

Description copied from interface: Index

Deletes the given object from the database.

Specified by:

delete in interface Index<O extends OB>

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

deleteAux

protected abstract OperationStatus deleteAux(O object)
                                      throws OBException,
                                             IllegalAccessException,
                                             InstantiationException

Deletes the entry of this object in the index. The current class will remove the object from A if the result status is Status.OK.

Parameters:

object - object to be deleted.

Returns:

Status.OK if the object was deleted. Status.NOT_EXISTS no object matched.

Throws:

OBException

IllegalAccessException

InstantiationException

objectToBytes

protected byte[] objectToBytes(O object)
                        throws OBException

Converts an object into an array of bytes.

Parameters:

object - Object to convert.

Returns:

The bytes array representation of the object.

Throws:

OBException

objectToByteBuffer

protected byte[] objectToByteBuffer(O object)
                             throws OBException

Throws:

OBException

getObject

public O getObject(long id)
                       throws IllegalIdException,
                              IllegalAccessException,
                              InstantiationException,
                              OBException

Description copied from interface: Index

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

Specified by:

getObject in interface Index<O extends OB>

Parameters:

id - The id to be retrieved

Returns:

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

Throws:

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

OBStorageException - If something goes wrong with the DB

OBException - User generated exception

IllegalIdException

findAux

protected OperationStatus findAux(O object)
                           throws IllegalIdException,
                                  IllegalAccessException,
                                  InstantiationException,
                                  OBException

Find the Id of the given object. (the distance 0 is considered as equal)

Parameters:

object - The object to search

Returns:

Status.OK if the object is found (with the id) otherwise, Status.NOT_EXISTS

Throws:

IllegalIdException

IllegalAccessException

InstantiationException

OBException

getStats

public Statistics getStats()
                    throws OBStorageException

Specified by:

getStats in interface Index<O extends OB>

Returns:

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

Throws:

OBStorageException

setIdAutoGeneration

public void setIdAutoGeneration(boolean auto)
                         throws OBException

Throws:

OBException

insert

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

Description copied from interface: Index

Inserts the given object into the index.

Specified by:

insert in interface Index<O extends OB>

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

insertBulk

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

Description copied from interface: Index

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

Specified by:

insertBulk in interface Index<O extends OB>

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

insertBulk

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

Description copied from interface: Index

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

Specified by:

insertBulk in interface Index<O extends OB>

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

insert

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

Description copied from interface: Index

Inserts the given object into the index.

Specified by:

insert in interface Index<O extends OB>

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

insertAux

protected abstract OperationStatus insertAux(long id,
                                             O object)
                                      throws OBStorageException,
                                             OBException,
                                             IllegalAccessException,
                                             InstantiationException

Inserts the given object into the particular index. The caller inserts the actual object so the implementing class only has to worry about adding the id inside the index.

Parameters:

id - The id that will be used to insert the object.

object - The object that will be inserted.

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

OBException

IllegalAccessException

InstantiationException

insertAuxBulk

protected abstract OperationStatus insertAuxBulk(long id,
                                                 O object)
                                          throws OBStorageException,
                                                 OBException,
                                                 IllegalAccessException,
                                                 InstantiationException

Inserts the given object into the particular index. No checks regarding existence are performed. We assume the user already checked uniqueness.

Parameters:

id - The id that will be used to insert the object.

object - The object that will be inserted.

Returns:

Status.OK

Throws:

OBStorageException

OBException

IllegalAccessException

InstantiationException

freeze

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

Description copied from interface: Index

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.

Specified by:

freeze in interface Index<O extends OB>

Throws:

PivotsUnavailableException

IOException

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

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

IllegalAccessException - If there is a problem when instantiating objects O

InstantiationException - If there is a problem when instantiating objects O

OBStorageException - If something goes wrong with the DB

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

OBException - User generated exception

See Also:

Index.freeze()

getBox

public long getBox(O object)
            throws OBException

Description copied from interface: Index

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

Specified by:

getBox in interface Index<O extends OB>

Parameters:

object - The object to be analyzed

Returns:

The box that corresponds to object

Throws:

OBException - User generated exception

isFrozen

public boolean isFrozen()

Description copied from interface: Index

Returns true if the index is frozen.

Specified by:

isFrozen in interface Index<O extends OB>

Returns:

true if the index is frozen, false otherwise

resetStats

public void resetStats()

Description copied from interface: Index

Resets all the stats counters.

Specified by:

resetStats in interface Index<O extends OB>

totalBoxes

public long totalBoxes()

Description copied from interface: Index

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

Specified by:

totalBoxes in interface Index<O extends OB>

Returns:

The total number of boxes the index can eventually support.

serializePivots

protected byte[][] serializePivots(long[] ids)
                            throws IllegalIdException,
                                   IllegalAccessException,
                                   InstantiationException,
                                   OBException

Finds the given objects in A and serializes them.

Parameters:

ids - Objects that will be loaded

Returns:

Serialization of the objects.

Throws:

OBException

InstantiationException

IllegalAccessException

IllegalIdException

emptyPivotsArray

public O[] emptyPivotsArray(int size)

Create an empty pivots array.

Returns:

an empty pivots array of size #pivotsCount.

loadPivots

protected O[] loadPivots(byte[][] serializedPivots)
                             throws IllegalIdException,
                                    OBException,
                                    InstantiationException,
                                    IllegalAccessException

Throws:

IllegalIdException

OBException

InstantiationException

IllegalAccessException