Holger's Java API

## com.antelmann.db
Class AbstractDatabase<S>

    java.lang.Object
      com.antelmann.db.AbstractDatabase<S>

Type Parameters:
  `S` - the underlying service that this database is based upon

All Implemented Interfaces:
  Database<S>, LoginListener, LoggerProvider, QueryMechanism, Closeable, EventListener

Direct Known Subclasses:
  SQLDatabase

    public abstract class AbstractDatabase<S>

extends Object
implements Database<S>, LoginListener, QueryMechanism

a base class for implementing a database. All methods are synchronized on the transaction rather than this instance! It leaves the transaction management to the inheriting class by omitting the implementation of `getTransaction()` and also requires `close()` to be implemented. Each databaseService access through DBClassStore objects is monitored by this implementation as every DBClassStore instance is wrapped by a proxy. In addition, this implementation also provides a mechanism to control access to its DBClassStore instances via DBAccessController interface. Also, this implementation serves as a LoginListener and can thus automatically update its current user when appropriately added as a listener. Other than that, the logging itself is also left to an inheriting class. Unless otherwise specified, all methods in this class that throw a `DatabaseException` are implemented via `DBUtils.runInTransaction(Task, DBTransaction, boolean)` to ensure proper transactional behavior.

Author:
  Holger Antelmann

Nested Class Summary

Nested classes/interfaces inherited from interface com.antelmann.db.LoginListener
`LoginListener.Adapter`

Constructor Summary
`AbstractDatabase(S databaseService)`
`AbstractDatabase(S databaseService, User user)` sets the current user (may be null)
`AbstractDatabase(S databaseService, User user, DBAccessController controller, LogWriter logWriter)`
`AbstractDatabase(S databaseService, User user, DBAccessController controller, LogWriter logWriter, boolean automatedTransactions)`
`AbstractDatabase(S databaseService, User user, LogWriter logWriter)` the given logWriter - assumed to write into the databaseService if not null - will be added to the embedded Logger

Method Summary
`boolean` `addConfigListener(DBConfigListener listener)`
`boolean` `addStoreListener(DBStoreListener listener)`
`void` `checkAccessRight(Object right)` checks whether there is a current user on the database with the given access right and throws an exception if that's not the case
`void` `checkTransactionActive()` test for an active transaction; implies ownership of the transaction
`protected void` `clearAllData()` this method clears all stores, listeners, writers and users from this database in preparation for calling `close()`
`void` `close()`
`boolean` `contains(DBReference ref)`

`

`<T extends DBEntry> boolean`

`

`contains(T entry)`

`

`<T extends DBEntry> int`

`

`count(Class<T> c, Filter<? super T> filter)`

`

`<T extends DBEntry> int`

`

`countStubs(Class<T> c, Filter<Stub<?>> filter)`

`boolean` `delete(DBReference ref)`
`boolean` `delete(Stub<?> stub)`

`

`<T extends DBEntry> boolean`

`

`delete(T entry)`

`static

`<E extends DBEntry,I> I`

`

`extractInterface(DBClassStore<E> store, Class<I> desiredInterface)`
allows to extract an interface from a store only if it is 'exposed'

`void` `failedLogin(UserLoginStore uls, String location, Exception exception)` called when a login was either canceled or failed due to an exception
`protected void` `finalize()`
`protected void` `fireStoreChanges()`
`DBAccessController` `getAccessController()`
`Set<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

`

`<T extends DBEntry> T`

`

`getEntry(Class<T> c, Object id)`
a shortcut w/o having to go through the DBClassStore

`DBEntry` `getEntry(DBReference ref)` This method will begin and abort a transaction if none is active at the time.

`

`<T extends DBEntry> T`

`

`getEntry(Stub<T> stub)`
This method will begin and abort a transaction if none is active at the time.

`

`<T extends DBEntry> T`

`

`getFirstEntry(Class<T> type, Filter<? super T> filter)`

`

`<T extends DBEntry> Stub<T>`

`

`getFirstStub(Class<T> type, Filter<Stub<?>> filter)`

`Logger` `getLogger()` a logger that contains the logWriter given in the constructor; it is used to log all databaseService access with the special level 'dbaccess' by default

`protected

`<T extends DBEntry> DBClassStore<T>`

