com.goldencode.p2j.persist

Class FastFindCache

java.lang.Object

com.goldencode.p2j.persist.FastFindCache

public class FastFindCache
extends java.lang.Object

Implementation of FastFind caching algorithm. The internal structures use a triple-cache to store the id-s of the records that should be present in session cache. The first level is keyed by the table unique identifier. The second level is the index id, also guaranteed to be unique (positive for unique indexes and negative for the rest). The last level is keyed by the FQL of the query, the navigation type, and substitution parameters. We need to store the identifier (private key) as the cache value, rather than the DMO instance itself, because:

• DMO instances cannot be shared across contexts;
• we don't want two sources of cached DMO instances.

Temporary tables are handled as context-local. Permanent tables are shared, but only within one database to avoid mix-ups when separate databases use same names for tables. Thus, pointer to a database is required to lookup tables - it is used as a key leading to appropriate cache instance.

The first two levels of cache size are not limited. They are the table and indexes unique ids and are stable, governed by database structure. Only the very last level is an actual LRUCache object whose size will need to be configured based on how many records should be cached for each index of a table. However, since the invalidation of the cache will occur quite often, the value can be kept small.

Cache Invalidation: the cache is individually invalidated for each affected index when a record is updated. On insert and delete operations all indices are invalidated for respective table. On a rollback event all affected tables are invalidated.

Concurrency: The cache access is thread-safe for temporary because the instances are context local. When accessing the permanent table shared instances, all accesses are synchronized since the LRU cache implementation also alter the internal structure. TODO: implement support for Resolvable substitution parameters.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	FastFindCache.Key A special key used for accessing values in cache.
private static class	FastFindCache.L2Key The second level key for Fast Find algorithm.
private static class	FastFindCache.ReverseLookup A reverse cache of record identifiers to values which contain information to enable the quick invalidation of individual, cached results from the primary cache.
private static class	FastFindCache.TenantKey Class denoting a key for the tenantInstances map.

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.Map<java.lang.Long,java.util.Map<java.lang.Integer,Cache<FastFindCache.L2Key,RecordIdentifier<java.lang.String>>>>	cache The internal data, as a triple-level cache: table-uid x index x other-information.
private boolean	isPermanent Differentiate between permanent and temporary tables and caches.
static RecordIdentifier<java.lang.String>	NO_RECORD Constant for representing a negative result (i.e., the lack of result) for a query.
private static java.util.Map<Database,FastFindCache>	permanentInstances The instances for permanent database(s).
private FastFindCache.ReverseLookup	reverseLookup Reverse cache of record identifiers to invalidation info, for queries with non-indexed properties
private static ContextLocal<FastFindCache>	tempTableInstances The context-local instance for the current session for temp-tables.
private static java.util.Map<FastFindCache.TenantKey,FastFindCache>	tenantInstances Map that stored instances of FastFindCache per tenant id + database id.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	FastFindCache(boolean isPermanent) Constructor for internal use.

Method Summary

Modifier and Type	Method and Description
static long	combine(int uid, java.lang.Integer multiplex) Combines the DMO uid and the optional temp-table multiplex value into a single long value.
(package private) static FastFindCache.Key	createKey(RecordBuffer buffer, int indexId, java.lang.String fql, java.util.BitSet properties, int type, java.lang.Object[] values) Creates a cache key.
RecordIdentifier<java.lang.String>	get(FastFindCache.Key k) Query the cache for a value.
private RecordIdentifier<java.lang.String>	getImpl(FastFindCache.Key k) Query the cache for a value.
static FastFindCache	getInstance(boolean temporary, Database database) Obtain the singleton instance, if FastFind mode enabled.
static FastFindCache	getInstance(boolean temporary, Database database, java.lang.String tenantId) Obtain the singleton instance, if FastFind mode enabled.
void	invalidate(java.util.Collection<java.lang.Long> dmoList) Invalidates records from a list of DMOs.
void	invalidate(int dmoUid, java.lang.Integer multiplex) Invalidates all indexes of a table.
void	invalidate(int dmoUid, java.lang.Integer multiplex, java.util.BitSet unique, java.util.BitSet nonUnique) Invalidates the index for a table.
void	invalidate(int dmoUid, java.lang.Integer multiplex, int idxUid) Invalidate a single index of a table.
void	invalidate(java.lang.String dmoName, long id, java.util.BitSet dirtyProps) Invalidate any cached result which matches the given DMO name and primary key, iff dirtyProps intersects with the set of non-indexed properties used in the associated FQL query.
private void	invalidateImpl(java.util.Collection<java.lang.Long> dmoList) Invalidates records from a list of DMOs.
private void	invalidateImpl(int dmoUid, java.lang.Integer multiplex, java.util.BitSet unique, java.util.BitSet nonUnique) Invalidates the index for a table.
private void	invalidateImpl(int dmoUid, java.lang.Integer multiplex, int idxUid) Invalidate a single index of a table.
void	put(FastFindCache.Key k, Record value) Saves a result in cache.
private void	putImpl(FastFindCache.Key k, Record value) Saves a result in cache.
static void	removeCache(java.lang.String tenantId, java.lang.String databaseId) Remove a cache based on a (tenant id, database id) key.

