AbstractCache (sormula)

java.lang.Object
- org.sormula.cache.AbstractCache<R>

Type Parameters:

R - cache row type

All Implemented Interfaces:

Cache<R>

Direct Known Subclasses:

ReadOnlyCache, WritableCache
```
public abstract class AbstractCache<R>
extends java.lang.Object
implements Cache<R>
```
Abstract base class for implementing caches. The class contains two maps of rows keyed by primary key(s) of row. One map contains uncommitted rows that are in cache until the database transaction commits. The other map contains rows that have been cached and retained after the database transaction has been committed.

Since:

3.0

Author:

Jeff Miller

Constructor Summary

Constructors
Constructor and Description

AbstractCache(Table<R> table, Cached cachedAnnotation)
Constructs for a table and annotation.

Constructors
Constructor and Description
`AbstractCache(Table<R> table, Cached cachedAnnotation)` Constructs for a table and annotation.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`begin(Transaction transaction)` Indicates start of database transaction.
`protected void`	`check()` Verifies that cache is ready.
`void`	`commit(Transaction transaction)` Indicates database transaction commit.
`boolean`	`contains(java.lang.Object[] primaryKeys)` Tests if row is in cache.
`void`	`evict(R row)` Removes row from the cache.
`void`	`evictAll()` Removes all rows from the cache.
`Cached`	`getCachedAnnotation()` Gets the annotations used to configure cache.
`R`	`getCommitted(CacheKey primaryKeys)` Gets a row from committed cache.
`protected java.util.Map<CacheKey,R>`	`getCommittedCache()` Gets the map that stores committed rows.
`int`	`getHits()` Gets the number of times that requested row was in cache.
`int`	`getMisses()` Gets the number of times that requested row was not in cache.
`int`	`getPercentHits()` Gets hits as a percentage of total requests.
`FieldExtractor<R>`	`getPrimaryKeyExtractor()` Gets the `FieldExtractor` used to get all primary key values from a row.
`java.lang.Object[]`	`getPrimaryKeyValues(R row)` Gets the primary key values from a row as Object array.
`Table<R>`	`getTable()` Gets table that is cached.
`UncommittedRow<R>`	`getUncommitted(CacheKey primaryKeys)` Gets a row from uncommitted cache.
`protected java.util.Map<CacheKey,UncommittedRow<R>>`	`getUncommittedCache()` Gets the map that stores uncommitted rows.
`void`	`hit()` Increments hit count.
`protected void`	`initCommittedCache()` Initializes committed map with initial capacity of `Cached.size()`.
`protected void`	`initUncommittedCache()` Initializes uncommitted map with initial capacity of 1/2 of `Cached.size()`.
`void`	`log()` Writes information to the log about the cache.
`void`	`miss()` Increments miss count.
`R`	`putCommitted(CacheKey primaryKeys, R row)` Puts a row into committed cache.
`UncommittedRow<R>`	`putUncommitted(UncommittedRow<R> uncommittedRow)` Puts a row into uncommitted cache.
`R`	`removeCommited(CacheKey primaryKeys)` Removes a row from committed cache.
`void`	`rollback(Transaction transaction)` Indicates database transaction rollback.
`protected void`	`setCommittedCache(java.util.Map<CacheKey,R> committedCache)` Sets new committed map.
`protected void`	`setUncommittedCache(java.util.Map<CacheKey,UncommittedRow<R>> uncommittedCache)` Sets new uncommitted map.
`UncommittedRow<R>`	`transition(UncommittedRow<R> currentUncommittedRow, UncommittedRow<R> newUncommittedRow)` Transition uncommitted cache state.

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

Methods inherited from interface org.sormula.cache.Cache
close, delete, deleted, execute, insert, inserted, save, saved, select, selected, update, updated, write

- Constructor Detail
  - AbstractCache
```
public AbstractCache(Table<R> table,
                     Cached cachedAnnotation)
              throws CacheException
```
    Constructs for a table and annotation.
    
    Parameters:
    
    table - cache rows for operations on this table
    
    cachedAnnotation - annotation that defines cache configuration
    
    Throws:
    
    CacheException - if error
- Method Detail
  - begin
