com.unister.semweb.drums.api
Class DRUMS<Data extends AbstractKVStorable>

java.lang.Object
  com.unister.semweb.drums.api.DRUMS<Data>

Type Parameters:

Data - an implementation of AbstractKVStorable, e.g. GeneralStorable

public class DRUMS<Data extends AbstractKVStorable>
extends java.lang.Object

An instance of this class provides access to a DRUMS-table. The instance allows managing the storage of AbstractKVStorables. Use the static methods in DRUMSInstantiator to get an instance of DRUMS.

Use the method insertOrMerge(AbstractKVStorable...) to insert or merge records.
To update records use the method update(AbstractKVStorable...).
Single selects can be performed by the method #select(byte[]).
To perform range selects, a DRUMSReader should be instantiated (getReader().
The whole table is scanned best, using an DRUMSIterator (getIterator().

Author:

Nils Thieme, Martin Nettling

Nested Class Summary

static class

DRUMS.AccessMode the accessmode for DRUMS

Method Summary

void	close() Closes the DRUMS.
void	disableForceMode() Disable the force mode of DRUMS.
void	enableForceMode() Enables the force mode of DRUMS.
int	findElementInReadBuffer(java.nio.ByteBuffer workingBuffer, byte[] key, int indexInChunk) Searches for the given key in workingBuffer, beginning at the given index.
BucketContainer<Data>	getBucketContainer()
java.lang.String	getDatabaseDirectory()
int	getElementKeySize()
int	getElementSize()
DRUMSParameterSet<Data>	getGlobalParameters()
AbstractHashFunction	getHashFunction()
DRUMSIterator<Data>	getIterator() Instantiates a new DRUMSIterator and returns it.
Data	getPrototype()
DRUMSReader<Data>	getReader() Returns a DRUMSReader.
SyncManager<Data>	getSyncManager()
void	insertOrMerge(Data... toPersist) Adds or merges the given data.
void	join() Joins all the DRUMS-table.
java.util.List<Data>	read(int bucketId, int elementOffset, int numberToRead) Reads numberToRead elements (or less if there are not enough elements) from the bucket with the given bucketId beginning at the element offset.
java.util.List<Data>	searchForData(HeaderIndexFile<Data> indexFile, byte[]... keys) Searches for the AbstractKVStorable-records corresponding the given keys within the given indexFile.
java.util.List<Data>	select(byte[]... keys) Selects all existing records to the keys in the given array.
void	setHashFunction(AbstractHashFunction hashfunction) sets a new HashFunction.
void	setSynchronizerFactory(ISynchronizerFactory<Data> factory) Expert method.
long	size()
void	update(Data... records) Updates the given data.

Methods inherited from class java.lang.Object

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

Method Detail

setSynchronizerFactory

public void setSynchronizerFactory(ISynchronizerFactory<Data> factory)

Expert method. Sets the SynchronizerFactory.

Parameters:

factory -

getBucketContainer

public BucketContainer<Data> getBucketContainer()

Returns:

a pointer to the local BucketContainer

getSyncManager

public SyncManager<Data> getSyncManager()

Returns:

a pointer to the local SyncManager

insertOrMerge

public void insertOrMerge(Data... toPersist)
                   throws DRUMSException,
                          java.lang.InterruptedException

Adds or merges the given data. If all memory buckets are full, this method is blocking the calling thread.

A merge calls the method Data#merge(AbstractKVStorable).

Parameters:

toPersist - data to insert or update

Throws:

DRUMSException - if an unexpected error occurs

java.lang.InterruptedException - if the call blocks and the current thread is interrupted

update

public void update(Data... records)
            throws java.io.IOException

Updates the given data. Be careful, ONLY updates are provided. If the given array contains elements, which are not already stored in the underlying DRUMS-table, they will be not taken into account during synchronization.

This method uses the UpdateOnlySynchronizer, which by itself uses the Data's implemented update-function (Data#update(AbstractKVStorable)) to update elements. If you want to merge objects, use #insertOrMerge(Data ...) instead.

Parameters:

records - the data to update

Throws:

java.io.IOException

select

public java.util.List<Data> select(byte[]... keys)
                                                       throws DRUMSException

Selects all existing records to the keys in the given array.

Parameters:

keys - the keys to look for

Returns:

a list of all found elements

Throws:

DRUMSException

read

public java.util.List<Data> read(int bucketId,
                                 int elementOffset,
                                 int numberToRead)
                                                     throws FileLockException,
                                                            java.io.IOException

Reads numberToRead elements (or less if there are not enough elements) from the bucket with the given bucketId beginning at the element offset.

Parameters:

bucketId - the id of the bucket where to read the elements from

elementOffset - the byte offset, where to start reading

numberToRead - the number of elements to read

Returns:

ArrayList containing the data-objects

Throws:

FileLockException

java.io.IOException

searchForData

public java.util.List<Data> searchForData(HeaderIndexFile<Data> indexFile,
                                          byte[]... keys)
                                                              throws java.io.IOException

Searches for the AbstractKVStorable-records corresponding the given keys within the given indexFile. This is done by using the IndexForHeaderIndexFile from the given HeaderIndexFile. If you want to do this in a more sequential way, try to use the method read(int, int, int) or use an DRUMSIterator . (getIterator())

Parameters:

indexFile - HeaderIndexFile, where to search for the keys

keys - the keys to search for

Returns:

an ArrayList which contains the found records. Can be less than the number of requested keys.

Throws:

java.io.IOException

size

public long size()
          throws FileLockException,
                 java.io.IOException

Returns:

the number of elements in the database.

Throws:

java.io.IOException

FileLockException

findElementInReadBuffer

public int findElementInReadBuffer(java.nio.ByteBuffer workingBuffer,
                                   byte[] key,
                                   int indexInChunk)

Searches for the given key in workingBuffer, beginning at the given index. Remember: The records in the given workingBuffer have to be ordered ascending.

Parameters:

workingBuffer - the ByteBuffer to work on

key - the key to find

indexInChunk - the start position of reading the workingBuffer

Returns:

the byteOffset where the key was found.
-1 if the key wasn't found

getIterator

public DRUMSIterator<Data> getIterator()

Instantiates a new DRUMSIterator and returns it.

Returns:

a new DRUMSIterator

getReader

public DRUMSReader<Data> getReader()
                                                       throws FileLockException,
                                                              java.io.IOException

Returns a DRUMSReader. If the DRUMSReader was not instantiated yet, it will be instantiated. If there exists an instance, but the files were already closed, the files will be reopened.

Remember, if you have an opened Reader. You can't synchronize buckets.

Returns:

a pointer to the internal DRUMSReader-instance

Throws:

java.io.IOException

FileLockException

join

public void join()
          throws java.lang.InterruptedException

Joins all the DRUMS-table.

Throws:

java.lang.InterruptedException

close

public void close()
           throws java.lang.InterruptedException

Closes the DRUMS.

Throws:

java.lang.InterruptedException

enableForceMode

public void enableForceMode()

Enables the force mode of DRUMS. All buckets will be synchronized independent from its fill level and last sync-time.
Be careful: All buckets will be affected. Even if a bucket contains only one element, the synchronizer is going to synchronize this bucket.
This method doesn't block the insert-methods.

disableForceMode

public void disableForceMode()

Disable the force mode of DRUMS. Buckets will be synchronized only if constraints like fill-level and last sync-time are fulfilled.

getElementSize

public int getElementSize()

Returns:

the size of one record to store in bytes

getElementKeySize

public int getElementKeySize()

Returns:

the size of the key of one record

getHashFunction

public AbstractHashFunction getHashFunction()

Returns:

the underlying hash-function

setHashFunction

public void setHashFunction(AbstractHashFunction hashfunction)

sets a new HashFunction. Be careful with this method. Overwriting the hashfunction, when elements are already inserted may cause, that you won't find those elements by select.

Parameters:

hashfunction - the hash-function to set

getDatabaseDirectory

public java.lang.String getDatabaseDirectory()

Returns:

the database-directory

getPrototype

public Data getPrototype()

Returns:

a pointer to the prototype. This is not a clone.

getGlobalParameters

public DRUMSParameterSet<Data> getGlobalParameters()

Returns:

the DRUMSParameterSet that are used within the DRUMS