com.antelmann.db
Class DBUtils

java.lang.Object
  com.antelmann.db.DBUtils

public final class DBUtils
extends Object

provides convenience methods for dealing with database related issues

Author:

Holger Antelmann

Method Summary

static boolean	abort(DBTransaction t) aborts an ongoing transaction if it is active, or simply returns false.
static <T> T	commitCall(Callable<T> call, DBTransaction tx) commits the given task synchronized to the transaction and aborts the transaction in case of an exception
static void	commitEntries(Database<?> db, Iterator<? extends DBEntry> it)
static <T extends DBEntry> T	commitEntry(Database<?> db, T entry) commits the given entry to the database and returns the given entry
static <T extends DBEntry> T	commitEntry(DBClassStore<T> store, T entry) the store is used to update/insert the entry and the transaction is committed.
static void	commitTask(Task<?> task, DBTransaction tx) commits the given task synchronized to the transaction and aborts the transaction in case of an exception
static TableModel	createMappingInfoModel(Database<?> db)
static TableModel	createMappingInfoModel(Database<?> db, Monitor mon)
static <T extends DBEntry> int	delete(Database<?> db, Iterable<? extends DBReference> list) deletes the given entries from the database
static <T extends DBEntry> int	delete(DBClassStore<T> store, Iterable<T> entries) deletes the given entries from the database
static <T extends DBEntry> int	deleteIndividually(DBClassStore<T> store, Filter<? super T> filter) deletes all entries that pass the given filter individually
static void	ensureActive(DBTransaction tx) ensures that the current thread holds a lock on the given transaction and that this transaction is also active
static DBReference	ensureReferenceString(Database<?> db, DBReference ref)
static boolean	exists(Database<?> db, DBReference ref) determines whether there is a relevant store that contains the relevant id for the given reference in the given database
static Set<Class<? extends DBEntry>>	findStoresWithID(Database<?> db, Object id)
static DBEntry	get(Database<?> db, DBReference ref) determines whether there is a relevant store that contains the relevant id for the given reference in the given database.
static <T extends DBEntry> T	getFirstEntry(DBClassStore<T> store, Filter<? super T> filter)
static <T extends DBEntry> Stub<T>	getFirstStub(DBClassStore<T> store, Filter<? super Stub<?>> filter)
static <T extends DBEntry> PatternExtractor<T,Object>	getIDExtractor()
static HashSet<Object>	getIDSet(Collection<? extends DBReference> col)
static <T extends DBEntry> T	getRandomEntry(DBClassStore<T> store, Filter<? super T> filter)
static <T extends DBEntry> Stub<T>	getRandomStub(DBClassStore<T> store)
static <T extends DBEntry> void	handle(DBClassStore<T> store, Handler<? super T,?> handler, Filter<? super T> filter, Monitor monitor, boolean useCommitNotAbort)
static <T extends DBEntry> T	insertEntry(DBClassStore<T> store, T entry) the store is used to insert the entry and the transaction is committed.
static <T extends DBEntry> Iterable<T>	iterate(DBClassStore<T> store, Filter<? super T> filter)
static <T extends DBEntry> ArrayList<T>	listEntries(DBClassStore<T> store, Filter<? super T> filter)
static <T extends DBEntry> ArrayList<T>	listEntries(DBClassStore<T> store, Filter<? super T> filter, int maxEntries)
static DatabaseChangeMonitor	listenWhileVisible(JComponent c, Database<?> db, DatabaseChangeListener listener) uses an AncestorListener on the given component to enable the listener only while it is displayed
static <T extends DBEntry> ArrayList<Stub<T>>	listStubs(DBClassStore<T> store, Filter<? super Stub<?>> filter)
static <T extends DBEntry> ArrayList<Stub<T>>	listStubs(DBClassStore<T> store, Filter<? super Stub<?>> filter, int maxEntries)
static Stub<?>	loadStub(Database<?> db, DBReference ref) reloads a reference as a stub, so that the display value is properly initialized.
static <T extends DBEntry> Hashtable<Object,T>	mapEntries(Collection<T> entries, Filter<? super T> filter)
static <T extends DBEntry> Hashtable<Object,T>	mapEntries(DBClassStore<T> store, Filter<? super T> filter)
static <T extends DBEntry,P> Hashtable<Object,P>	mapEntries(DBClassStore<T> store, PatternExtractor<? super T,P> pe, Filter<? super T> filter)
static <T extends DBEntry> Hashtable<Object,Stub<T>>	mapStubs(Collection<Stub<T>> stubs, Filter<? super Stub<T>> filter)
static <T extends DBEntry> Hashtable<Object,Stub<T>>	mapStubs(DBClassStore<T> store, Filter<? super Stub<?>> filter)
static boolean	referenceRefersToEntry(DBReference ref, DBEntry entry)
static <T> T	runInTransaction(Callable<T> call, DBTransaction t, boolean useCommitNotAbort) the given task is guaranteed to run in an active transaction, where this method only begins a transaction, if the given transaction is not active, yet.
static void	runInTransaction(Task<? extends Exception> task, DBTransaction t, boolean useCommitNotAbort) the given task is guaranteed to run in an active transaction, where this method only begins a transaction, if the given transaction is not active, yet.
static void	store(Database<?> db, DBEntry... entries)
static void	store(Database<?> db, Iterator<? extends DBEntry> i)
static <T extends DBEntry> void	store(DBClassStore<T> store, Collection<T> entries) inserts/updates the given entries in the database depending on whether it already exists
static <T extends DBEntry> void	store(DBClassStore<T> store, Iterator<T> entries) inserts/updates the given entries in the database depending on whether it already exists
static <T extends DBEntry> void	store(DBClassStore<T> store, T entry) inserts/updates the given entry into the database depending on whether it already exists
static DBClassStore<DBEntry>	unsaveStore(DBClassStore<?> store)
static <T extends DBEntry,E extends Exception> void	updateAll(DBClassStore<T> store, Processor<T,E> handler, Filter<? super T> filter)
static <T extends DBEntry,E extends Exception> void	updateAll(DBClassStore<T> store, Processor<T,E> handler, Filter<? super T> filter, Monitor mon)
static <T extends DBEntry> T	updateEntry(DBClassStore<T> store, T entry) the store is used to update the entry and the transaction is committed.
static <T> T	wrapTransactional(DBTransaction tx, T instance, Class<T> transactionalInterface) wraps a given instance into a proxy that calls all methods of the provided interface in a proper transactional context.
static <T> Callable<T>	wrapWithUser(Callable<T> call, DBTransaction t, User user) allows to wrap the given call so that it runs in the context of the given user as the current user for the database
static <E extends Exception> Task<E>	wrapWithUser(Task<E> task, DBTransaction t, User user) allows to wrap the given task so that it runs in the context of the given user as the current user for the database

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getIDExtractor

