messif.buckets.storage.impl
Class DatabaseStorage<T>

java.lang.Object
  extended by messif.buckets.storage.impl.DatabaseStorage<T>
Type Parameters:
T - the class of objects stored in this storage
All Implemented Interfaces:
java.io.Serializable, Addible<T>, Index<T>, ModifiableIndex<T>, IntStorage<T>, IntStorageIndexed<T>, Storage<T>, StorageIndexed<T>

public class DatabaseStorage<T>
extends java.lang.Object
implements IntStorageIndexed<T>, java.io.Serializable

Database-based storage. The objects in this storage are stored in a relational database that is accessed via JDBC.

A database table that will hold the stored data must be created. The primary key of the table must be integer compatible and must be automatically generated by the database. The data column types must match the given column convertors.

See Also:
Serialized Form

Nested Class Summary
static class DatabaseStorage.BinarySerializableColumnConvertor<T>
          Column convertor that uses a database BLOB into which instances of T are binary serialized/deserialized.
static interface DatabaseStorage.ColumnConvertor<T>
          Provides a conversion between database column data and object instances.
 
Field Summary
static DatabaseStorage.ColumnConvertor<LocalAbstractObject> locatorColumnConvertor
          Column convertor that stores/restores a locator URI of LocalAbstractObjects stored in the database.
static DatabaseStorage.ColumnConvertor<java.lang.Object> trivialColumnConvertor
          Column convertor that stores/restores instances supported directly by the database.
 
Constructor Summary
DatabaseStorage(java.lang.Class<? extends T> storedObjectsClass, java.lang.String dbConnUrl, java.util.Properties dbConnInfo, java.lang.String tableName, java.lang.String primaryKeyColumn, java.lang.String[] columnNames, DatabaseStorage.ColumnConvertor<T>[] columnConvertors)
          Constructs an empty database storage.
 
Method Summary
 boolean add(T object)
          Adds the specified object to this instance.
protected  void closeConnection()
          Closes connection to the database.
static
<T> DatabaseStorage<T>
create(java.lang.Class<T> storedObjectsClass, java.util.Map<java.lang.String,java.lang.Object> parameters)
          Creates a new database storage.
 void destroy()
          Destroy this index.
protected  java.sql.PreparedStatement execute(java.sql.PreparedStatement statement, java.lang.String sql, java.lang.Integer primaryKey, T object)
          Prepares and executes an SQL command.
 void finalize()
          Finalize this index.
protected  java.sql.Connection getConnection()
          Returns the database connection of this storage.
 java.lang.Class<? extends T> getStoredObjectsClass()
          Returns the class of objects that the this storage works with.
 boolean isEmpty()
          Returns true if this storage contains no elements.
 T read(int address)
          Reads the object stored at the specified address in this storage.
 void remove(int address)
          Removes the object stored at the specified address in this storage.
 IntStorageSearch<T> search()
          Returns a search for all objects in this index.
<C> IntStorageSearch<T>
search(IndexComparator<? super C,? super T> comparator, C key)
          Returns a search for objects in this index that have any of the specified keys.
<C> IntStorageSearch<T>
search(IndexComparator<? super C,? super T> comparator, C from, C to)
          Returns a search for objects in this index that are within the specified key-range.
<C> IntStorageSearch<T>
search(IndexComparator<? super C,? super T> comparator, java.util.Collection<? extends C> keys)
          Returns a search for objects in this index that have any of the specified keys.
 int size()
          Returns the number of elements in this storage.
 IntAddress<T> store(T object)
          Stores an object in this storage.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

locatorColumnConvertor

public static final DatabaseStorage.ColumnConvertor<LocalAbstractObject> locatorColumnConvertor
Column convertor that stores/restores a locator URI of LocalAbstractObjects stored in the database. Note that the associated column must be String-compatible. When restoring an object, its key is set only if it has no key yet.


trivialColumnConvertor

public static final DatabaseStorage.ColumnConvertor<java.lang.Object> trivialColumnConvertor
Column convertor that stores/restores instances supported directly by the database. For example, numbers can be accessed as Integers or Doubles, BLOBs as byte[] arrays, etc.

Constructor Detail

DatabaseStorage

public DatabaseStorage(java.lang.Class<? extends T> storedObjectsClass,
                       java.lang.String dbConnUrl,
                       java.util.Properties dbConnInfo,
                       java.lang.String tableName,
                       java.lang.String primaryKeyColumn,
                       java.lang.String[] columnNames,
                       DatabaseStorage.ColumnConvertor<T>[] columnConvertors)
                throws java.lang.IllegalArgumentException