```
public void begin(Transaction transaction)
           throws CacheException
```
    Indicates start of database transaction. Usually invoked by Table.begin(Transaction) which is a listener method of TransactionListener. Initializes uncommitted map with initCommittedCache().
    
    Specified by:
    
    begin in interface Cache<R>
    
    Parameters:
    
    transaction - database transaction throws CacheException if error
    
    Throws:
    
    CacheException - if error
  - commit
```
public void commit(Transaction transaction)
            throws CacheException
```
    Indicates database transaction commit. Usually invoked by Table.commit(Transaction) which is a listener method of TransactionListener. If Cached.evictOnTransactionEnd() is false, then updates committed map with UncommittedRow.updateCommitted(Cache) for all rows in uncommitted cache. If Cached.evictOnTransactionEnd() is true, then removes all rows from cache with evictAll().
    
    Specified by:
    
    commit in interface Cache<R>
    
    Parameters:
    
    transaction - database transaction throws CacheException if error
    
    Throws:
    
    CacheException - if error
  - rollback
```
public void rollback(Transaction transaction)
              throws CacheException
```
    Indicates database transaction rollback. Usually invoked by Table.rollback(Transaction) which is a listener method of TransactionListener. Removes all uncommitted rows. If Cached.evictOnTransactionEnd() is true, then removes all committed rows from cache with evictAll().
    
    Specified by:
    
    rollback in interface Cache<R>
    
    Parameters:
    
    transaction - database transaction throws CacheException if error
    
    Throws:
    
    CacheException - if error
  - contains
```
public boolean contains(java.lang.Object[] primaryKeys)
                 throws CacheException
```
    Tests if row is in cache. Returns true if row exists as committed or uncommitted. Note that Cache.select(Object[]) will return null but contains(Object[]) will true for the same primary key(s) if row is an uncommitted delete. Cache.select(Object[]) indicates committed visibility while contains(Object[]) simply indicates if row is known to the cache. This method is used by ScalarSelectOperation.execute() to know if cache is authority for row or if database must be queried to get row.
    
    Specified by:
    
    contains in interface Cache<R>
    
    Parameters:
    
    primaryKeys - primary key(s) for row
    
    Returns:
    
    true if row for primary key(s) exists in cache; false if primary key(s) do not exist in committed or uncommitted map
    
    Throws:
    
    CacheException - if error
  - evict
```
public void evict(R row)
           throws CacheException
```
    Removes row from the cache. Does nothing if cache is not initialized because no transaction is active.
    
    Specified by:
    
    evict in interface Cache<R>
    
    Parameters:
    
    row - row to remove
    
    Throws:
    
    CacheException - never
  - evictAll
```
public void evictAll()
              throws CacheException
```
    Removes all rows from the cache. Does nothing if cache is not initialized because no transaction is active.
    
    Specified by:
    
    evictAll in interface Cache<R>
    
    Throws:
    
    CacheException - never
  - initCommittedCache
```
protected void initCommittedCache()
                           throws CacheException
```
    Initializes committed map with initial capacity of Cached.size(). Subclasses may override to initialize a custom Map.
    
    Throws:
    
    CacheException - if error
  - initUncommittedCache
```
protected void initUncommittedCache()
                             throws CacheException
```
    Initializes uncommitted map with initial capacity of 1/2 of Cached.size(). Subclasses may override to initialize a custom Map.
    
    Throws:
    
    CacheException - if error
  - getTable
```
public Table<R> getTable()
```
    Gets table that is cached.
    
    Returns:
    
    table supplied in constructor
  - getCachedAnnotation
```
public Cached getCachedAnnotation()
```
    Gets the annotations used to configure cache.
    
    Returns:
    
    annotation supplied in constructor
  - getPrimaryKeyExtractor
```
public FieldExtractor<R> getPrimaryKeyExtractor()
```
    Gets the FieldExtractor used to get all primary key values from a row.
    
    Returns:
    
    primary key extractor used by getPrimaryKeyValues(Object)
  - log
```
public void log()
```
    Writes information to the log about the cache.
    
    Specified by:
    
    log in interface Cache<R>
  - getCommittedCache
```
protected java.util.Map<CacheKey,R> getCommittedCache()
```
    Gets the map that stores committed rows. Map is not a copy so modifying map will affect cache.
    
    Returns:
    
    the map of committed rows
  - setCommittedCache
