Holger's Java API

## com.antelmann.db
Class DBClassStoreCache<T extends DBEntry>

    java.lang.Object
      com.antelmann.db.WrappedDBClassStore<T>
          com.antelmann.db.DBClassStoreCache<T>

All Implemented Interfaces:
  DBClassStore<T>, ProcessedFilterOption<T>, TransactionListener, TransactionRequired, ProcessorHook<T,DatabaseException>, Wrapped<DBClassStore<T>>

    public class DBClassStoreCache<T extends DBEntry>

extends WrappedDBClassStore<T>
implements TransactionListener

a special store that has the ability of caching entries, so that multiple calls to retrieve an entry may be answered through cache hits. This implementation adds itself as a `TransactionListener` to the database, so in order to remove this instance itself from memory, it has to be removed as a listener, which can be done by calling `stopListening()`.

Since:
  24.01.2009, 17:44:09
Author:
  Holger Antelmann

Nested Class Summary
`static class` `DBClassStoreCache.PrefetchedFilter<T>` a special interface supported by the enclosing class store that indicates that only pre-fetched (cached) instances should be returned from a fetch.

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

Nested classes/interfaces inherited from interface com.antelmann.db.DBClassStore
`DBClassStore.DBMethod`

Field Summary

Fields inherited from class com.antelmann.db.WrappedDBClassStore
`store`

Constructor Summary
`DBClassStoreCache(DBClassStore<T> store)`

Method Summary
`boolean` `containsID(Object id)` determines whether the given ID is present in this store.
`int` `deleteEntries(Filter<? super T> filter)` deletes all DBEntry objects that match the given filter; if the filter is null, all resources are deleted.
`boolean` `deleteEntry(Object id)` removes the entry with the given ID from this store in the database.
`DBEnumeration<T>` `fetch(Filter<? super T> filter)` adds support for `DBClassStoreCache.PrefetchedFilter`
`void` `finishTransaction(DBTransaction transaction)` called before the transaction commits (and before `TransactionListener.prepareToCommit(DBTransaction)`), so that the commit at the database level can be prevented by throwing a DatabaseException here.
`int` `getCacheHitCounter()`
`int` `getCacheSize()`
`T` `getEntry(Object id)` returns the DBEntry based on its ID.
`Stub<T>` `getStub(Object id)` returns a Stub representing the resource for the given ID or null.
`void` `insert(T entry)` it is suggested to create the entry with an ID obtained through `generateNewID()` before passing it into this method.
`void` `prepareToCommit(DBTransaction transaction)` called right before the transaction actually commits and after `TransactionListener.finishTransaction(DBTransaction)`.
`void` `resetCacheHitCounter()`
`void` `stopListening()` removes itself as a TransactionListener from the database.
`void` `transactionAborted(DBTransaction transaction)` called after a database transaction was aborted; the transaction is already inactive.
`void` `transactionBegin(DBTransaction transaction)` called upon beginning a transaction (the transaction is already active)
`void` `transactionCommitted(DBTransaction transaction)` called after a successful database commit; the transaction is already inactive.
`void` `update(T entry)` updates the given entry in the database.

Methods inherited from class com.antelmann.db.WrappedDBClassStore

`add, checkReadAccess, checkWriteAccess, deleteEntriesIndividually, exposesInterfaces, fetchStubs, generateNewID, getAccessFilter, getAccessStubFilter, getDatabase, getEntryClass, getFetchProcessor, getPreStoreHandler, getStoreHandler, getStubProcessor, insertAsNew, isApplyFilterProcessingRecursively, isDeleteEntriesIndividually, isEnsureTransactionsOnFetch, isProcessBeforeFiltering, queryForInterface, remove, setAccessFilter, setAccessStubFilter, setApplyFilterProcessingRecursively, setDeleteEntriesIndividually, setEnsureTransactionsOnFetch, setExposesInterfaces, setFetchProcessor, setPreStoreHandler, setProcessBeforeFiltering, setProcessBeforeFiltering, setStoreHandler, setStubProcessor, size, unwrap, wrapFilterForProcessing`

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

