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