org.sormula.cache.readwrite

Class ReadWriteCache<R>

java.lang.Object

org.sormula.cache.AbstractCache<R>

org.sormula.cache.writable.WritableCache<R>

org.sormula.cache.readwrite.ReadWriteCache<R>

Type Parameters:

R - row type that is cached

All Implemented Interfaces:

Cache<R>

public class ReadWriteCache<R>
extends WritableCache<R>

A cache that retains rows that selected, inserted, updated, and deleted. Rows modified with insert, update, and delete are written to the database when transaction is committed or when WritableCache.write(), Table.flush(), or Database.flush() is invoked. The selected and modified rows are retained in cache for life of Table object or until explicitly flushed with Table.flush(), or Database.flush() or evicted with Cache.evict(Object) or Cache.evictAll().

This is a transaction based cache which means that caching is performed relative to database transaction boundaries of begin, commit, and rollback. Tables that are cached may not read/write unless a transaction is active. Tables that are cached must use Transaction obtained from Database.getTransaction() or must use a subclass of Transaction that is set with Database.setTransaction(Transaction).

Cached rows are stored in maps with primary keys as the map key. Primary keys are defined by Column.primaryKey(), Column.identity(), or Row.primaryKeyFields(). Cache will be searched when selecting by primary key. Non primary key selects will cause cache to write uncommitted rows to database prior to executing query.

Since:

3.0

Author:

Jeff Miller

Constructor Summary

Constructors

Constructor and Description
ReadWriteCache(Table<R> table, Cached cachedAnnotation) Constructs for a table and cache annotation.

Method Summary

Modifier and Type	Method and Description
void	close(SqlOperation<R> sqlOperation) Notification that a SqlOperation for the cached table is about to close.
boolean	delete(R row) Performs an equivalent to SQL delete on cache for row.
void	deleted(R row) Throws IllegalCacheOperationException since writable ReadWriteCache should never be notified of a delete since ReadWriteCache will be deleting from the database.
void	execute(SqlOperation<R> sqlOperation) Prepares cache for use.
boolean	insert(R row) Performs an equivalent to SQL insert on cache for row.
void	inserted(R row) If table does not have an identity column, then throws IllegalCacheOperationException since writable ReadWriteCache should never be notified of an insert of non identity row since ReadWriteCache will be inserting the database.
boolean	save(R row) Performs an equivalent to save operation on cache for row.
void	saved(R row) Throws IllegalCacheOperationException since writable ReadWriteCache should never be notified of an save since ReadWriteCache will be saving to the database.
R	select(java.lang.Object[] primaryKeys) Performs an equivalent to SQL select on cache for a row with primary key(s).
R	selected(R row) Indicates row was selected from database.
boolean	update(R row) Performs an equivalent to SQL update on cache for row.
void	updated(R row) Throws IllegalCacheOperationException since writable ReadWriteCache should never be notified of an update since ReadWriteCache will be updating the database.

Methods inherited from class org.sormula.cache.writable.WritableCache

commit, write

Methods inherited from class org.sormula.cache.AbstractCache

begin, check, contains, evict, evictAll, getCachedAnnotation, getCommitted, getCommittedCache, getHits, getMisses, getPercentHits, getPrimaryKeyExtractor, getPrimaryKeyValues, getTable, getUncommitted, getUncommittedCache, hit, initCommittedCache, initUncommittedCache, log, miss, putCommitted, putUncommitted, removeCommited, rollback, setCommittedCache, setUncommittedCache, transition

Methods inherited from class java.lang.Object

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

Constructor Detail

ReadWriteCache

public ReadWriteCache(Table<R> table,
                      Cached cachedAnnotation)
               throws CacheException

Constructs for a table and cache annotation.

Parameters:

table - cache rows for this table

cachedAnnotation - cache configuration

Throws:

CacheException - if error

Method Detail

execute

public void execute(SqlOperation<R> sqlOperation)
             throws CacheException

Prepares cache for use.

Parameters:

sqlOperation - operation that will use this cache

Throws:

CacheException - if cache has not been initialized (no transaction is active)

close

public void close(SqlOperation<R> sqlOperation)
           throws CacheException

Notification that a SqlOperation for the cached table is about to close.

Parameters:

sqlOperation - operation that will used this cache

Throws:

CacheException - if error

select

public R select(java.lang.Object[] primaryKeys)
         throws CacheException

Performs an equivalent to SQL select on cache for a row with primary key(s). If false is returned, then invoke Cache.selected(Object) when the row is selected from database. If true is returned, then Cache.selected(Object) must not be invoked.

Parameters:

primaryKeys - primary key(s) for one row

Returns:

row for primary key(s) if row exists in cache; null if row is not in cache or row will be deleted for primary key(s)

Throws:

CacheException - if error

insert

public boolean insert(R row)
               throws CacheException

Performs an equivalent to SQL insert on cache for row. If false is returned, then invoke Cache.inserted(Object) when the row is inserted into database. If true is returned, then Cache.inserted(Object) must not be invoked.

Parameters:

row - row to insert

Returns:

true if cache is authority for row (cache will insert row into database); false if cache does not insert row into database (row should be inserted by the operation that invoked this method)

Throws:

CacheException - if error

update

public boolean update(R row)
               throws CacheException

Performs an equivalent to SQL update on cache for row. If false is returned, then invoke Cache.updated(Object) when the row is updated in database. If true is returned, then Cache.updated(Object) must not be invoked.

Parameters:

row - row to update

Returns:

true if cache is authority for row (cache will update row in database); false if cache does not update row in database (row should be updated by the operation that invoked this method)

Throws:

CacheException - if error

save

public boolean save(R row)
             throws CacheException

Performs an equivalent to save operation on cache for row. If false is returned, then invoke Cache.saved(Object) when the row is saved to database. If true is returned, then Cache.saved(Object) must not be invoked.

Parameters:

row - row to save

Returns:

true if cache is authority for row (cache will save row in database); false if cache does not save row in database (row should be saved by the operation that invoked this method)

Throws:

CacheException - if error

delete

public boolean delete(R row)
               throws CacheException

Performs an equivalent to SQL delete on cache for row. If false is returned, then invoke Cache.deleted(Object) when the row is deleted from database. If true is returned, then Cache.deleted(Object) must not be invoked.

Parameters:

row - row to delete

Returns:

true if cache is authority for row (cache will delete row from database); false if cache does not delete row from database (row should be delete by the operation that invoked this method)

Throws:

CacheException - if error

selected

public R selected(R row)
           throws CacheException

Indicates row was selected from database. Always use returned row since it will be consistent with what is stored in cache. Row is added to cache if appropriate.

Parameters:

row - that was selected

Returns:

cached row if row parameter if row already exists in cache; null if row has been deleted

Throws:

CacheException - if error

inserted

public void inserted(R row)
              throws CacheException

If table does not have an identity column, then throws IllegalCacheOperationException since writable ReadWriteCache should never be notified of an insert of non identity row since ReadWriteCache will be inserting the database.

If table has an identity column (Column.identity() was set true on a field), then row is added to cache. Row is not written to database since this method indicates that it has already been written.

Parameters:

row - row that has been inserted

Throws:

IllegalCacheOperationException - if table does not have an identity column

CacheException - if error

updated

public void updated(R row)
             throws CacheException

Throws IllegalCacheOperationException since writable ReadWriteCache should never be notified of an update since ReadWriteCache will be updating the database.

Parameters:

row - ignored

Throws:

IllegalCacheOperationException - if error

CacheException - if error

saved

public void saved(R row)
           throws CacheException

Throws IllegalCacheOperationException since writable ReadWriteCache should never be notified of an save since ReadWriteCache will be saving to the database.

Parameters:

row - ignored

Throws:

IllegalCacheOperationException - if error

CacheException - if error

Since:

3.4

deleted

public void deleted(R row)
             throws CacheException

Throws IllegalCacheOperationException since writable ReadWriteCache should never be notified of a delete since ReadWriteCache will be deleting from the database.

Parameters:

row - ignored

Throws:

IllegalCacheOperationException - if error

CacheException - if error