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