public static <T extends DBEntry> PatternExtractor<T,Object> getIDExtractor()

wrapTransactional

public static <T> T wrapTransactional(DBTransaction tx,
                                      T instance,
                                      Class<T> transactionalInterface)

wraps a given instance into a proxy that calls all methods of the provided interface in a proper transactional context.

Parameters:

tx - the transaction that all calls should be synchronized with

instance - the object that eventually executes all calls to the proxy

transactionalInterface - the interface that is to be exposed by the returned proxy in a transactionally consistent way

Returns:

a proxy handling all calls to the given interface transactionally consisten

See Also:

TransactionRequired

wrapWithUser

public static <E extends Exception> Task<E> wrapWithUser(Task<E> task,
                                                         DBTransaction t,
                                                         User user)

allows to wrap the given task so that it runs in the context of the given user as the current user for the database

wrapWithUser

public static <T> Callable<T> wrapWithUser(Callable<T> call,
                                           DBTransaction t,
                                           User user)

allows to wrap the given call so that it runs in the context of the given user as the current user for the database

runInTransaction

public static void runInTransaction(Task<? extends Exception> task,
                                    DBTransaction t,
                                    boolean useCommitNotAbort)
                             throws DatabaseException

the given task is guaranteed to run in an active transaction, where this method only begins a transaction, if the given transaction is not active, yet. Only if a transaction had to be begun, this method also ends the transaction by either calling commit or abort - depending on the given boolean parameter. If no transaction was active when entering this method and a DatabaseException is thrown while executing the task, the method will try to abort this transaction and then throw the DatabaseException thrown by the task. Exceptions other than RuntimeExceptions or DatabaseExceptions are wrapped into a DatabaseException to be thrown.

