Holger's Java API

## 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)`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads