de.ipcon.db.cache

Class BOCache

java.lang.Object

de.ipcon.db.cache.BOCache

All Implemented Interfaces:

DBManEventListenerI, BOCacheI, CacheI, CacheFetcherI, DependencyCalculatorI

public class BOCache
extends java.lang.Object
implements CacheFetcherI, DBManEventListenerI, BOCacheI, DependencyCalculatorI

A concurrent-safe cache for frequently accessed Business Objects (BOIs) retrieved via queries.

This cache utilizes soft references, allowing the garbage collector to reclaim memory when needed, and supports dynamic resizing to adapt to varying loads.

Key features:

• Concurrent access: Safe for use in multithreaded environments.
• Soft references: Cached BOIs can be garbage collected when memory is low.
• Dynamic resizing: Automatically adjusts its size to accommodate the number of cached objects.
• Query-based fetching: Retrieves BOIs using a callback mechanism (`CacheFetcherI`).
• Database event listening: Reacts to database changes to maintain cache consistency (`DBManEventListenerI`).
• Dependency tracking: Calculates and manages dependencies between cached BOs to invalidate outdated entries (`DependencyCalculatorI`).

Recommended use cases:

• Methods that frequently access the same BOs, such as "by..." lookup methods.
• Scenarios where cache updates or dirtying are less critical, e.g., read-only or infrequently changing data.

Potential drawbacks:

• Cache updates based on events might be delayed, leading to temporary inconsistencies, particularly with new BOs.

Avoid using in:

• `getOrCreate()` methods that are not exclusively called on the server-side.

Future enhancements:

• Object count limiting with LRU (Least Recently Used) eviction policy.
• Time-based expiration of cached objects.

Usage in clients:

• Create instances of BOCache directly for managing individual caches.
• Use the static `getCachedInstance` method to potentially share a named cache across application components.

See Also:

CacheFetcherI, DBManEventListenerI, BOCacheI, DependencyCalculatorI

Constructor Summary

Constructors

Constructor and Description
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader) Initializes a new instance of the BOCache class with the provided title, BO class, and cache loader.
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader, CacheFetcherI _fetcher) Initializes a new instance of the BOCache class with advanced configuration options.
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader, CacheFetcherI _fetcher, DependencyCalculatorI _dependencyCalculator)
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader, CacheFetcherI _fetcher, DependencyCalculatorI _dependencyCalculator, java.lang.Class[] _dependentClasses)
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader, CacheFetcherI _fetcher, DependencyCalculatorI _dependencyCalculator, java.lang.Class[] _dependentClasses, CacheKeyCalculatorI _cacheKeyCalculator)
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader, CacheFetcherI _fetcher, DependencyCalculatorI _dependencyCalculator, java.lang.Class[] _dependentClasses, CacheKeyCalculatorI _cacheKeyCalculator, java.util.concurrent.ConcurrentMap map)
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader, java.lang.String _query) Initializes a new instance of the BOCache class with a query for fetching missing BOs and optional dependency calculation.
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader, java.lang.String _query, CacheKeyCalculatorI _cacheKeyCalculator) Initializes a new instance of the BOCache class with a query for fetching missing BOs and a cache key calculator.
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader, java.lang.String _query, CacheKeyCalculatorI _cacheKeyCalculator, java.util.concurrent.ConcurrentMap map)
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader, java.lang.String _query, DependencyCalculatorI _dependencyCalculator)
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader, java.lang.String _query, DependencyCalculatorI _dependencyCalculator, java.lang.Class[] _dependentClasses)
BOCache(java.lang.String _title, java.lang.Class<? extends BOI> _clazz, BOLoaderI _cacheLoader, java.lang.String _query, DependencyCalculatorI _dependencyCalculator, java.lang.Class[] _dependentClasses, java.util.concurrent.ConcurrentMap map)

Method Summary