Throws:

DatabaseException

runInTransaction

public static <T> T runInTransaction(Callable<T> call,
                                     DBTransaction t,
                                     boolean useCommitNotAbort)
                          throws DatabaseException

the given task is guaranteed to run in an active transaction, where this method only begins a transaction, if the given transaction is not active, yet. Only if a transaction had to be begun, this method also ends the transaction by either calling commit or abort - depending on the given boolean parameter. If no transaction was active when entering this method and a DatabaseException is thrown while executing the task, the method will try to abort this transaction and then throw the DatabaseException thrown by the task. Exceptions other than RuntimeExceptions or DatabaseExceptions are wrapped into a DatabaseException to be thrown.

Returns:

the result of the task

Throws:

DatabaseException

updateAll

public static <T extends DBEntry,E extends Exception> void updateAll(DBClassStore<T> store,
                                                                     Processor<T,E> handler,
                                                                     Filter<? super T> filter)
                      throws DatabaseException

Throws:

DatabaseException

updateAll

public static <T extends DBEntry,E extends Exception> void updateAll(DBClassStore<T> store,
                                                                     Processor<T,E> handler,
                                                                     Filter<? super T> filter,
                                                                     Monitor mon)
                      throws DatabaseException,
                             CancellationWarning

Throws:

DatabaseException

CancellationWarning

handle

public static <T extends DBEntry> void handle(DBClassStore<T> store,
                                              Handler<? super T,?> handler,
                                              Filter<? super T> filter,
                                              Monitor monitor,
                                              boolean useCommitNotAbort)
                   throws DatabaseException

Throws:

DatabaseException

commitTask

public static void commitTask(Task<?> task,
                              DBTransaction tx)
                       throws DatabaseException

commits the given task synchronized to the transaction and aborts the transaction in case of an exception

Throws:

DatabaseException

commitCall

public static <T> T commitCall(Callable<T> call,
                               DBTransaction tx)
                    throws DatabaseException

commits the given task synchronized to the transaction and aborts the transaction in case of an exception

Throws:

DatabaseException

abort

public static boolean abort(DBTransaction t)

