Caches

This configures the caches in the runtime

Overview

BoxLang comes bundled with an enterprise caching engine that can be configured with different settings and backend object stores. It is also can give you the ability to register caches that adhere to our BoxCache interface (ICacheProvider) to create an implementation agnostic API. Apart from the core providers we create, we also have several in our + subscriptions and anybody can build custom providers as well.

You can also define per-application caches by defining them in the Application.bx file in your applications.

Default Caches

Every BoxLang runtime comes pre-configured with the following caches that are mandatory for operation:

Cache	Hint
default	The default cache in BoxLang is used for queries, templates, and many more internal usages.
bxSessions	If you activate session management in your web or client applications, user session information will be stored here.
bxRegex	This is where all dynamic regular expressions are compiled and kept.

boxlang.json

"caches": {
	// The configuration for the BoxLang `default` cache.  If empty, we use the defaults
	// See the ortus.boxlang.runtime.config.segments.CacheConfig for all the available settings
	// This is used by query caching, template caching, and other internal caching.
	// You can use the cache() BIF in order to get access to the default cache.
	"default": {
		"provider": "BoxCacheProvider",
		"properties": {
			// How many to evict at a time once a policy is triggered
			"evictCount": 1,
			// The eviction policy to use: Least Recently Used
			// Other policies are: LRU, LFU, FIFO, LIFO, RANDOM
			"evictionPolicy": "LRU",
			// The free memory percentage threshold to trigger eviction
			// 0 = disabled, 1-100 = percentage of available free memory in heap
			// If the threadhold is reached, the eviction policy is triggered
			"freeMemoryPercentageThreshold": 0,
			// The maximum number of objects to store in the cache
			"maxObjects": 1000,
			// The maximum in seconds to keep an object in the cache since it's last access
			// So if an object is not accessed in this time or greater, it will be removed from the cache
			"defaultLastAccessTimeout": 1800,
			// The maximum time in seconds to keep an object in the cache regardless if it's used or not
			// A default timeout of 0 = never expire, careful with this setting
			"defaultTimeout": 3600,
			// The object store to use to store the objects.
			// The default is a ConcurrentStore which is a memory sensitive store
			"objectStore": "ConcurrentStore",
			// The frequency in seconds to check for expired objects and expire them using the policy
			// This creates a BoxLang task that runs every X seconds to check for expired objects
			"reapFrequency": 120,
			// If enabled, the last access timeout will be reset on every access
			// This means that the last access timeout will be reset to the defaultLastAccessTimeout on every access
			// Usually for session caches or to simulate a session
			"resetTimeoutOnAccess": false,
			// If enabled, the last access timeout will be used to evict objects from the cache
			"useLastAccessTimeouts": true
		}
	},
	// This is the holder of all sessions in a BoxLang runtime.
	// The keys are prefixed by application to create separation.
	"bxSessions": {
		"provider": "BoxCacheProvider",
		"properties": {
			// How many objects to evict when the cache is full
			"evictCount": 1,
			// The eviction policy to use: FIFO, LFU, LIFO, LRU, MFU, MRU, Random
			"evictionPolicy": "LRU",
			// The maximum number of objects the cache can hold
			"maxObjects": 100000,
			// How long should sessions last for in seconds. Default is 60 minutes.
			"defaultTimeout": 3600,
			// The object store to use to store the objects.
			// The default is a ConcurrentStore which is a thread safe and fast storage.
			// Available Stores are: BlackHoleStore, ConcurrentSoftReferenceStore, ConcurrentStore, FileSystemStore, Your own.
			"objectStore": "ConcurrentStore",
			// The free memory percentage threshold to start evicting objects
			// Only use if memory is constricted and you need to relieve cache pressure
			// Please note that this only makes sense depending on which object store you use.
			"freeMemoryPercentageThreshold": 0,
			// The frequency in seconds to check for expired objects and expire them using the policy
			// This creates a BoxLang task that runs every X seconds to check for expired objects
			// Default is every 2 minutes
			"reapFrequency": 120,
			// This makes a session extend it's life when accessed.  So if a users uses anything or puts anything
			// In session, it will re-issue the timeout.
			"resetTimeoutOnAccess": true,
			// Sessions don't rely on the last access timeouts but on the default timeout only.
			"useLastAccessTimeouts": false
		}
	},
	// Stores all dynamic regular expressions used in the runtime
	"bxRegex": {
		"provider": "BoxCacheProvider",
		"properties": {
			"evictCount": 1,
			"evictionPolicy": "LRU",
			"freeMemoryPercentageThreshold": 0,
			"maxObjects": 500,
			// 30 minutes ifnot used
			"defaultLastAccessTimeout": 1800,
			// 60 minutes default
			"defaultTimeout": 3600,
			"objectStore": "ConcurrentSoftReferenceStore",
			"reapFrequency": 120,
			"resetTimeoutOnAccess": false,
			"useLastAccessTimeouts": true
		}
	}
},