Modifier and Type	Method and Description
long[]	calculateDependencies(java.lang.Object key, java.lang.Object value) This method calculates for a given object the ids of objects, which can invalidate the cached state.
void	clear()
java.lang.Object	computeIfAbsent(java.lang.Object key, java.util.function.Function computeFunction)
boolean	contains(java.lang.Object key)
java.lang.Object	fetch(java.lang.Object key) Fetches an object corresponding to the given key from the cache or the database using the cache loader.
java.lang.Object	fetch(java.lang.Object key, boolean silent)
java.lang.Object[]	fetchAll(java.lang.Object[] keys) Returns an array of objects fetched from the cache, given an array of keys.
static void	flushCaches()
BOI	get(java.lang.Object key)
BOI[]	get(java.lang.Object[] keys)
BOI[]	get(java.lang.Object[] keys, boolean dontCacheNulls)
BOI[]	get(java.lang.Object[] keys, boolean dontCacheNulls, boolean dontFetch)
BOI	get(java.lang.Object key, boolean dontCacheNulls)
BOI	get(java.lang.Object key, boolean dontCacheNulls, boolean dontFetch)
static BO	getCachedInstance(java.lang.Class<? extends BOI> c, java.lang.String keyAttrName, java.lang.Object key, java.lang.String q, BOLoaderI makeLoadedBy) Retrieves a Business Object (BO) instance from the cache or the database, based on the given parameters.
static BO	getCachedInstance(java.lang.Class<? extends BOI> c, java.lang.String keyAttrName, java.lang.Object key, java.lang.String q, BOLoaderI makeLoadedBy, boolean dontCacheNulls)
static BO	getCachedInstance(java.lang.Class<? extends BOI> c, java.lang.String keyAttrName, java.lang.Object key, java.lang.String q, BOLoaderI makeLoadedBy, boolean dontCacheNulls, java.lang.String cacheName)
static BO	getCachedInstance(java.lang.Class<? extends BOI> c, java.lang.String keyAttrName, java.lang.Object key, java.lang.String q, BOLoaderI makeLoadedBy, boolean dontCacheNulls, java.lang.String cacheName, BOLoaderI fallbackCacheLoader)
BOLoaderI	getCacheLoader() Returns the `BOLoaderI` object used for loading objects into this cache Caution: Use with care, intended for specific scenarios where a different `CacheFetcherI` might need it.
java.lang.Class	getExpectedKeyClass()
static void	initStaticCacheLoader(BOLoaderI bol)
void	processDBManEvent(DBManEvent e) Invoked when a subscribed DBManEvent occurs.
void	put(java.lang.Object key, java.lang.Object value)
void	remove(java.lang.Object key)

Methods inherited from class java.lang.Object

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

Constructor Detail

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader)

Initializes a new instance of the BOCache class with the provided title, BO class, and cache loader.

Parameters:

_title - The title or name of the cache.

_clazz - The `Class` object of the BO that the cache is designed to handle

_cacheLoader - The cache loader to be used for loading BOs into the cache

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader,
               CacheFetcherI _fetcher)

Initializes a new instance of the BOCache class with advanced configuration options.

Parameters:

_title - The title or name of the cache.

_clazz - The `Class` object of the BO that the cache is designed to handle

_cacheLoader - The cache loader to be used for loading BOs into the cache

_fetcher - The cache fetcher providing a callback to fetch missing values

_dependencyCalculator - The dependency calculator to extend the change listener to additional BOs a cached value depends on and invalidate the cached state depending on the calculated dependencies between BOs

_dependentClasses - An array of classes dependent on the BO class, used by the dependency calculator

_cacheKeyCalculator - The cache key calculator to be used for calculating cache keys

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader,
               CacheFetcherI _fetcher,
               DependencyCalculatorI _dependencyCalculator)

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader,
               CacheFetcherI _fetcher,
               DependencyCalculatorI _dependencyCalculator,
               java.lang.Class[] _dependentClasses)

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader,
               CacheFetcherI _fetcher,
               DependencyCalculatorI _dependencyCalculator,
               java.lang.Class[] _dependentClasses,
               CacheKeyCalculatorI _cacheKeyCalculator)

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader,
               CacheFetcherI _fetcher,
               DependencyCalculatorI _dependencyCalculator,
               java.lang.Class[] _dependentClasses,
               CacheKeyCalculatorI _cacheKeyCalculator,
               java.util.concurrent.ConcurrentMap map)

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader,
               java.lang.String _query)

Initializes a new instance of the BOCache class with a query for fetching missing BOs and optional dependency calculation.

Parameters:

_title - The title or name of the cache

_clazz - The `Class` object of the BO that the cache is designed to handle

_cacheLoader - The cache loader to be used for loading BOs into the cache

_query - The query to be used for fetching missing BOs

_dependencyCalculator - The dependency calculator to extend the change listener to additional BOs a cached value depends on and invalidate the cached state depending on the calculated dependencies between BOs

_dependentClasses - An array of classes dependent on the BO class, used by the dependency calculator

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader,
               java.lang.String _query,
               DependencyCalculatorI _dependencyCalculator)

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader,
               java.lang.String _query,
               DependencyCalculatorI _dependencyCalculator,
               java.lang.Class[] _dependentClasses)

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader,
               java.lang.String _query,
               DependencyCalculatorI _dependencyCalculator,
               java.lang.Class[] _dependentClasses,
               java.util.concurrent.ConcurrentMap map)

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader,
               java.lang.String _query,
               CacheKeyCalculatorI _cacheKeyCalculator)

Initializes a new instance of the BOCache class with a query for fetching missing BOs and a cache key calculator.

Parameters:

_title - The title or name of the cache.

_clazz - The `Class` object of the BO that the cache is designed to handle

_cacheLoader - The cache loader to be used for loading BOs into the cache

_query - The query to be used for fetching missing BOs

_cacheKeyCalculator - The cache key calculator to be used for calculating cache keys

BOCache

public BOCache(java.lang.String _title,
               java.lang.Class<? extends BOI> _clazz,
               BOLoaderI _cacheLoader,
               java.lang.String _query,
               CacheKeyCalculatorI _cacheKeyCalculator,
               java.util.concurrent.ConcurrentMap map)

Method Detail

initStaticCacheLoader

public static void initStaticCacheLoader(BOLoaderI bol)

flushCaches

public static void flushCaches()

getCachedInstance

public static BO getCachedInstance(java.lang.Class<? extends BOI> c,
                                   java.lang.String keyAttrName,
                                   java.lang.Object key,
                                   java.lang.String q,
                                   BOLoaderI makeLoadedBy)

Retrieves a Business Object (BO) instance from the cache or the database, based on the given parameters.

This method efficiently fetches a BO instance of the specified class matching the provided "primary key". It first attempts to retrieve the BO from the cache using the specified `cacheName`. If not found in the cache, it falls back to loading the BO from the database using the given query (`q`) and the `cacheLoader` or `fallbackCacheLoader`. The returned BO instance can optionally be associated with a different `BOLoaderI` using `makeLoadedBy`.

Parameters:

c - The `Class` object of the BO to be loaded.

keyAttrName - The name of the "primary key" attribute used to identify the BO in the cache and for cache invalidation.

key - The value of the "primary key" attribute that uniquely identifies the BO instance.

q - The query used to fetch the BO instance from the database if not found in the cache.

makeLoadedBy - (Optional) The `BOLoaderI` to associate with the returned BO instance, overriding the cache loader.

dontCacheNulls - If `true`, null values will not be cached.

cacheName - (Optional) A custom name for the cache to use. If `null`, a default cache name will be derived from the class' simple name and the `keyAttrName`.

fallbackCacheLoader - (Optional) A fallback `BOLoaderI` used when no static cache loader is available. Primarily for special cases like update scripts.

Returns:

An instance of the requested class matching the given key, or `null` if no such object exists.

Throws:

java.lang.IllegalStateException - If no suitable cache loader is found to retrieve the BO.

getCachedInstance

public static BO getCachedInstance(java.lang.Class<? extends BOI> c,
                                   java.lang.String keyAttrName,
                                   java.lang.Object key,
                                   java.lang.String q,
                                   BOLoaderI makeLoadedBy,
                                   boolean dontCacheNulls)

getCachedInstance

public static BO getCachedInstance(java.lang.Class<? extends BOI> c,
                                   java.lang.String keyAttrName,
                                   java.lang.Object key,
                                   java.lang.String q,
                                   BOLoaderI makeLoadedBy,
                                   boolean dontCacheNulls,
                                   java.lang.String cacheName)

getCachedInstance

