Class MapDBCache

java.lang.Object

se.liu.ida.hefquin.federation.access.impl.cache.CacheLayer<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>,PersistentCacheEntry>

se.liu.ida.hefquin.federation.access.impl.cache.mapdb.MapDBCache

All Implemented Interfaces:

AutoCloseable, Cache<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>>

public class MapDBCache
extends CacheLayer<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>,PersistentCacheEntry>

Persistent cache backed by a MapDB HTreeMap.

This class is thread-safe for concurrent access through its public methods on a single MapDBCache instance. Cache operations are synchronized using a dedicated lock.

Cache entry creation, invalidation, and replacement behavior are delegated to the configured cache policies.

The cache enforces a maximum capacity. If the persisted map contains more entries than allowed when opened, entries are evicted according to the configured replacement policy until the capacity constraint is satisfied.

Caveats:

Thread safety is provided only at the level of this cache instance. If two MapDBCache objects point to the same persisted file, this class does not coordinate:

• replacement policy state
• capacity enforcement
• invalidation/eviction decisions

Field Summary

Fields

Modifier and Type	Field	Description
protected final org.mapdb.DB	db
protected static final int	DEFAULT_CAPACITY
protected static final String	DEFAULT_FILENAME

Fields inherited from class se.liu.ida.hefquin.federation.access.impl.cache.CacheLayer

capacity, entryFactory, invalidationPolicy, lock, map, replacementPolicy

Constructor Summary

Constructors

Constructor	Description
MapDBCache(int capacity, String filename, CachePolicies<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>,PersistentCacheEntry> policies)	Creates a cache with the given capacity and file path.
MapDBCache(int capacity, CachePolicies<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>,PersistentCacheEntry> policies)	Creates a cache with the given capacity and the default file path.
MapDBCache(String filename, CachePolicies<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>,PersistentCacheEntry> policies)	Constructs a new MapDBCache with a custom file path and the default cache capacity.
MapDBCache(CachePolicies<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>,PersistentCacheEntry> policies)	Creates a cache with the default capacity and default file path.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes the underlying MapDB database and releases associated resources.
protected static File	ensureParentDirectoryExists(String filename)	Ensures that the parent directory of the given file path exists.
void	put(PersistentCacheKey key, CompletableFuture<? extends DataRetrievalResponse<?>> value)	Inserts or updates a cache entry once the given future completes successfully.

Methods inherited from class se.liu.ida.hefquin.federation.access.impl.cache.CacheLayer

clear, evict, evict, get, isEmpty

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT_CAPACITY

protected static final int DEFAULT_CAPACITY

See Also:

• Constant Field Values

DEFAULT_FILENAME

protected static final String DEFAULT_FILENAME

See Also:

• Constant Field Values

db

protected final org.mapdb.DB db

Constructor Details

MapDBCache

public MapDBCache(CachePolicies<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>,PersistentCacheEntry> policies)

Creates a cache with the default capacity and default file path.

Parameters:

policies - the cache policies to use

Throws:

IOException - if the cache file cannot be created or opened

MapDBCache

public MapDBCache(int capacity,
 CachePolicies<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>,PersistentCacheEntry> policies)

Creates a cache with the given capacity and the default file path.

Parameters:

capacity - the maximum number of cache entries

policies - the cache policies to use

Throws:

IOException - if the cache file cannot be created or opened

MapDBCache

public MapDBCache(String filename,
 CachePolicies<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>,PersistentCacheEntry> policies)

Constructs a new MapDBCache with a custom file path and the default cache capacity.

Parameters:

filename - the path to the cache file

policies - the cache policies to use

Throws:

IOException - if the cache file cannot be created or opened

MapDBCache

public MapDBCache(int capacity,
 String filename,
 CachePolicies<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>,PersistentCacheEntry> policies)

Creates a cache with the given capacity and file path.

If the persisted map already contains entries, the replacement policy is initialized accordingly and eviction is performed if necessary to satisfy the capacity constraint.

Parameters:

capacity - the maximum number of cache entries

filename - the path to the cache file

policies - the cache policies to use

Throws:

IOException - if the cache file cannot be created or opened

Method Details

ensureParentDirectoryExists

protected static File ensureParentDirectoryExists(String filename)

Ensures that the parent directory of the given file path exists.

Parameters:

filename - the path to the file

Returns:

a File object for the given path

Throws:

IllegalStateException - if the parent directory does not exist and cannot be created

close

public void close()

Closes the underlying MapDB database and releases associated resources.

Prevents new cache writes, waits for all pending asynchronous writes to complete, and then closes the database. Any write failures encountered during shutdown are logged.

After this method returns, the cache must not be used anymore.

put

public void put(PersistentCacheKey key,
 CompletableFuture<? extends DataRetrievalResponse<?>> value)

Inserts or updates a cache entry once the given future completes successfully.

Unlike the implementation in CacheLayer, this method does not insert the entry immediately. The cache entry is created and stored only after value has completed successfully. This ensures that the persistent MapDB cache never attempts to serialize an incomplete CompletableFuture.

If value completes exceptionally, no entry is added or updated in the cache.

Once the future has completed successfully, insertion is delegated to CacheLayer.put(Object, Object), which handles replacement policy, capacity enforcement, and the actual insertion into the backing map. The changes are then committed to the database. Writes are synchronized with shutdown to prevent database access after it has been closed.

Specified by:

put in interface Cache<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>>

Overrides:

put in class CacheLayer<PersistentCacheKey,CompletableFuture<? extends DataRetrievalResponse<?>>,PersistentCacheEntry>

Parameters:

key - cache key, must not be null

value - future containing the object to cache, must not be null

Throws:

IllegalArgumentException - if key or value is null