Cache (sormula)

Type Parameters:

R - class of row to cache

All Known Implementing Classes:

AbstractCache, ReadOnlyCache, ReadWriteCache, WritableCache
```
public interface Cache<R>
```
Interface for a cache implementation. Cache is for one table. Implementations are specified for a table with Cached.type().
Implementations have the option to cache all rows for the table or only subset of rows. The row parameter in the interface methods, allow cache implementations to cache a subset based upon a row's values.
A design goal was to keep this interface as simple as possible and to allow optimal performance with the sormula api. Therefore, only local transactions are supported and there is no attempt to support JTA, nor generic caches like JCache.
Cache implementations require a two parameter constructor of types Table and Cached.

Since:

3.0

Author:

Jeff Miller

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`begin(Transaction transaction)` Notification of database transaction start.
`void`	`close(SqlOperation<R> sqlOperation)` Notification that a `SqlOperation` for the cached table is about to close.
`void`	`commit(Transaction transaction)` Notification of database transaction normal end.
`boolean`	`contains(java.lang.Object[] primaryKeys)` Tests if cache contains a row with the primary key(s).
`boolean`	`delete(R row)` Performs an equivalent to SQL delete on cache for row.
`void`	`deleted(R row)` Indicates that a row was deleted from database.
`void`	`evict(R row)` Removes row from cache.
`void`	`evictAll()` Removes all rows from cache.
`void`	`execute(SqlOperation<R> sqlOperation)` Notification that a `SqlOperation` for the cached table is about to execute.
`boolean`	`insert(R row)` Performs an equivalent to SQL insert on cache for row.
`void`	`inserted(R row)` Indicates that a row was inserted into database.
`void`	`log()` Writes state of cache to log for debugging.
`void`	`rollback(Transaction transaction)` Notification of database transaction abnormal end.
`boolean`	`save(R row)` Performs an equivalent to save operation on cache for row.
`void`	`saved(R row)` Indicates that a row was saved in 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)` Indicates that a row was updated in database.
`void`	`write()` Writes uncommitted changes to database.

- Method Detail
  - begin
```
void begin(Transaction transaction)
    throws CacheException
```
    Notification of database transaction start. Typically invoked by Table.begin(Transaction).
    
    Parameters:
    
    transaction - database transaction
    
    Throws:
    
    CacheException - if error
  - commit
```
void commit(Transaction transaction)
     throws CacheException
```
    Notification of database transaction normal end. Typically invoked by Table.commit(Transaction). Some cache implementations write rows to the database when this method is invoked.
    
    Parameters:
    
    transaction - database transaction
    
    Throws:
    
    CacheException - if error
  - rollback
```
void rollback(Transaction transaction)
       throws CacheException
```
    Notification of database transaction abnormal end. Typically invoked by Table.rollback(Transaction). Typical cache implementations discard uncommitted rows from cache when this method is invoked.
    
    Parameters:
    
    transaction - database transaction
    
    Throws:
    
    CacheException - if error
  - execute
```
void execute(SqlOperation<R> sqlOperation)
      throws CacheException
```
    Notification that a SqlOperation for the cached table is about to execute.
    
    Parameters:
    
    sqlOperation - operation that will use this cache
    
    Throws:
    
    CacheException - if error
  - close
```
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
  - contains
```
boolean contains(java.lang.Object[] primaryKeys)
          throws CacheException
```
    Tests if cache contains a row with the primary key(s). True is returned if cache has knowledge of any kind of row including one that has been deleted. For deleted rows, true is returned meaning that row is in cache but will be deleted when transaction completes.
    
    Parameters:
    
    primaryKeys - primary key(s) for one row
    
    Returns:
    
    true if cache contains a row for the primary key(s); false if not
    
    Throws:
    
    CacheException - if error
  - select
```
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 selected(Object) when the row is selected from database. If true is returned, then 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
```
boolean insert(R row)
        throws CacheException
```
    Performs an equivalent to SQL insert on cache for row. If false is returned, then invoke inserted(Object) when the row is inserted into database. If true is returned, then 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
```
boolean update(R row)
        throws CacheException
```
    Performs an equivalent to SQL update on cache for row. If false is returned, then invoke updated(Object) when the row is updated in database. If true is returned, then 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
```
boolean save(R row)
      throws CacheException
```
    Performs an equivalent to save operation on cache for row. If false is returned, then invoke saved(Object) when the row is saved to database. If true is returned, then 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
    
    Since:
    
    3.4
  - delete
```
boolean delete(R row)
        throws CacheException
```
    Performs an equivalent to SQL delete on cache for row. If false is returned, then invoke deleted(Object) when the row is deleted from database. If true is returned, then 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
```
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
```
void inserted(R row)
       throws CacheException
```
    Indicates that a row was inserted into database. Row is added to cache if appropriate.
    
    Parameters:
    
    row - that was inserted
    
    Throws:
    
    CacheException - if error
  - updated
```
void updated(R row)
      throws CacheException
```
    Indicates that a row was updated in database. Row is added to cache if appropriate.
    
    Parameters:
    
    row - that was updated
    
    Throws:
    
    CacheException - if error
  - saved
```
void saved(R row)
    throws CacheException
```
    Indicates that a row was saved in database. Row is added to cache if appropriate.
    
    Parameters:
    
    row - that was saved
    
    Throws:
    
    CacheException - if error
    
    Since:
    
    3.4
  - deleted
```
void deleted(R row)
      throws CacheException
```
    Indicates that a row was deleted from database. Row is added to cache if appropriate.
    
    Parameters:
    
    row - that was deleted
    
    Throws:
    
    CacheException - if error
  - write
```
void write()
    throws CacheException
```
    Writes uncommitted changes to database.
    
    Throws:
    
    CacheException - if error
  - evict
```
void evict(R row)
    throws CacheException
```
    Removes row from cache. Does not write it to database.
    
    Parameters:
    
    row - row to remove from cache
    
    Throws:
    
    CacheException - if error
  - evictAll
```
void evictAll()
       throws CacheException
```
    Removes all rows from cache. Does not write any rows to database.
    
    Throws:
    
    CacheException - if error
  - log
```
void log()
```
    Writes state of cache to log for debugging.

Interface Cache<R>

Method Summary

Method Detail

begin

commit

rollback

execute

close

contains

select

insert

update

save

delete

selected

inserted

updated

saved

deleted

write

evict

evictAll

log