org.sormula.annotation.cache

Annotation Type Cached

@Retention(value=RUNTIME)
 @Target(value=TYPE)
public @interface Cached

Annotation for row class, table class, or database class to specify caching. When used on row or table class, then caching is for a single table. When used on database class, all tables in the database will be cached unless overridden by other annotations or SqlOperation.setCached(boolean).

Only rows that are read/written with Sormula operations are cached. JDBC operations are not cached. Batch operations are not cached.

Each instance of a Table object contains a cache for all operations that were performed with that instance of the table. For example, for two instances of Table for the same database table T, there will be two caches for the database table T. To maintain one cache for table T, use Database.getTable(Class) to insure only one instance of Table exists at any one time for the database.

In some cases, it may be desirable to have more than once cache per row class or database table. In those situations, create separate instances of Table with the Table.Table(Database, Class) constructor.

You can use almost any mixture of cached and non cached tables with one exception. A table that has a foreign key constraint must be cached with a WritableCache like ReadWriteCache if the table that it refers to is also cached with a a WritableCache like ReadWriteCache. The reason is that the foreign keys written to database may refer to a row that is in cache (not yet written to database) which will result in a foreign key constraint violation. Therefore tables that are related by foreign key constraints must have compatible caching as follows:

    Cache type for table        Cache type for table 
    referenced by foreign key   with foreign key      Compatible
    -------------------------------------------------------------
    none                        none                  yes
    none                        ReadOnlyCache.class   yes
    none                        ReadWriteCache.class  yes
    ReadOnlyCache.class         none                  yes
    ReadOnlyCache.class         ReadOnlyCache.class   yes
    ReadOnlyCache.class         ReadWriteCache.class  yes
    ReadWriteCache.class        none                  no - possible foreign key constraint violation
    ReadWriteCache.class        ReadOnlyCache.class   no - possible foreign key constraint violation
    ReadWriteCache.class        ReadWriteCache.class  yes
 

Since:

3.0

Author:

Jeff Miller

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
java.lang.Class<? extends DeleteOperation>	delete Operation to use by writable caches when deleting rows from database from cache.
boolean	enabled Allows to be explicitly disabled for selective tables.
boolean	evictOnTransactionEnd Evicts all rows upon transaction commit or rollback.
int	expire Number of seconds that row will remain in cache.
java.lang.Class<? extends InsertOperation>	insert Operation to use by writable caches when inserting rows into database from cache.
java.lang.Class<? extends SaveOperation>	save Operation to use by writable caches when saving rows into database from cache.
int	size Meaning of is dependent upon cache implementation specified with type().
java.lang.Class<? extends Cache>	type Cache implementation.
java.lang.Class<? extends UpdateOperation>	update Operation to use by writable caches when updating rows in database from cache.

Element Detail

enabled

public abstract boolean enabled

Allows to be explicitly disabled for selective tables. Annotate @Cached(enabled=false) for table or row class when caching has been enabled at the database class for all tables. If enabled is false, then no cache will be created for table and SqlOperation.setCached(boolean) will have no effect.

Returns:

true for caching; false for no will be created for table

Default:

true

type

public abstract java.lang.Class<? extends Cache> type

Cache implementation.

Returns:

ReadOnlyCache.class, ReadWriteCache.class, or other implementation of Cache

Default:

org.sormula.cache.readwrite.ReadWriteCache.class

size

public abstract int size

Meaning of is dependent upon cache implementation specified with type(). For ReadOnlyCache and ReadWriteCache, the size is the initial capacity of cache.

Returns:

the cache size constraint

Default:

30

expire

public abstract int expire

Number of seconds that row will remain in cache. Not used by ReadWriteCache and ReadOnlyCache.

Returns:

maximum lifetime in seconds of cached row; 0 for never expire

Default:

0

evictOnTransactionEnd

public abstract boolean evictOnTransactionEnd

Evicts all rows upon transaction commit or rollback. Setting to true means cache will only be used while database transaction is active. Setting to false means that cached rows may be used in multiple transactions.

Returns:

true to remove all rows from cache when transaction completes

Default:

false

insert

public abstract java.lang.Class<? extends InsertOperation> insert

Operation to use by writable caches when inserting rows into database from cache.

Returns:

insert operation class or subclass of insert operation

See Also:

WritableCache, WriteOperations

Default:

org.sormula.operation.InsertOperation.class

update

public abstract java.lang.Class<? extends UpdateOperation> update

Operation to use by writable caches when updating rows in database from cache.

Returns:

update operation class or subclass of update operation

See Also:

WritableCache, WriteOperations

Default:

org.sormula.operation.UpdateOperation.class

delete

public abstract java.lang.Class<? extends DeleteOperation> delete

Operation to use by writable caches when deleting rows from database from cache.

Returns:

delete operation class or subclass of delete operation

See Also:

WritableCache, WriteOperations

Default:

org.sormula.operation.DeleteOperation.class

save

public abstract java.lang.Class<? extends SaveOperation> save

Operation to use by writable caches when saving rows into database from cache. Save operations are used when cache determines it is ambiguous if insert or update is needed.

Returns:

save operation class or subclass of save operation

See Also:

WritableCache, WriteOperations

Default:

org.sormula.operation.SaveOperation.class