Package ortus.boxlang.runtime.cache.providers

Class BoxCacheProvider

java.lang.Object
ortus.boxlang.runtime.cache.providers.AbstractCacheProvider
ortus.boxlang.runtime.cache.providers.BoxCacheProvider
All Implemented Interfaces:
ICacheProvider
@BoxCache(alias="BoxLang", distributed=false, description="BoxLang\'s native cache provider using an object store.") public class BoxCacheProvider extends AbstractCacheProvider
BoxLang's native cache provider implementation that uses an object store for caching operations. This cache provider supports automatic expiration, reaping, eviction policies, and provides comprehensive caching functionality with performance monitoring and event announcements.

Key Features:

  • Object store-based caching with configurable timeout and last access timeout
  • Automatic reaping of expired entries via scheduled tasks
  • Memory threshold and max objects eviction policies
  • Performance statistics tracking (hits, misses, etc.)
  • Event-driven architecture with cache lifecycle announcements
  • Thread-safe operations with proper synchronization
  • Flexible key filtering and batch operations
  • Metadata reporting for cache monitoring and debugging

Configuration Properties:

  • maxObjects - Maximum number of objects allowed in cache
  • defaultTimeout - Default expiration timeout in seconds
  • defaultLastAccessTimeout - Default last access timeout in seconds
  • reapFrequency - Frequency of reaping operations in seconds
  • useLastAccessTimeouts - Whether to use last access timeouts for eviction

Thread Safety:

This implementation is thread-safe and uses synchronization where necessary, particularly in the configure(), reap(), and getOrSet() methods to ensure data consistency.

Usage Example: 

 // Basic operations
 cache.set( "key", "value", 3600 ); // Store with 1 hour timeout
 Optional<Object> value = cache.get( "key" );
 boolean exists = cache.lookup( "key" );
 cache.clear( "key" );

 // Batch operations
 cache.set( Struct.of( "key1", "value1", "key2", "value2" ) );
 IStruct results = cache.get( "key1", "key2", "key3" );

 // Get-or-set pattern (thread-safe)
 Object value = cache.getOrSet( "expensiveKey", () -> computeExpensiveValue() );