```
protected void setCommittedCache(java.util.Map<CacheKey,R> committedCache)
```
    Sets new committed map. Available for subclasses to change the map implementation.
    
    Parameters:
    
    committedCache - map for storing committed rows
  - getUncommittedCache
```
protected java.util.Map<CacheKey,UncommittedRow<R>> getUncommittedCache()
```
    Gets the map that stores uncommitted rows. Map is not a copy so modifying map will affect cache.
    
    Returns:
    
    the map of uncommitted rows
  - setUncommittedCache
```
protected void setUncommittedCache(java.util.Map<CacheKey,UncommittedRow<R>> uncommittedCache)
```
    Sets new uncommitted map. Available for subclasses to change the map implementation.
    
    Parameters:
    
    uncommittedCache - map for storing uncommitted rows
  - getCommitted
```
public R getCommitted(CacheKey primaryKeys)
```
    Gets a row from committed cache.
    
    Parameters:
    
    primaryKeys - primary key(s) of a row
    
    Returns:
    
    row or null if no row exists in committed cache for key
  - putCommitted
```
public R putCommitted(CacheKey primaryKeys,
                      R row)
```
    Puts a row into committed cache.
    
    Parameters:
    
    primaryKeys - primary key(s) of a row
    
    row - row to put in committed cache
    
    Returns:
    
    previous row if one existed for the key or null if no previous row existed in map
  - removeCommited
```
public R removeCommited(CacheKey primaryKeys)
```
    Removes a row from committed cache.
    
    Parameters:
    
    primaryKeys - primary key(s) of a row
    
    Returns:
    
    row if one existed for the key or null if no row existed in map
  - check
```
protected void check()
              throws CacheException
```
    Verifies that cache is ready.
    
    Throws:
    
    CacheException - if cache is not ready for use
  - getUncommitted
```
public UncommittedRow<R> getUncommitted(CacheKey primaryKeys)
```
    Gets a row from uncommitted cache.
    
    Parameters:
    
    primaryKeys - primary key(s) of a row
    
    Returns:
    
    row or null if no row exists in uncommitted cache for key
  - putUncommitted
```
public UncommittedRow<R> putUncommitted(UncommittedRow<R> uncommittedRow)
```
    Puts a row into uncommitted cache.
    
    Parameters:
    
    uncommittedRow - row to put in uncommitted cache
    
    Returns:
    
    previous row if one existed for the key or null if no previous row existed in map
  - transition
```
public UncommittedRow<R> transition(UncommittedRow<R> currentUncommittedRow,
                                    UncommittedRow<R> newUncommittedRow)
```
    Transition uncommitted cache state.
    
    Parameters:
    
    currentUncommittedRow - current uncommitted row in uncommitted cache
    
    newUncommittedRow - null to remove current uncommitted row; otherwise replace current uncommitted row with new uncommitted row (if they are not the same object)
    
    Returns:
    
    uncommitted row that was replaced or removed; null if uncommitted cache was not changed
  - getPrimaryKeyValues
```
public java.lang.Object[] getPrimaryKeyValues(R row)
                                       throws CacheException
```
    Gets the primary key values from a row as Object array.
    
    Parameters:
    
    row - get value from this row
    
    Returns:
    
    array of primary key values
    
    Throws:
    
    CacheException - if error extracting values
  - getHits
```
public int getHits()
```
    Gets the number of times that requested row was in cache.
    
    Returns:
    
    number of cache hits
  - hit
```
public void hit()
```
    Increments hit count.
  - getMisses
```
public int getMisses()
```
    Gets the number of times that requested row was not in cache.
    
    Returns:
    
    number of cache misses
  - miss
```
public void miss()
```
    Increments miss count.
  - getPercentHits
```
public int getPercentHits()
```
    Gets hits as a percentage of total requests.
    
    Returns:
    
    100 * hits / (hits + misses) rounded to whole percent

Class AbstractCache<R>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.sormula.cache.Cache

Constructor Detail

AbstractCache

Method Detail

begin

commit

rollback

contains

evict

evictAll

initCommittedCache

initUncommittedCache

getTable

getCachedAnnotation

getPrimaryKeyExtractor

log

getCommittedCache

setCommittedCache

getUncommittedCache

setUncommittedCache

getCommitted

putCommitted

removeCommited

check

getUncommitted

putUncommitted

transition

getPrimaryKeyValues

getHits

hit

getMisses

miss

getPercentHits