public static BO getCachedInstance(java.lang.Class<? extends BOI> c,
                                   java.lang.String keyAttrName,
                                   java.lang.Object key,
                                   java.lang.String q,
                                   BOLoaderI makeLoadedBy,
                                   boolean dontCacheNulls,
                                   java.lang.String cacheName,
                                   BOLoaderI fallbackCacheLoader)

processDBManEvent

public void processDBManEvent(DBManEvent e)

Description copied from interface: DBManEventListenerI

Invoked when a subscribed DBManEvent occurs. See DBManBOChangeEvent for events triggered after modification on BOs.

Specified by:

processDBManEvent in interface DBManEventListenerI

getCacheLoader

public BOLoaderI getCacheLoader()

Returns the `BOLoaderI` object used for loading objects into this cache

Caution: Use with care, intended for specific scenarios where a different `CacheFetcherI` might need it.

Returns:

the `BOLoaderI` object used for loading objects into this cache

calculateDependencies

public long[] calculateDependencies(java.lang.Object key,
                                    java.lang.Object value)

Description copied from interface: DependencyCalculatorI

This method calculates for a given object the ids of objects, which can invalidate the cached state. e.g. BO A contains the sum of BO B and BO C. Normal BOChangeEvents only allow looking for explicit changes to A. If this method is implemented and additionally returns the IDs of B and C, then the cache containing A is automatically invalidated, if either B or C changes.

Specified by:

calculateDependencies in interface DependencyCalculatorI

Parameters:

key - The cache key of the object, does not have to be a Long, FIXME is it nullable or nonnull?

value - The currently cached value which might depend on other objects. Nullable

Returns:

an Array of longs, which are the IDs of all objects whose changes have an effect on the cached value of the provided object, nonnull. Should not contain the id of the value-object itself.

getExpectedKeyClass

public java.lang.Class getExpectedKeyClass()

Specified by:

getExpectedKeyClass in interface CacheFetcherI

fetch

public java.lang.Object fetch(java.lang.Object key)

Fetches an object corresponding to the given key from the cache or the database using the cache loader.

This method is synchronized to prevent overloading the server with too many initial cache-filling queries. A different `CacheFetcherI` may be used if one was passed in the constructor.

Specified by:

fetch in interface CacheFetcherI

Parameters:

key - The key corresponding to the object to be fetched

silent - A flag indicating whether to suppress any error messages

Returns:

The object corresponding to the given key, or null if it cannot be fetched.

Throws:

java.lang.IllegalArgumentException - if more than one object for the given key exists

fetch

public java.lang.Object fetch(java.lang.Object key,
                              boolean silent)

fetchAll

public java.lang.Object[] fetchAll(java.lang.Object[] keys)

Returns an array of objects fetched from the cache, given an array of keys. Synchronized to prevent flooding the server with initial cache-filling queries.

Note: This method only works if no query is given, and the keys are interpreted as Ids.

Specified by:

fetchAll in interface CacheFetcherI

Parameters:

keys - an array of keys of the objects to fetch

Returns:

An array of requested objects, in the same order as the keys.

contains

public boolean contains(java.lang.Object key)

Specified by:

contains in interface CacheI

get

public BOI get(java.lang.Object key)

Specified by:

get in interface CacheI

get

public BOI get(java.lang.Object key,
               boolean dontCacheNulls)

Specified by:

get in interface BOCacheI

get

public BOI get(java.lang.Object key,
               boolean dontCacheNulls,
               boolean dontFetch)

Specified by:

get in interface BOCacheI

get

public BOI[] get(java.lang.Object[] keys)

Specified by:

get in interface CacheI

get

public BOI[] get(java.lang.Object[] keys,
                 boolean dontCacheNulls)

Specified by:

get in interface BOCacheI

get

public BOI[] get(java.lang.Object[] keys,
                 boolean dontCacheNulls,
                 boolean dontFetch)

Specified by:

get in interface BOCacheI

put

public void put(java.lang.Object key,
                java.lang.Object value)

Specified by:

put in interface CacheI

remove

public void remove(java.lang.Object key)

Specified by:

remove in interface CacheI

clear

public void clear()

Specified by:

clear in interface CacheI

computeIfAbsent

public java.lang.Object computeIfAbsent(java.lang.Object key,
                                        java.util.function.Function computeFunction)

Specified by:

computeIfAbsent in interface CacheI