Constructs an empty database storage. Note that the connection is established when the first manipulation-method is called.

Parameters:
storedObjectsClass - the class of objects that the storage will work with
dbConnUrl - the database connection URL (e.g. "jdbc:mysql://localhost/somedb")
dbConnInfo - additional parameters of the connection (e.g. "user" and "password")
tableName - the name of the table in the database
primaryKeyColumn - the name of the column that is the primary key of the table
columnNames - the names of columns where the data are stored
columnConvertors - the convertors that convert between the storage instances and database column; there must be one convertor for every data column name from columnNames
Throws:
java.lang.IllegalArgumentException - if the column names and column convertors do not match
Method Detail

finalize

public void finalize()
              throws java.lang.Throwable
Description copied from interface: ModifiableIndex
Finalize this index. All transient resources associated with this index are released. After this method is called, the store and retrieval methods' behavior is unpredictable.

Specified by:
finalize in interface ModifiableIndex<T>
Specified by:
finalize in interface Storage<T>
Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable - if there was an error while cleaning

destroy

public void destroy()
             throws java.lang.Throwable
Description copied from interface: ModifiableIndex
Destroy this index. This method releases all resources (transient and persistent) associated with this index. After this method is called, the store and retrieval methods' behavior is unpredictable.

Specified by:
destroy in interface ModifiableIndex<T>
Specified by:
destroy in interface Storage<T>
Throws:
java.lang.Throwable - if there was an error while cleaning

getConnection

protected final java.sql.Connection getConnection()
                                           throws java.sql.SQLException
Returns the database connection of this storage.

Returns:
the database connection
Throws:
java.sql.SQLException - if there was a problem connecting to the database

closeConnection

protected void closeConnection()
                        throws java.sql.SQLException
Closes connection to the database.

Throws:
java.sql.SQLException - if there was an error while closing the connection

execute

protected final java.sql.PreparedStatement execute(java.sql.PreparedStatement statement,
                                                   java.lang.String sql,
                                                   java.lang.Integer primaryKey,
                                                   T object)
                                            throws java.sql.SQLException,
                                                   BucketStorageException
Prepares and executes an SQL command. The ResultSet returned by the execution can be retrieved by Statement.getResultSet(). Note that if a SQLRecoverableException is thrown while executing, the current connection is closed and the command retried.

Parameters:
statement - the previous cached statement that matches the given sql (can be null)
sql - the SQL command to prepare and execute; one parameter (using "?") for the primary key or n parameters for data can be specified
primaryKey - the value for the one SQL parameter of the primary key (if null the parameter is not set)
object - the instance that is converted to database columns using columnConvertors (if null the parameters are not set)
Returns:
an executed prepared statement
Throws:
java.sql.SQLException - if there was an unrecoverable error when parsing or executing the SQL command
BucketStorageException - if there was an error converting a column value

create

public static <T> DatabaseStorage<T> create(java.lang.Class<T> storedObjectsClass,
                                            java.util.Map<java.lang.String,java.lang.Object> parameters)
                                 throws java.lang.IllegalArgumentException
Creates a new database storage. The additional parameters are specified in the parameters map with the following recognized key names: All additinal parameters are passed to the database driver.

Type Parameters:
T - the class of objects that the new storage will work with
Parameters:
storedObjectsClass - the class of objects that the new storage will work with
parameters - list of named parameters (see above)
Returns:
a new database storage instance
Throws:
java.lang.IllegalArgumentException - if the parameters specified are invalid (null values, etc.)

getStoredObjectsClass

public java.lang.Class<? extends T> getStoredObjectsClass()
Returns the class of objects that the this storage works with.

Returns:
the class of objects that the this storage works with

isEmpty

public boolean isEmpty()
Returns true if this storage contains no elements.

Returns:
true if this storage contains no elements

size

public int size()
Returns the number of elements in this storage.

Specified by:
size in interface Index<T>
Returns:
the number of elements in this storage

store

public IntAddress<T> store(T object)
                    throws BucketStorageException
Description copied from interface: Storage
Stores an object in this storage. The address returned by this call can be used to retrieve or remove the object.

Specified by:
store in interface IntStorage<T>
Specified by:
store in interface Storage<T>
Parameters:
object - the object to store
Returns:
the address where the object has been stored
Throws:
BucketStorageException - if there was an error writing the data

