com.antelmann.db
Interface Database<S>

Type Parameters:

S - the type of the underlying service this database relies on (e.g. a java.sql.Connection)

All Superinterfaces:

Closeable, LoggerProvider

All Known Implementing Classes:

AbstractDatabase, GDB, OpenGeoDB, SQLDatabase, SQLFactoryDatabase

public interface Database<S>
extends Closeable, LoggerProvider

provides a wrapper around a database service implementation and a lookup service for persistence services for DBEntry objects. All database access through Database instances provided by this class is monitored and can be logged by adding listeners.

Author:

Holger Antelmann

See Also:

DBTransaction, DatabaseChangeMonitor, DBEntry, DBClassStore

Method Summary

boolean	addConfigListener(DBConfigListener listener)
boolean	addStoreListener(DBStoreListener listener)
Collection<Class<? extends DBEntry>>	getAvailableClassStores() returns an unmodifiable view of the existing classes that map to a DBClassStore in this database
DBConfigListener[]	getConfigListeners()
User	getCurrentUser() returns the user credentials of the one currently using this database
S	getDatabaseService() provides access to the actual database service that is used by the implementation of this interface
Logger	getLogger() access to the Logger that by default uses a LogWriter writing entries directly into this database.
<T extends DBEntry> DBClassStore<T>	getStore(Class<T> c) allows to query for a persistence service for a given DBEntry class.
DBStoreListener[]	getStoreListeners()
DBTransaction	getTransaction() provides access to the DBTransaction, which coordinates all access to the Resources via DBClassStore.
<E extends DBEntry,I> I	queryStoreForInterface(Class<E> type, Class<I> desiredInterface) allows to query an embedded DBClassStore for additional functionality exposed via the given desired interface.
boolean	removeConfigListener(DBConfigListener listener)
boolean	removeStoreListener(DBStoreListener listener)
void	setCurrentUser(User user) sets the user credentials for accessing resources
<E extends DBEntry> void	setVersioningEnabled(Class<E> type, boolean flag) Enabling versioning on a class store results on additional overhead for insert, update and delete operations, as for each update and delete operation the store first retrieves the existing instance from the database before storing the new version.

Methods inherited from interface java.io.Closeable

close

Method Detail

getCurrentUser

User getCurrentUser()

returns the user credentials of the one currently using this database

setCurrentUser

void setCurrentUser(User user)

sets the user credentials for accessing resources

getAvailableClassStores

Collection<Class<? extends DBEntry>> getAvailableClassStores()

returns an unmodifiable view of the existing classes that map to a DBClassStore in this database

getTransaction

DBTransaction getTransaction()

provides access to the DBTransaction, which coordinates all access to the Resources via DBClassStore. The returned DBTransaction is always the same object for a particular database.

getDatabaseService

S getDatabaseService()

provides access to the actual database service that is used by the implementation of this interface

getLogger

Logger getLogger()

access to the Logger that by default uses a LogWriter writing entries directly into this database. This Logger is also commonly used to log all database access; adding your own LogWriter therefore allows to be notified of database access via logging. As this may possibly happen outside transaction boundaries (depending on the implementation), be aware of possible side-effects (e.g. in the event of transaction aborts).

Specified by:

getLogger in interface LoggerProvider

getStore

<T extends DBEntry> DBClassStore<T> getStore(Class<T> c)

allows to query for a persistence service for a given DBEntry class.

Returns:

a persistence service for the given DBEntry class or null if such service doesn't exist

addStoreListener

boolean addStoreListener(DBStoreListener listener)

removeStoreListener

boolean removeStoreListener(DBStoreListener listener)

getStoreListeners

DBStoreListener[] getStoreListeners()

addConfigListener

boolean addConfigListener(DBConfigListener listener)

removeConfigListener

boolean removeConfigListener(DBConfigListener listener)

getConfigListeners

DBConfigListener[] getConfigListeners()

setVersioningEnabled

<E extends DBEntry> void setVersioningEnabled(Class<E> type,
                                              boolean flag)

Enabling versioning on a class store results on additional overhead for insert, update and delete operations, as for each update and delete operation the store first retrieves the existing instance from the database before storing the new version. If versioning is enabled, a DBStoreListener will then receive DBVersionedUpdateEvent objects instead of DBUpdateEvent objects for database updates on such store.

See Also:

DBVersionedUpdateEvent

queryStoreForInterface

<E extends DBEntry,I> I queryStoreForInterface(Class<E> type,
                                               Class<I> desiredInterface)

allows to query an embedded DBClassStore for additional functionality exposed via the given desired interface. Optionally, the database itself may provide certain interfaces on specific stores and return that instance. If the embedded DBClassStore instance implements the desired interface, that interface is wrapped and returned to the caller - or null is returned. It is not save to cast the returned interface to DBClassStore!

The implementation is to ensure that all calls to the returned interface are synchronized with and embedded in a transaction if the desired interface inherits TransactionRequired; then, each call on a method from the returned interface is either directly committed to the database or the transaction is managed by the caller directly.

Note that each method implementation that actually alters data is responsible for firing appropriate DBUpdateEvent objects to the listeners of the database.

The return value cannot be casted to the original class store; only a proxy is returned that merely exposes the requested interface.

Class stores that implement interfaces queried here don't need to handle transactions themselves, similar to the way the DBClassStore methods can be implemented.

Parameters:

type - the DBEntry-type of the DBClassStore that is to implement the desired interface

desiredInterface - the class of the interface that the store is implementing

Returns:

a proxy to the functionality that the queried store provides or null if either the class store doesn't exist or doesn't support the desired interface.

See Also:

TransactionRequired, DBUtils.runInTransaction(java.util.concurrent.Callable, DBTransaction, boolean), AbstractDatabase.queryStoreForInterface(Class, Class), AbstractDatabase.queryStoreForInterface(Class, Class)