Holger's Java API

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

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