Use this skill when implementing caching in BoxLang applications: cache providers, cachePut/cacheGet BIFs, output caching, cache regions, distributed caching with Redis or Couchbase, TTL policies, and distributed locking.
BoxLang provides a flexible, pluggable caching system managed by CacheService.
Multiple named cache regions can coexist, each backed by a different provider.
The default in-memory cache is available immediately; Redis, Couchbase, JDBC, and
filesystem caches are available via modules.
boxlang.json{
"caches": {
"default": {
"provider": "BoxCacheProvider",
"properties": {
"maxObjects": 1000,
"defaultTimeout": 60,
"defaultLastAccessTimeout": 30,
"reapFrequency": 5,
"evictionPolicy": "LRU"
}
},
"sessions": {
"provider": "BoxCacheProvider",
"properties": {
"maxObjects": 5000,
"defaultTimeout": 120
}
},
"queries": {
"provider": "jdbc",
"properties": {
"datasource": "mainDB",
"table": "cache_entries"
}
},
"files": {
"provider": "filesystem",
"properties": {
"directory": "/tmp/bxcache"
}
}
}
}
// Store a value (default cache, 60-minute TTL)
cachePut( "user_#userId#", userStruct )
// Store with explicit TTL (timespan)
cachePut( "user_#userId#", userStruct, createTimeSpan( 0, 1, 0, 0 ) ) // 1 hour
// Store with TTL and idle timeout
cachePut(
"user_#userId#",
userStruct,
createTimeSpan( 0, 2, 0, 0 ), // absolute TTL: 2 hours
createTimeSpan( 0, 0, 30, 0 ) // idle timeout: 30 minutes
)
// Retrieve
var user = cacheGet( "user_#userId#" )
if ( isNull( user ) ) {
user = userService.findById( userId )
cachePut( "user_#userId#", user, createTimeSpan( 0, 1, 0, 0 ) )
}
// Check existence without fetching
if ( cacheKeyExists( "user_#userId#" ) ) {
// ...
}
// Remove
cacheRemove( "user_#userId#" )
// Remove multiple
cacheRemove( ["user_1", "user_2", "user_3"] )
// Clear all entries in default cache
cacheClear()
// Use a specific named cache
cachePut( "product_#id#", product, createTimeSpan(0,4,0,0), "", "products" )
var product = cacheGet( "product_#id#", false, "products" )
// Check in named cache
if ( cacheKeyExists( "product_#id#", "products" ) ) { ... }
// Clear a specific cache region
cacheClear( "products" )
// Get cache statistics
var stats = cacheGetStats( "products" )
writeOutput( "Hits: #stats.hits#, Misses: #stats.misses#, Size: #stats.size#" )
// List all cache IDs
var keys = cacheGetAllIds( "products" )
// Reusable cache-aside helper
function cacheOrLoad(
required string key,
required function loader,
any ttl = createTimeSpan(0,1,0,0),
string cacheName = "default"
) {
var cached = cacheGet( arguments.key, false, arguments.cacheName )
if ( !isNull( cached ) ) {
return cached
}
var fresh = arguments.loader()
cachePut( arguments.key, fresh, arguments.ttl, "", arguments.cacheName )
return fresh
}
// Usage
var config = cacheOrLoad(
key = "app_config",
loader = () -> configService.loadFromDB(),
ttl = createTimeSpan(0,0,15,0) // 15 minutes
)
Cache rendered HTML output to avoid re-executing expensive templates:
// Cache entire block output for 10 minutes