`

`getOriginalClassStore(Class<T> c)`
returns the original class store that was put in here directly (not the proxy/wrapper that ensures listeners are notified and transactional integrity is guaranteed)

`

`<T extends DBEntry> T`

`

`getRandomEntry(Class<T> type)`

`

`<T extends DBEntry> T`

`

`getRandomEntry(Class<T> type, Filter<? super T> filter)`

`

`<T extends DBEntry> Stub<T>`

`

`getRandomStub(Class<T> type)`

`

`<T extends DBEntry> DBClassStore<T>`

`

`getStore(Class<T> c)`
returns a monitored Proxy of the previously added DBClassStore for c or null

`

`<T extends DBEntry> DBClassStore<T>`

`

`getStoreForEntry(T entry)`
provides a save cast to obtain the relevant DBClassStore

`DBStoreListener[]` `getStoreListeners()`

`

`<T extends DBEntry> Stub<T>`

`

`getStub(Class<T> c, Object id)`
a shortcut w/o having to go through the DBClassStore

`Stub<? extends DBEntry>` `getStub(DBReference ref)` This method will begin and abort a transaction if none is active at the time.
`boolean` `hasAutomatedTransactions()` determines whether the DBClassStoreWrapper instances used by this database use automatic transaction handling.
`boolean` `isEnsureTransactions()`

`

`<E extends DBEntry> boolean`

`

`isVersioningEnabled(Class<E> type, boolean flag)`

`

`<T extends DBEntry> ArrayList<T>`

`

`listEntries(Class<T> c, Filter<? super T> filter)`
This method will begin and abort a transaction if none is active at the time.

`

`<T extends DBEntry> ArrayList<T>`

`

`listEntries(Class<T> type, Filter<? super T> filter, int maxEntries)`

`

`<T extends DBEntry> ArrayList<Stub<T>>`

`

`listStubs(Class<T> c, Filter<? super Stub<?>> filter)`
This method will begin and abort a transaction if none is active at the time.

`void` `loginPerformed(UserLoginStore uls, User user, String location)` called when a user logged into the store
`void` `logoutPerformed(UserLoginStore uls, User user)` called when a user logged out

`

`<T extends DBEntry> Hashtable<Object,T>`

`

`mapEntries(Class<T> c, Filter<? super T> filter)`
returns a Hashtable mapping the ID to its DBEntry of those that apply to the given filter.

`

`<T extends DBEntry> Hashtable<Object,Stub<T>>`

`

`mapStubs(Class<T> c, Filter<? super Stub<?>> filter)`
returns a Hashtable mapping the ID to its Stub of those that apply to the given filter.

`

`<T extends DBEntry> DBClassStore<T>`

`

`putClassStore(Class<T> c, DBClassStore<T> dbcs)`
puts the given dbcs into this database, which is then available in a wrapped Proxy when accessing the class store via interface method `getClassStore(Class)`.

`

`<T> T`

`

`query(Class<T> requiredReturnType, Object context)`
implements the query mechanism based on `queryStoreForInterface(Class, Class)` and also allows to effectively cast to the subclass.

`

`<E extends DBEntry,I> I`

`

`queryStoreForInterface(Class<E> type, Class<I> desiredInterface)`
supports `WrappedDBClassStore` instances for querying the interface from embedded stores

`

`<T extends DBEntry> DBClassStore<T>`

`

`remove(Class<T> c)`

`boolean` `removeConfigListener(DBConfigListener listener)`
`boolean` `removeStoreListener(DBStoreListener listener)`
`void` `setAccessController(DBAccessController controller)`
`void` `setAutomatedTransactions(boolean flag)`
`void` `setCurrentUser(User user)` sets the user credentials for accessing resources
`void` `setEnsureTransactions(boolean flag)`

`

`<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.

`

`<T extends DBEntry> void`