aborts an ongoing transaction if it is active, or simply returns false. Exceptions that may be thrown during abort are ignored; true would be returned. This method is useful to achieve a clean transactional state (being outside a transaction) w/o much hassle. If the associated Database instance happens to be using a Connection as a database service, the underlying Connection is explicitly aborted if no transaction was active (to ensure that all locks are released from direct calls to that connection.

Returns:

whether an active transaction was actually aborted

ensureActive

public static void ensureActive(DBTransaction tx)
                         throws TransactionException

ensures that the current thread holds a lock on the given transaction and that this transaction is also active

Throws:

TransactionException - if any of the two assumption are not met

commitEntry

public static <T extends DBEntry> T commitEntry(Database<?> db,
                                                T entry)
                                     throws DatabaseException

commits the given entry to the database and returns the given entry

Throws:

DatabaseException

commitEntries

public static void commitEntries(Database<?> db,
                                 Iterator<? extends DBEntry> it)
                          throws DatabaseException

Throws:

DatabaseException

exists

public static boolean exists(Database<?> db,
                             DBReference ref)
                      throws DatabaseException

determines whether there is a relevant store that contains the relevant id for the given reference in the given database

Throws:

DatabaseException

get

public static DBEntry get(Database<?> db,
                          DBReference ref)
                   throws DatabaseException

determines whether there is a relevant store that contains the relevant id for the given reference in the given database. May return null if either ref is null, ref is empty or if no store is available for the reference class.

Throws:

DatabaseException

loadStub

public static Stub<?> loadStub(Database<?> db,
                               DBReference ref)
                        throws DatabaseException

reloads a reference as a stub, so that the display value is properly initialized. If the reference is null or empty or it does not exist in the database, null is returned.

Throws:

DatabaseException

findStoresWithID

public static Set<Class<? extends DBEntry>> findStoresWithID(Database<?> db,
                                                             Object id)
                                                      throws DatabaseException

Throws:

DatabaseException

commitEntry

public static <T extends DBEntry> T commitEntry(DBClassStore<T> store,
                                                T entry)
                                     throws DatabaseException

the store is used to update/insert the entry and the transaction is committed. If the method should fail due to a DatabaseException, the transaction is aborted. If the ID of the given entry is not a Serializable, this method will use DBClassStore.insertAsNew(DBEntry) to store the entry and return the entry that has been saved to the database (instead of the given one).

Returns:

the given entry itself or the re-retrieved entry from the database (if the id was non-serializable)

Throws:

DatabaseException

insertEntry

public static <T extends DBEntry> T insertEntry(DBClassStore<T> store,
                                                T entry)
                                     throws DatabaseException

the store is used to insert the entry and the transaction is committed. If the method should fail due to a DatabaseException, the transaction is aborted.

Throws:

DatabaseException

updateEntry

public static <T extends DBEntry> T updateEntry(DBClassStore<T> store,
                                                T entry)
                                     throws DatabaseException

the store is used to update the entry and the transaction is committed. If the method should fail due to a DatabaseException, the transaction is aborted.

Throws:

DatabaseException

referenceRefersToEntry

public static boolean referenceRefersToEntry(DBReference ref,
                                             DBEntry entry)

unsaveStore

public static DBClassStore<DBEntry> unsaveStore(DBClassStore<?> store)

getFirstStub

public static <T extends DBEntry> Stub<T> getFirstStub(DBClassStore<T> store,
                                                       Filter<? super Stub<?>> filter)
                                            throws DatabaseException

Throws:

DatabaseException

listStubs

public static <T extends DBEntry> ArrayList<Stub<T>> listStubs(DBClassStore<T> store,
                                                               Filter<? super Stub<?>> filter)
                                                    throws DatabaseException

Throws:

DatabaseException

listStubs

public static <T extends DBEntry> ArrayList<Stub<T>> listStubs(DBClassStore<T> store,
                                                               Filter<? super Stub<?>> filter,
                                                               int maxEntries)
                                                    throws DatabaseException

Throws:

DatabaseException

getRandomEntry

public static <T extends DBEntry> T getRandomEntry(DBClassStore<T> store,
                                                   Filter<? super T> filter)
                                        throws DatabaseException

Throws:

DatabaseException

getRandomStub

public static <T extends DBEntry> Stub<T> getRandomStub(DBClassStore<T> store)
                                             throws DatabaseException

Throws:

DatabaseException

getFirstEntry

public static <T extends DBEntry> T getFirstEntry(DBClassStore<T> store,
                                                  Filter<? super T> filter)
                                       throws DatabaseException

Throws:

DatabaseException

iterate

public static <T extends DBEntry> Iterable<T> iterate(DBClassStore<T> store,
                                                      Filter<? super T> filter)
                                           throws DatabaseException

Throws:

DatabaseException

listEntries

public static <T extends DBEntry> ArrayList<T> listEntries(DBClassStore<T> store,
                                                           Filter<? super T> filter)
                                                throws DatabaseException

Throws:

DatabaseException

listEntries

public static <T extends DBEntry> ArrayList<T> listEntries(DBClassStore<T> store,
                                                           Filter<? super T> filter,
                                                           int maxEntries)
                                                throws DatabaseException

Throws:

DatabaseException

store

public static void store(Database<?> db,
                         DBEntry... entries)
                  throws DatabaseException

Throws:

DatabaseException

store

public static void store(Database<?> db,
                         Iterator<? extends DBEntry> i)
                  throws DatabaseException

Throws:

DatabaseException

store

public static <T extends DBEntry> void store(DBClassStore<T> store,
                                             T entry)
                  throws DatabaseException

inserts/updates the given entry into the database depending on whether it already exists

Throws:

DatabaseException

store

public static <T extends DBEntry> void store(DBClassStore<T> store,
                                             Collection<T> entries)
                  throws DatabaseException

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

Throws:

DatabaseException

store

public static <T extends DBEntry> void store(DBClassStore<T> store,
                                             Iterator<T> entries)
                  throws DatabaseException

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

Throws:

DatabaseException

delete

public static <T extends DBEntry> int delete(Database<?> db,
                                             Iterable<? extends DBReference> list)
                  throws DatabaseException

deletes the given entries from the database

Returns:

the number of entries that were actually deleted

Throws:

DatabaseException

delete

public static <T extends DBEntry> int delete(DBClassStore<T> store,
                                             Iterable<T> entries)
                  throws DatabaseException

deletes the given entries from the database

Returns:

the number of entries that were actually deleted

Throws:

DatabaseException

deleteIndividually

public static <T extends DBEntry> int deleteIndividually(DBClassStore<T> store,
                                                         Filter<? super T> filter)
                              throws DatabaseException

deletes all entries that pass the given filter individually

Throws:

DatabaseException

getIDSet

public static HashSet<Object> getIDSet(Collection<? extends DBReference> col)

mapStubs

public static <T extends DBEntry> Hashtable<Object,Stub<T>> mapStubs(DBClassStore<T> store,
                                                                     Filter<? super Stub<?>> filter)
                                                          throws DatabaseException

Throws:

DatabaseException

mapEntries

public static <T extends DBEntry> Hashtable<Object,T> mapEntries(DBClassStore<T> store,
                                                                 Filter<? super T> filter)
                                                      throws DatabaseException

Throws:

DatabaseException

mapEntries

public static <T extends DBEntry,P> Hashtable<Object,P> mapEntries(DBClassStore<T> store,
                                                                   PatternExtractor<? super T,P> pe,
                                                                   Filter<? super T> filter)
                                      throws DatabaseException

Throws:

DatabaseException

mapEntries

public static <T extends DBEntry> Hashtable<Object,T> mapEntries(Collection<T> entries,
                                                                 Filter<? super T> filter)

mapStubs

public static <T extends DBEntry> Hashtable<Object,Stub<T>> mapStubs(Collection<Stub<T>> stubs,
                                                                     Filter<? super Stub<T>> filter)

listenWhileVisible

public static DatabaseChangeMonitor listenWhileVisible(JComponent c,
                                                       Database<?> db,
                                                       DatabaseChangeListener listener)

uses an AncestorListener on the given component to enable the listener only while it is displayed

Returns:

the change monitor that is used to accomplish this

ensureReferenceString

public static DBReference ensureReferenceString(Database<?> db,
                                                DBReference ref)
                                         throws DatabaseException

Throws:

DatabaseException

createMappingInfoModel

public static TableModel createMappingInfoModel(Database<?> db)
                                         throws DatabaseException,
                                                OfficeException

Throws:

DatabaseException

OfficeException

createMappingInfoModel

public static TableModel createMappingInfoModel(Database<?> db,
                                                Monitor mon)
                                         throws OfficeException,
                                                DatabaseException

Throws:

OfficeException

DatabaseException