Here are the available providers for BoxLang. The table shows the status of completion for each provider and its availability for the open-source version of BoxLang, as well as for +/++ subscribers.

Provider	Description	Status	OS	+/++
BoxLang	The enterprise BoxLang native cache provider can leverage many different object stores.	Done
Redis	A Redis single-node provider	Done
RedisCluster	A Redis cluster cache provider	Done
MongoDB	A MongoDB based Provider	In Progress
Couchbase	A Couchbase based provider	In Progress
ElasticSearch	An Elastic Search provider	In Progress
EhCache	An EhCacheProvider	In Progress

You can also find more providers through third-party providers at www.forgebox.io.

Configuration

Every cache must be placed inside the cachesobject with a unique name key. The value of that key contains:

• provider - The name of a core provider or a full classpath to use. Ex: BoxCacheProvider which is the core one, or a module collaborated class or class path class: ortus.boxlang.modules.redis.RedisCache

• properties - An object of configuration for the provider.

"myCache" : {
    "provider" : "BoxCacheProvider",
    "properties" : {}
}

BoxCache Provider

Our BoxCacheProvideris an enterprise-level cache designed to be fast and event-driven. Here are the available configuration options.

Object Stores

Object stores are the foundational storage layer of the BoxLang cache engine. They provide the actual mechanism for storing, retrieving, and managing cached objects. While cache providers coordinate user interactions and act as a service layer, object stores handle the low-level data persistence and retrieval operations.

Type	Description
BlackHoleStore	Mocking store, just simulates a store, nothing is stored.
ConcurrentSoftReferenceStore	Memory-sensitive storage leveraging Java Soft References.
ConcurrentStore	Leverages concurrent hashmaps for storage.
FileSystemStore	Stores the cache items in a serialized fashion on disk
JDBCStore	Distributed cache store backed by JDBC databases for multi-instance cache sharing

Each store can have different configuration properties as well.

Global Properties

Here are the global properties for all object stores.

evictCount

How many objects can be evicted once a policy is triggered? The default is 1.

"evictCount" : 1

evictionPolicy

The eviction policy to use. The available policies are:

• LRU (default): Least Recently Used

• LFU: Least Frequently Used

• FIFO: First in First out

• LIFO: Last in Last Out

• RANDOM: Randomly evict objects

"evictionPolicy" : "Random"

freeMemoryPercentageThreshold

The free memory percentage threshold to trigger eviction 0 = disabled, 1-100 = percentage of available free memory in heap. If the threshold is reached, the eviction policy is triggered. The default is 0.

"freeMemoryPercentageThreshold" : 10

maxObjects

The maximum number of objects to store in the cache. The default is 1000

"maxObjects" : 1000

defaultLastAccessTimeout

The maximum number of seconds an object can be kept in the cache since its last access. If an object is not accessed at this time or greater, it will be removed from the cache. The default is 1800 seconds or 30 minutes.

"defaultLastAccessTimeout" : 1800

defaultTimeout

The maximum time in seconds to keep an object in the cache regardless if it's used or not. A default timeout of 0 = never expire, careful with this setting. The default is 3600 seconds or 60 minutes.

"defaultTimeout" : 3600

objectStore

The object store to use to store the objects. The default is a ConcurrentStore.

"objectStore" : "FileSystemStore"

reapFrequency

The frequency in seconds to check for expired objects and expire them using the policy. This creates a BoxLang task that runs every X seconds to check for expired objects. The default is 120 seconds or 2 minutes.

"reapFrequency" : 240

resetTimeoutOnAccess

If enabled, the last access timeout will be reset on every access for the cache entry. This means that the last access timeout will be reset to the defaultLastAccessTimeout on every access. Usually for session caches or to simulate a session. The default is false.

"resetTimeoutOnAccess" : true

useLastAccessTimeouts

If enabled, the last access timeout will be used to evict objects from the cache. The default is true.

"useLastAccessTimeouts" : true

Object Stores

BoxCache supports multiple object store backends for different caching scenarios. Each store provides different persistence, performance, and distribution characteristics.

For detailed information about each store type, including configuration examples and best practices, see the BoxCache Stores documentation:

• ConcurrentStore - High-performance in-memory caching (default)

• ConcurrentSoftReferenceStore - Memory-sensitive caching with automatic GC support

• FileSystemStore - Disk-based persistent caching

• JDBCStore - Database-backed distributed caching (New in 1.7.0)

• BlackHoleStore - Mock store for testing

Each store page includes:

• Features and capabilities

• Complete configuration examples

• Store-specific properties

• Usage patterns and best practices

• Performance considerations

• When to use each store type