read

public T read(int address)
       throws BucketStorageException
Description copied from interface: IntStorage
Reads the object stored at the specified address in this storage.

Specified by:
read in interface IntStorage<T>
Parameters:
address - the address of the object to read
Returns:
the object retrieved
Throws:
BucketStorageException - if there was an error reading the data

remove

public void remove(int address)
            throws BucketStorageException,
                   java.lang.UnsupportedOperationException
Description copied from interface: IntStorage
Removes the object stored at the specified address in this storage. This operation is optional and need not be implemented.

Specified by:
remove in interface IntStorage<T>
Parameters:
address - the address of the object to remove
Throws:
BucketStorageException - if there was an error deleting an object
java.lang.UnsupportedOperationException - if this storage does not support removal of objects

add

public boolean add(T object)
            throws BucketStorageException
Description copied from interface: Addible
Adds the specified object to this instance.

Specified by:
add in interface Addible<T>
Parameters:
object - the object to be added
Returns:
true if the addition was successful
Throws:
BucketStorageException - if there was an error adding the object

search

public IntStorageSearch<T> search()
                           throws java.lang.IllegalStateException
Description copied from interface: Index
Returns a search for all objects in this index.

Specified by:
search in interface Index<T>
Specified by:
search in interface ModifiableIndex<T>
Specified by:
search in interface IntStorageIndexed<T>
Specified by:
search in interface StorageIndexed<T>
Returns:
a search for all objects in this index
Throws:
java.lang.IllegalStateException - if there was an error initializing the search on this index

search

public <C> IntStorageSearch<T> search(IndexComparator<? super C,? super T> comparator,
                                      C key)
                           throws java.lang.IllegalStateException
Description copied from interface: Index
Returns a search for objects in this index that have any of the specified keys. The equality is checked exclusively by using the specified comparator, thus key need not necessarily be of the same class as the objects stored in this index and also consistency with equals is not required.

Note that objects are not necessarily returned in the order defined by the comparator

Specified by:
search in interface Index<T>
Specified by:
search in interface ModifiableIndex<T>
Specified by:
search in interface IntStorageIndexed<T>
Specified by:
search in interface StorageIndexed<T>
Type Parameters:
C - the type of the key used by the search
Parameters:
comparator - compares the key with the stored objects
key - the key to search for
Returns:
a search for objects in this index
Throws:
java.lang.IllegalStateException - if there was an error initializing the search on this index

search

public <C> IntStorageSearch<T> search(IndexComparator<? super C,? super T> comparator,
                                      java.util.Collection<? extends C> keys)
                           throws java.lang.IllegalStateException
Description copied from interface: Index
Returns a search for objects in this index that have any of the specified keys. The equality is checked exclusively by using the specified comparator, thus key need not necessarily be of the same class as the objects stored in this index and also consistency with equals is not required.

Note that objects are not necessarily returned in the order defined by the comparator

Specified by:
search in interface Index<T>
Specified by:
search in interface ModifiableIndex<T>
Specified by:
search in interface IntStorageIndexed<T>
Specified by:
search in interface StorageIndexed<T>
Type Parameters:
C - the type of the keys used by the search
Parameters:
comparator - compares the keys with the stored objects
keys - the keys to search for (at least one key must be given)
Returns:
a search for objects in this index
Throws:
java.lang.IllegalStateException - if there was an error initializing the search on this index

search

public <C> IntStorageSearch<T> search(IndexComparator<? super C,? super T> comparator,
                                      C from,
                                      C to)
                           throws java.lang.IllegalStateException
Description copied from interface: Index
Returns a search for objects in this index that are within the specified key-range. The key boundaries [from, to] need not necessarily be of the same class as the objects stored in this index, however, the comparator must be able to compare the boundaries and the internal objects.

Note that objects are not returned in the order defined by the comparator

Specified by:
search in interface Index<T>
Specified by:
search in interface ModifiableIndex<T>
Specified by:
search in interface IntStorageIndexed<T>
Specified by:
search in interface StorageIndexed<T>
Type Parameters:
C - the type the boundaries used by the search
Parameters:
comparator - compares the boundaries [from, to] with the stored objects
from - the lower bound on the searched objects, i.e. objects greater or equal are returned
to - the upper bound on the searched objects, i.e. objects smaller or equal are returned
Returns:
a search for objects in this index
Throws:
java.lang.IllegalStateException - if there was an error initializing the search on this index