`

`store(T... entries)`
inserts/updates the given entries in the database depending on whether it already exists

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface com.antelmann.db.Database
`getTransaction`

Constructor Detail

### AbstractDatabase

    public AbstractDatabase(S databaseService)

### AbstractDatabase

    public AbstractDatabase(S databaseService,
                            User user)

  sets the current user (may be null)

### AbstractDatabase

    public AbstractDatabase(S databaseService,
                            User user,
                            LogWriter logWriter)

  the given logWriter - assumed to write into the databaseService if not null - will be added to the embedded Logger

### AbstractDatabase

    public AbstractDatabase(S databaseService,
                            User user,
                            DBAccessController controller,
                            LogWriter logWriter)

### AbstractDatabase

    public AbstractDatabase(S databaseService,
                            User user,
                            DBAccessController controller,
                            LogWriter logWriter,
                            boolean automatedTransactions)

Method Detail

### clearAllData

    protected void clearAllData()

  this method clears all stores, listeners, writers and users from this database in preparation for calling `close()`

### fireStoreChanges

    protected void fireStoreChanges()

### finalize

    protected void finalize()
                     throws Throwable

  Overrides:
    `finalize` in class `Object`
  Throws:
    `Throwable`

### getDatabaseService

    public final S getDatabaseService()

  Description copied from interface: `Database`
  provides access to the actual database service that is used by the implementation of this interface

  Specified by:
    `getDatabaseService` in interface `Database<S>`

### hasAutomatedTransactions

    public final boolean hasAutomatedTransactions()

  determines whether the DBClassStoreWrapper instances used by this database use automatic transaction handling.

### setAutomatedTransactions

    public final void setAutomatedTransactions(boolean flag)

### isEnsureTransactions

    public final boolean isEnsureTransactions()

### setEnsureTransactions

    public final void setEnsureTransactions(boolean flag)

### setAccessController

    public void setAccessController(DBAccessController controller)

### getAccessController

    public DBAccessController getAccessController()

### checkAccessRight

    public void checkAccessRight(Object right)
                          throws DBAccessDeniedWarning

  checks whether there is a current user on the database with the given access right and throws an exception if that's not the case

  Throws:
    `DBAccessDeniedWarning`

### getAvailableClassStores

    public Set<Class<? extends DBEntry>> getAvailableClassStores()

  Description copied from interface: `Database`
  returns an unmodifiable view of the existing classes that map to a DBClassStore in this database

  Specified by:
    `getAvailableClassStores` in interface `Database<S>`

### remove

    public <T extends DBEntry> DBClassStore<T> remove(Class<T> c)

### getStore

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

  returns a monitored Proxy of the previously added DBClassStore for c or null

  Specified by:
    `getStore` in interface `Database<S>`
  Returns:
    a persistence service for the given DBEntry class or null if such service doesn't exist

### getOriginalClassStore

    protected <T extends DBEntry> DBClassStore<T> getOriginalClassStore(Class<T> c)

  returns the original class store that was put in here directly (not the proxy/wrapper that ensures listeners are notified and transactional integrity is guaranteed)

### putClassStore

    public <T extends DBEntry> DBClassStore<T> putClassStore(Class<T> c,
                                                             DBClassStore<T> dbcs)

  puts the given dbcs into this database, which is then available in a wrapped Proxy when accessing the class store via interface method `getClassStore(Class)`. The original object put in here can still be accessed by the protected method `getOriginalClassStore(Class)`.

  Returns:
    the wrapped class store associated with the given class previously or null

### mapEntries

    public <T extends DBEntry> Hashtable<Object,T> mapEntries(Class<T> c,
                                                              Filter<? super T> filter)
                                                   throws DatabaseException

  returns a Hashtable mapping the ID to its DBEntry of those that apply to the given filter. This method will begin and abort a transaction if none is active at the time.

  Throws:
    `DatabaseException`

### mapStubs

    public <T extends DBEntry> Hashtable<Object,Stub<T>> mapStubs(Class<T> c,
                                                                  Filter<? super Stub<?>> filter)
                                                       throws DatabaseException

  returns a Hashtable mapping the ID to its Stub of those that apply to the given filter. This method will begin and abort a transaction if none is active at the time.

  Throws:
    `DatabaseException`

### count

    public <T extends DBEntry> int count(Class<T> c,
                                         Filter<? super T> filter)
              throws DatabaseException

  Throws:
    `DatabaseException`

### countStubs

    public <T extends DBEntry> int countStubs(Class<T> c,
                                              Filter<Stub<?>> filter)
                   throws DatabaseException

  Throws:
    `DatabaseException`

### listEntries

    public <T extends DBEntry> ArrayList<T> listEntries(Class<T> type,
                                                        Filter<? super T> filter,
                                                        int maxEntries)
                                             throws DatabaseException

  Throws:
    `DatabaseException`

### listEntries

    public <T extends DBEntry> ArrayList<T> listEntries(Class<T> c,
                                                        Filter<? super T> filter)
                                             throws DatabaseException

  This method will begin and abort a transaction if none is active at the time.

  Throws:
    `DatabaseException`

### listStubs

    public <T extends DBEntry> ArrayList<Stub<T>> listStubs(Class<T> c,
                                                            Filter<? super Stub<?>> filter)
                                                 throws DatabaseException

  This method will begin and abort a transaction if none is active at the time.

  Throws:
    `DatabaseException`

### getEntry

    public <T extends DBEntry> T getEntry(Class<T> c,
                                          Object id)
                               throws DatabaseException

  a shortcut w/o having to go through the DBClassStore

  Throws:
    `DatabaseException`

### getEntry

    public <T extends DBEntry> T getEntry(Stub<T> stub)
                               throws DatabaseException

  This method will begin and abort a transaction if none is active at the time.

  Throws:
    `DatabaseException`

### getStub

    public <T extends DBEntry> Stub<T> getStub(Class<T> c,
                                               Object id)
                                    throws DatabaseException

  a shortcut w/o having to go through the DBClassStore

  Throws:
    `DatabaseException`

### getEntry

    public DBEntry getEntry(DBReference ref)
                     throws DatabaseException

  This method will begin and abort a transaction if none is active at the time.

  Throws:
    `DatabaseException`

### getStub

    public Stub<? extends DBEntry> getStub(DBReference ref)
                                    throws DatabaseException

  This method will begin and abort a transaction if none is active at the time.

  Throws:
    `DatabaseException`

### getStoreForEntry

    public <T extends DBEntry> DBClassStore<T> getStoreForEntry(T entry)

  provides a save cast to obtain the relevant DBClassStore

### store

    public <T extends DBEntry> void store(T... entries)
               throws DatabaseException

  inserts/updates the given entries in the database depending on whether it already exists

  Throws:
    `DatabaseException`

### contains

    public boolean contains(DBReference ref)
                     throws DatabaseException

  Throws:
    `DatabaseException`

### contains

    public <T extends DBEntry> boolean contains(T entry)
                     throws DatabaseException

  Throws:
    `DatabaseException`

### delete

    public <T extends DBEntry> boolean delete(T entry)
                   throws DatabaseException

  Throws:
    `DatabaseException`

### delete

    public boolean delete(DBReference ref)
                   throws DatabaseException

  Throws:
    `DatabaseException`

### delete

    public boolean delete(Stub<?> stub)
                   throws DatabaseException

  Throws:
    `DatabaseException`

### getFirstEntry

    public <T extends DBEntry> T getFirstEntry(Class<T> type,
                                               Filter<? super T> filter)
                                    throws DatabaseException

  Throws:
    `DatabaseException`

### getFirstStub

    public <T extends DBEntry> Stub<T> getFirstStub(Class<T> type,
                                                    Filter<Stub<?>> filter)
                                         throws DatabaseException

  Throws:
    `DatabaseException`

### getCurrentUser

    public User getCurrentUser()

  Description copied from interface: `Database`
  returns the user credentials of the one currently using this database

  Specified by:
    `getCurrentUser` in interface `Database<S>`

### setCurrentUser

    public void setCurrentUser(User user)

  Description copied from interface: `Database`
  sets the user credentials for accessing resources

  Specified by:
    `setCurrentUser` in interface `Database<S>`

### getLogger

    public Logger getLogger()

  a logger that contains the logWriter given in the constructor; it is used to log all databaseService access with the special level 'dbaccess' by default

  Specified by:
    `getLogger` in interface `Database<S>`
  Specified by:
    `getLogger` in interface `LoggerProvider`

### addStoreListener

    public boolean addStoreListener(DBStoreListener listener)

  Specified by:
    `addStoreListener` in interface `Database<S>`

### removeStoreListener

    public boolean removeStoreListener(DBStoreListener listener)

  Specified by:
    `removeStoreListener` in interface `Database<S>`

### getStoreListeners

    public DBStoreListener[] getStoreListeners()

  Specified by:
    `getStoreListeners` in interface `Database<S>`

### addConfigListener

    public boolean addConfigListener(DBConfigListener listener)

  Specified by:
    `addConfigListener` in interface `Database<S>`

### removeConfigListener

    public boolean removeConfigListener(DBConfigListener listener)

  Specified by:
    `removeConfigListener` in interface `Database<S>`

### getConfigListeners

    public DBConfigListener[] getConfigListeners()

  Specified by:
    `getConfigListeners` in interface `Database<S>`

### loginPerformed

    public void loginPerformed(UserLoginStore uls,
                               User user,
                               String location)

  Description copied from interface: `LoginListener`
  called when a user logged into the store

  Specified by:
    `loginPerformed` in interface `LoginListener`

### logoutPerformed

    public void logoutPerformed(UserLoginStore uls,
                                User user)

  Description copied from interface: `LoginListener`
  called when a user logged out

  Specified by:
    `logoutPerformed` in interface `LoginListener`

### failedLogin

    public void failedLogin(UserLoginStore uls,
                            String location,
                            Exception exception)

  Description copied from interface: `LoginListener`
  called when a login was either canceled or failed due to an exception

  Specified by:
    `failedLogin` in interface `LoginListener`
    `location` - denotes where the event occurred
    `exception` - is commonly either a `DatabaseException` or a `FailedLoginException`
  See Also:
    `DatabaseException`, `FailedLoginException`

### checkTransactionActive

    public void checkTransactionActive()
                                throws TransactionException

  test for an active transaction; implies ownership of the transaction

  Throws:
    `TransactionException` - if the transaction is not active

### getRandomStub

    public <T extends DBEntry> Stub<T> getRandomStub(Class<T> type)
                                          throws DatabaseException

  Throws:
    `DatabaseException`

### getRandomEntry

    public <T extends DBEntry> T getRandomEntry(Class<T> type)
                                     throws DatabaseException

  Throws:
    `DatabaseException`

### getRandomEntry

    public <T extends DBEntry> T getRandomEntry(Class<T> type,
                                                Filter<? super T> filter)
                                     throws DatabaseException

  Throws:
    `DatabaseException`

### query

    public <T> T query(Class<T> requiredReturnType,
                       Object context)
            throws IOException,
                   IllegalArgumentException

  implements the query mechanism based on `queryStoreForInterface(Class, Class)` and also allows to effectively cast to the subclass.

  Specified by:
    `query` in interface `QueryMechanism`
  Type Parameters:
    `T` - the required return type
  Parameters:
    `requiredReturnType` - specifies the return type that is needed for this operation; if Object.class is given, any returned object is admissible
    `context` - provides a context parameter for which the desired instance is to be returned. Often (if no other meaningful context is required or applicable), it makes sense to pass a reference to the calling object source; null may also be allowed
  Returns:
    an instance of the required return type that matches the given context; null may be returned if no instance is available for the given context
  Throws:
    `IOException` - if any resource could not be acquired to fulfill the given query
    `IllegalArgumentException` - if either parameter is generally not acceptable by the implementation

### queryStoreForInterface

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

  supports `WrappedDBClassStore` instances for querying the interface from embedded stores

  Specified by:
    `queryStoreForInterface` in interface `Database<S>`
  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:
    `WrappedDBClassStore.exposesInterfaces()`

### extractInterface

    @Warning(value="the returned interface may not be save to be used without proper transactional context")
    public static <E extends DBEntry,I> I extractInterface(DBClassStore<E> store,
                                                                        Class<I> desiredInterface)

  allows to extract an interface from a store only if it is 'exposed'

  Returns:
    the 'raw' store that exposes the given interface or null
  See Also:
    `WrappedDBClassStore.exposesInterfaces()`, `queryStoreForInterface(Class, Class)`, `DBUtils.wrapTransactional(DBTransaction, Object, Class)`

### setVersioningEnabled

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

  Description copied from interface: `Database`
  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.

  Specified by:
    `setVersioningEnabled` in interface `Database<S>`
  See Also:
    `DBVersionedUpdateEvent`

### isVersioningEnabled

    public <E extends DBEntry> boolean isVersioningEnabled(Class<E> type,
                                                           boolean flag)

### close

    public void close()
               throws IOException

  Specified by:
    `close` in interface `Closeable`
  Throws:
    `IOException`

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