Since:
1.0.0

  • Constructor Details

    • BoxCacheProvider

      public BoxCacheProvider()
      -------------------------------------------------------------------------- Constructor --------------------------------------------------------------------------

  • Method Details

    • configure

      public ICacheProvider configure(CacheService cacheService, CacheConfig config)
      Configure the cache provider for operation
      Specified by:
      configure in interface ICacheProvider
      Overrides:
      configure in class AbstractCacheProvider
      Parameters:
      cacheService - The cache service that is configuring the cache provider
      config - The configuration object
      Returns:
      The cache provider

    • getObjectStore

      public IObjectStore getObjectStore()
      Return the configured object store for this cache provider

    • shutdown

      public void shutdown()
      Shutdown the cache provider

    • getStoreMetadataReport

      public IStruct getStoreMetadataReport(int limit)
      Get a structure of all the keys in the cache with their appropriate metadata structures. This is used to build the reporting for the cache provider Example: 
       {
    "key1": {
          "hits": 0,
          "lastAccessed": 0,
          "lastUpdated": 0,
           ...
   },
  "key2": {
          "hits": 0,
          "lastAccessed": 0,
          "lastUpdated": 0,
          ...
  }
 }
      The getStoreMetadataKeyMap method is used to get the keys that this method returns as metadata in order to build the reports. Careful, this will be a large structure if the cache is large.
      Parameters:
      limit - The limit of keys to return, default is all keys or 0

    • getStoreMetadataReport

      public IStruct getStoreMetadataReport()
      Get the store metadata report with no limit

    • getStoreMetadataKeyMap

      public IStruct getStoreMetadataKeyMap()
      Get a key lookup structure where the BoxCache can build the report on. Ex: { timeout=timeout, lastAccessTimeout=idleTimeout } It is a way for the visualizer to construct the columns correctly on the reports

    • getCachedObjectMetadata

      public IStruct getCachedObjectMetadata(String key)
      Get a cache objects metadata about its performance. This value is a structure of name-value pairs of metadata.
      Parameters:
      key - The key of the object
      Returns:
      The metadata structure or an empty struct if the object is not found

    • reap

      public void reap()
      Reap the cache

    • getSize

      public int getSize()
      Get the size of the cache

    • getSize

      public int getSize(ICacheKeyFilter filter)
      Get the size of the cache

    • clearAll

      public void clearAll()
      Clear all the elements in the cache provider

    • clearAll

      public boolean clearAll(ICacheKeyFilter filter)
      Clear all the elements in the cache provider with a $ICacheKeyFilter predicate. This can be a lambda or method reference since it's a functional interface.
      Parameters:
      filter - The filter that determines which keys to clear

    • clearQuiet

      public boolean clearQuiet(String key)
      Clears an object from the cache provider
      Parameters:
      key - The object key to clear
      Returns:
      True if the object was cleared, false otherwise (if the object was not found in the store)

    • clear

      public boolean clear(String key)
      Clears an object from the cache provider
      Parameters:
      key - The object key to clear
      Returns:
      True if the object was cleared, false otherwise (if the object was not found in the store)

    • clear

      public IStruct clear(String... keys)
      Clears multiple objects from the cache provider
      Parameters:
      keys - The keys to clear
      Returns:
      A struct of keys and their clear status

    • getKeys

      public Array getKeys()
      Get all the keys in the cache provider
      Returns:
      An array of keys in the cache

    • getKeys

      public Array getKeys(ICacheKeyFilter filter)
      Get all the keys in the cache provider using a filter
      Parameters:
      filter - The filter that determines which keys to return
      Returns:
      An array of keys in the cache

    • getKeysStream

      public Stream<String> getKeysStream()
      Get all the keys in the cache provider as a stream
      Returns:
      A stream of keys in the cache

    • getKeysStream

      public Stream<String> getKeysStream(ICacheKeyFilter filter)
      Get all the keys in the cache provider as a stream
      Parameters:
      filter - The filter that determines which keys to return
      Returns:
      A stream of keys in the cache

    • lookupQuiet

      public boolean lookupQuiet(String key)
      Check if an object is in the store with no stats updated or listeners
      Parameters:
      key - The key to lookup in the store
      Returns:
      True if the object is in the store, false otherwise

    • lookup

      public boolean lookup(String key)
      Check if an object is in the store or record a hit or miss in the stats
      Parameters:
      key - The key to lookup in the store
      Returns:
      True if the object is in the store, false otherwise

    • lookup

      public IStruct lookup(String... keys)
      Check if multiple objects are in the store
      Parameters:
      keys - A varargs of keys to lookup in the store
      Returns:
      A struct of keys and their lookup status

    • lookup

      public IStruct lookup(ICacheKeyFilter filter)
      Check if multiple objects are in the store using a filter
      Parameters:
      filter - The filter that determines which keys to return
      Returns:
      A struct of keys and their lookup status

    • getQuiet

      public Attempt<Object> getQuiet(String key)
      Get an object from cache with no metadata tracking
      Parameters:
      key - The key to retrieve
      Returns:
      The cache entry retrieved or null

    • get

      public Attempt<Object> get(String key)
      Get an object from the store with metadata tracking
      Parameters:
      key - The key to retrieve
      Returns:
      The value retrieved or null

    • get

      public IStruct get(String... keys)
      Get multiple objects from the store with metadata tracking
      Parameters:
      keys - The keys to retrieve
      Returns:
      A struct of keys and their cache entries

    • get

      public IStruct get(ICacheKeyFilter filter)
      Get multiple objects from the store with metadata tracking using a filter
      Parameters:
      filter - The filter that determines which keys to return
      Returns:
      A struct of keys and their cache entries

    • setQuiet

      public void setQuiet(Key key, ICacheEntry value)
      Sets an object in the storage with no announcements or eviction checks
      Parameters:
      key - The key to store
      value - The value to store

    • set

      public void set(String key, Object value, Object timeout, Object lastAccessTimeout, IStruct metadata)
      Sets an object in the storage
      Parameters:
      key - The key to store
      value - The value to store
      timeout - The timeout in seconds or a Duration object
      lastAccessTimeout - The last access timeout in seconds or a Duration object
      metadata - The metadata to store

    • set

      public void set(String key, Object value, Object timeout, Object lastAccessTimeout)
      Sets an object in the storage
      Parameters:
      key - The key to store
      value - The value to store
      timeout - The timeout in seconds
      lastAccessTimeout - The last access timeout in seconds

    • set

      public void set(String key, Object value, Object timeout)
      Sets an object in the storage with a default last access timeout
      Parameters:
      key - The key to store
      value - The value to store
      timeout - The timeout in seconds

    • set

      public void set(String key, Object value)
      Sets an object in the storage using the default timeout and last access timeout
      Parameters:
      key - The key to store
      value - The value to store

    • set

      public void set(IStruct entries)
      Set's multiple objects in the storage using all the same default timeout and last access timeouts
      Parameters:
      entries - The keys and cache entries to store

    • set

      public void set(IStruct entries, Object timeout, Object lastAccessTimeout)
      Set's multiple objects in the storage using all the same default timeout and last access timeouts
      Parameters:
      entries - The keys and cache entries to store in the cache
      timeout - The timeout in seconds
      lastAccessTimeout - The last access timeout in seconds

    • getOrSet

      public Object getOrSet(String key, Supplier<Object> provider, Object timeout, Object lastAccessTimeout, IStruct metadata)
      Tries to get an object from the cache, if not found, it will call the lambda to get the value and store it in the cache with the default timeout and last access timeout

      This is a convenience method to avoid the double lookup pattern

      var value = cache.getOrSet( "myKey", () -> { return "myValue"; });

      This is the same as: var value = cache.get( "myKey" ).orElseGet( () -> { var value = "myValue"; cache.set( "myKey", value ); return value; });

      This method is thread safe and will only call the lambda once if the key is not found in the cache

      Parameters:
      key - The key to retrieve
      provider - The lambda to call if the key is not found
      timeout - The timeout in seconds
      lastAccessTimeout - The last access timeout in seconds
      metadata - The metadata to store

    • getOrSet

      public Object getOrSet(String key, Supplier<Object> provider, Object timeout, Object lastAccessTimeout)
      Tries to get an object from the cache, if not found, it will call the lambda to get the value and store it in the cache with the default timeout and last access timeout
      Parameters:
      key - The key to retrieve
      provider - The lambda to call if the key is not found
      timeout - The timeout in seconds
      lastAccessTimeout - The last access timeout in seconds
      Returns:
      The object

    • getOrSet

      public Object getOrSet(String key, Supplier<Object> provider, Object timeout)
      Tries to get an object from the cache, if not found, it will call the lambda to get the value and store it in the cache with the default timeout and last access timeout
      Parameters:
      key - The key to retrieve
      provider - The lambda to call if the key is not found
      timeout - The timeout in seconds
      Returns:
      The object

    • getOrSet

      public Object getOrSet(String key, Supplier<Object> provider)
      Tries to get an object from the cache, if not found, it will call the lambda to get the value and store it in the cache with the default timeout and last access timeout
      Parameters:
      key - The key to retrieve
      provider - The lambda to call if the key is not found
      Returns:
      The object

    • getReapingFuture

      public ScheduledFuture<?> getReapingFuture()
      Get the reaping future

    • getCacheEntry

      public ICacheEntry getCacheEntry(String key)
      Get a raw ICacheEntry from the cache's object store
      Parameters:
      key - The key to retrieve
      Returns:
      The ICacheEntry from the object store or null if not found

    • getCacheEntry

      public ICacheEntry getCacheEntry(Key key)
      Get a raw ICacheEntry from the cache's object store
      Parameters:
      key - The key to retrieve
      Returns:
      The ICacheEntry from the object store or null if not found