Constructor Detail

### DBClassStoreCache

    public DBClassStoreCache(DBClassStore<T> store)
                      throws ClassCastException

Throws:
  `ClassCastException`

Method Detail

### stopListening

    public void stopListening()

  removes itself as a TransactionListener from the database. After calling this method, this store stops to provide transactionally consistent data, so only call this if you are sure to not rely on consistent data anymore or if you stop using this class and want to make it available for garbage collection. Another reason to call this method is to optimize a read-only store for caching, as there is no need for transactional consistency; so the cache doesn't have to be cleaned on every transaction end.

### getCacheSize

    public int getCacheSize()

### getCacheHitCounter

    public int getCacheHitCounter()

### resetCacheHitCounter

    public void resetCacheHitCounter()

### containsID

    public boolean containsID(Object id)
                       throws DatabaseException

  Description copied from interface: `DBClassStore`
  determines whether the given ID is present in this store.

  Specified by:
    `containsID` in interface `DBClassStore<T extends DBEntry>`
  Overrides:
    `containsID` in class `WrappedDBClassStore<T extends DBEntry>`
  Throws:
    `DatabaseException`

### deleteEntries

    public int deleteEntries(Filter<? super T> filter)
                      throws DatabaseException

  Description copied from interface: `DBClassStore`
  deletes all DBEntry objects that match the given filter; if the filter is null, all resources are deleted. Calling this method does not necessarily entail that `DBClassStore.deleteEntry(Object)` is called for each entry passing the filter (although stores may choose to do so)! Consequently, if a store's implementation does not call `DBClassStore.deleteEntry(Object)` on each instance, calling this method may result in changes that are hard to monitor for versioning purposes.

  Specified by:
    `deleteEntries` in interface `DBClassStore<T extends DBEntry>`
  Overrides:
    `deleteEntries` in class `WrappedDBClassStore<T extends DBEntry>`
  Returns:
    the number of objects that were deleted
  Throws:
    `DatabaseException`
  See Also:
    `WrappedDBClassStore.setProcessBeforeFiltering(boolean)`

### deleteEntry

    public boolean deleteEntry(Object id)
                        throws DatabaseException

  Description copied from interface: `DBClassStore`
  removes the entry with the given ID from this store in the database.

  Specified by:
    `deleteEntry` in interface `DBClassStore<T extends DBEntry>`
  Overrides:
    `deleteEntry` in class `WrappedDBClassStore<T extends DBEntry>`
  Returns:
    true only if the DBEntry with the given ID was actually found and deleted.
  Throws:
    `DatabaseException`

### fetch

    public DBEnumeration<T> fetch(Filter<? super T> filter)
                                           throws DatabaseException

  adds support for `DBClassStoreCache.PrefetchedFilter`

  Specified by:
    `fetch` in interface `DBClassStore<T extends DBEntry>`
  Overrides:
    `fetch` in class `WrappedDBClassStore<T extends DBEntry>`
  Parameters:
    `filter` - may be null, in which case all entries from are returned.
  Throws:
    `DatabaseException`
  See Also:
    `DBClassStoreCache.PrefetchedFilter`

### getEntry

    public T getEntry(Object id)
                               throws DatabaseException

  Description copied from interface: `DBClassStore`
  returns the DBEntry based on its ID.

  Specified by:
    `getEntry` in interface `DBClassStore<T extends DBEntry>`
  Overrides:
    `getEntry` in class `WrappedDBClassStore<T extends DBEntry>`
  Parameters:
    `id` - the ID that is retrieved from `Resource.getID()`
  Returns:
    the associated DBEntry or null if the id is unknown
  Throws:
    `DatabaseException`
  See Also:
    `DBEntry.getID()`