Methods inherited from class java.lang.Object

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

Field Detail

NO_RECORD

public static final RecordIdentifier<java.lang.String> NO_RECORD

Constant for representing a negative result (i.e., the lack of result) for a query.

permanentInstances

private static final java.util.Map<Database,FastFindCache> permanentInstances

The instances for permanent database(s).

tenantInstances

private static final java.util.Map<FastFindCache.TenantKey,FastFindCache> tenantInstances

Map that stored instances of FastFindCache per tenant id + database id.

tempTableInstances

private static final ContextLocal<FastFindCache> tempTableInstances

The context-local instance for the current session for temp-tables.

cache

private final java.util.Map<java.lang.Long,java.util.Map<java.lang.Integer,Cache<FastFindCache.L2Key,RecordIdentifier<java.lang.String>>>> cache

The internal data, as a triple-level cache: table-uid x index x other-information.

reverseLookup

private final FastFindCache.ReverseLookup reverseLookup

Reverse cache of record identifiers to invalidation info, for queries with non-indexed properties

isPermanent

private final boolean isPermanent

Differentiate between permanent and temporary tables and caches.

Constructor Detail

FastFindCache

private FastFindCache(boolean isPermanent)

Constructor for internal use.

Parameters:

isPermanent - Differentiate between permanent and temporary tables and caches.

Method Detail

getInstance

public static FastFindCache getInstance(boolean temporary,
                                        Database database)

Obtain the singleton instance, if FastFind mode enabled. Return null to disable FastFind mode.

Parameters:

temporary - Use true to get the instance object for a temp-table database. They are context-local objects. When false the global instance for permanent databases is returned.

database - The instance of the database to work with.

Returns:

the static instance of FastFindCache, or null if FastFind mode is disabled.

getInstance

public static FastFindCache getInstance(boolean temporary,
                                        Database database,
                                        java.lang.String tenantId)

Obtain the singleton instance, if FastFind mode enabled. In multi-tenancy mode, this function may also return a FastFindCache instance based on the given tenant id and database id. If these are not provided, return the singleton instance instead. Return null to disable FastFind mode.

Parameters:

temporary - Use true to get the instance object for a temp-table database. They are context-local objects. When false the global instance for permanent databases is returned.

database - The instance of the database to work with.

tenantId - The tenant id, if working with a tenant. null can either mean that multi-tenancy is disabled, or that we are using the default context.

Returns:

an instance of FastFindCache, or null if FastFind mode is disabled.

removeCache

public static void removeCache(java.lang.String tenantId,
                               java.lang.String databaseId)

Remove a cache based on a (tenant id, database id) key.

Parameters:

tenantId - The tenant to work with.

databaseId - The database to work with.

combine

public static long combine(int uid,
                           java.lang.Integer multiplex)

Combines the DMO uid and the optional temp-table multiplex value into a single long value.

Parameters:

uid - The DMO uid.

multiplex - The multiplex value of a temp-table. Must be positive. Use 0 or null for permanent tables.

Returns:

a single long value used as level 1 key in cache.

createKey

static FastFindCache.Key createKey(RecordBuffer buffer,
                                   int indexId,
                                   java.lang.String fql,
                                   java.util.BitSet properties,
                                   int type,
                                   java.lang.Object[] values)

Creates a cache key.

If provided, all substitution parameters (values) are checked if they are instances of Resolvable. These are not yet supported so no key is generated if they are encountered.

Parameters:

buffer - The buffer that holds the record. Used for obtaining the DMO uid and multiplex (for temp-tables).

indexId - The id of the index used when executing the query.

fql - The fql of the query which selected the keyed record.

properties - The set of properties used in fql.

type - The type of navigation. Must be one of FIRST, LAST or UNIQUE values of the QueryConstants.

values - The substitution values. May be null.

Returns:

a new Key for the provided parameters or null if not supported.

get

public RecordIdentifier<java.lang.String> get(FastFindCache.Key k)

Query the cache for a value.

Parameters:

k - The key for cache.

Returns:

a RecordIdentifier structure. In the case of a cache-hit, this is the key for a Session cache, and null otherwise.

put

public void put(FastFindCache.Key k,
                Record value)

Saves a result in cache. Supports both real records and also "NOT-FOUND" results, when the second parameter is null.

Parameters:

k - The key for cache.

value - The value to be stored in cache. Only the primary key is important. If null, -1 will be used to mark the result as not present in database.

invalidate

public void invalidate(int dmoUid,
                       java.lang.Integer multiplex,
                       java.util.BitSet unique,
                       java.util.BitSet nonUnique)

Invalidates the index for a table. Called when an operation on the table affected an index.

Parameters:

dmoUid - The unique id of the table.

multiplex - The multiplex of the records to be invalidated, if any.

unique - The set of dirty unique indices which need to be invalidated.

nonUnique - The set of dirty unique indices which need to be invalidated.

invalidate

public void invalidate(java.lang.String dmoName,
                       long id,
                       java.util.BitSet dirtyProps)

Invalidate any cached result which matches the given DMO name and primary key, iff dirtyProps intersects with the set of non-indexed properties used in the associated FQL query.

Parameters:

dmoName - DMO implementation class name of the record that was touched.

id - Primary key of the DMO that was touched.

dirtyProps - The set of properties touched by an update to the DMO.

invalidate

public void invalidate(int dmoUid,
                       java.lang.Integer multiplex)

Invalidates all indexes of a table.

Parameters:

dmoUid - The table uid whose indexes are invalidated.

multiplex - The multiplex of the records to be invalidated if any.

invalidate

public void invalidate(int dmoUid,
                       java.lang.Integer multiplex,
                       int idxUid)

Invalidate a single index of a table.

Parameters:

dmoUid - The table uid whose indexes are invalidated.

multiplex - Multiplex ID for a temp-table (null for a persistent table).

idxUid - Index identifier, unique to its table.

invalidate

public void invalidate(java.util.Collection<java.lang.Long> dmoList)

Invalidates records from a list of DMOs.

Parameters:

dmoList - The collection of unique identifiers of the DMOs to be invalidated.

putImpl

private void putImpl(FastFindCache.Key k,
                     Record value)

Saves a result in cache. Supports both real records and also "NOT-FOUND" results, when the second parameter is null.

Parameters:

k - The key for cache.

value - The value to be stored in cache. Only the primary key is important. If null, -1 will be used to mark the result as not present in database.

getImpl

private RecordIdentifier<java.lang.String> getImpl(FastFindCache.Key k)

Query the cache for a value.

Parameters:

k - The key for cache.

Returns:

a RecordIdentifier structure. In the case of a cache-hit, this is the key for a Session cache, and null otherwise.

invalidateImpl

private void invalidateImpl(int dmoUid,
                            java.lang.Integer multiplex,
                            java.util.BitSet unique,
                            java.util.BitSet nonUnique)

Invalidates the index for a table. Called when an operation on the table affected an index.

Parameters:

dmoUid - The unique id of the table.

multiplex - The multiplex of the records to be invalidated, if any.

unique - The set of dirty unique indices which need to be invalidated.

nonUnique - The set of dirty unique indices which need to be invalidated.

invalidateImpl

private void invalidateImpl(int dmoUid,
                            java.lang.Integer multiplex,
                            int idxUid)

Invalidate a single index of a table.

Parameters:

dmoUid - The table uid whose indexes are invalidated.

multiplex - Multiplex ID for a temp-table (null for a persistent table).

idxUid - Index identifier, unique to its table.

invalidateImpl

private void invalidateImpl(java.util.Collection<java.lang.Long> dmoList)

Invalidates records from a list of DMOs.

Parameters:

dmoList - The collection of unique identifiers of the DMOs to be invalidated.