### getStub

    public Stub<T> getStub(Object id)
                                    throws DatabaseException

  Description copied from interface: `DBClassStore`
  returns a Stub representing the resource for the given ID or null. This method allows to display the object w/o having to retrieve the full DBEntry.

  Specified by:
    `getStub` in interface `DBClassStore<T extends DBEntry>`
  Overrides:
    `getStub` in class `WrappedDBClassStore<T extends DBEntry>`
  Throws:
    `DatabaseException`

### insert

    public void insert(T entry)
                throws DatabaseException

  Description copied from interface: `DBClassStore`
  it is suggested to create the entry with an ID obtained through `generateNewID()` before passing it into this method. The ID of the entry must not already exist in the database.

  Specified by:
    `insert` in interface `DBClassStore<T extends DBEntry>`
  Overrides:
    `insert` in class `WrappedDBClassStore<T extends DBEntry>`
  Throws:
    `DatabaseException`
  See Also:
    `DBClassStore.generateNewID()`

### update

    public void update(T entry)
                throws DatabaseException

  Description copied from interface: `DBClassStore`
  updates the given entry in the database.

  Specified by:
    `update` in interface `DBClassStore<T extends DBEntry>`
  Overrides:
    `update` in class `WrappedDBClassStore<T extends DBEntry>`
  Throws:
    `DatabaseException` - if the database was not able to perform the update or it the entry didn't exist in the database before calling this method

### finishTransaction

    public void finishTransaction(DBTransaction transaction)
                           throws DatabaseException

  Description copied from interface: `TransactionListener`
  called before the transaction commits (and before `TransactionListener.prepareToCommit(DBTransaction)`), so that the commit at the database level can be prevented by throwing a DatabaseException here. This method can also be used to make some updates on another database or checking on certain data before the transaction is allowed to commit. In other words, this method may effectively veto the commit of a transaction After this call, the transaction is soon either going to be committed or aborted (right after all listeners have been called). As this method runs within the transaction, it is possible to access/update any resources from the database.

  Specified by:
    `finishTransaction` in interface `TransactionListener`
  Throws:
    `DatabaseException`

### prepareToCommit

    public void prepareToCommit(DBTransaction transaction)

  Description copied from interface: `TransactionListener`
  called right before the transaction actually commits and after `TransactionListener.finishTransaction(DBTransaction)`. Any exception thrown is ignored; listeners must not do any lengthy operations here. This may be used for supporting the implementation of a 2-phase-commit.

  Specified by:
    `prepareToCommit` in interface `TransactionListener`
  Parameters:
    `transaction` - the transaction (being still active) that is about to be committed

### transactionAborted

    public void transactionAborted(DBTransaction transaction)

  Description copied from interface: `TransactionListener`
  called after a database transaction was aborted; the transaction is already inactive. Note that you cannot to start a new transaction within the call of this method, since subsequent listeners would not have a chance to react on this transaction end. If the implementation of this method tries to begin a new transaction, a `TransactionException` will be thrown. If you need to access/update resources of this database from this method, start a new thread that opens a new transaction.

  Specified by:
    `transactionAborted` in interface `TransactionListener`

### transactionBegin

    public void transactionBegin(DBTransaction transaction)

  Description copied from interface: `TransactionListener`
  called upon beginning a transaction (the transaction is already active)

  Specified by:
    `transactionBegin` in interface `TransactionListener`

### transactionCommitted

    public void transactionCommitted(DBTransaction transaction)

  Description copied from interface: `TransactionListener`
  called after a successful database commit; the transaction is already inactive. Note that you cannot start a new transaction within the call of this method, since subsequent listeners would not have a chance to react on this transaction end. If the implementation of this method tries to begin a new transaction, a `TransactionException` will be thrown. If you need to access/update resources of this database from this method, start a new thread that opens a new transaction.

  Specified by:
    `transactionCommitted` in interface `TransactionListener`

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