Boxlang 1.x Stable Released
BoxLang : A Modern Dynamic JVM Language
LogoLogo
APIDocsDownloadTrySourceSupport
  • Introduction
    • Contributing Guide
    • Release History
      • 1.2.0
      • 1.1.0
      • 1.0.1
      • 1.0.0
      • RC Stage
        • 1.0.0-RC.1
        • 1.0.0-RC.2
        • 1.0.0-RC.3
      • Beta Stage
        • 1.0.0-Beta27
        • 1.0.0-Beta26
        • 1.0.0-Beta25
        • 1.0.0-Beta24
        • 1.0.0-Beta23
        • 1.0.0-Beta22
        • 1.0.0-Beta21
        • 1.0.0-Beta20
        • 1.0.0-Beta19
        • 1.0.0-Beta18
        • 1.0.0-Beta17
        • 1.0.0-Beta16
        • 1.0.0-Beta15
        • 1.0.0-Beta14
        • 1.0.0-Beta13
        • 1.0.0-Beta12
        • 1.0.0-Beta11
        • 1.0.0-Beta10
        • 1.0.0-Beta9
        • 1.0.0-Beta8
        • 1.0.0-Beta7
        • 1.0.0-Beta6
        • 1.0.0-Beta5
        • 1.0.0-Beta 4
        • 1.0.0-Beta3
        • 1.0.0-Beta2
    • About This Book
      • Authors
  • Getting Started
    • Overview
      • Multi-Runtime
      • Instructions & Interpreters
      • CommandBox CLI
      • Quick Syntax Guide
        • Differences From CFML
      • Frequently Asked Questions
      • Running ColdFusion/CFML Apps
        • Migrating from Adobe ColdFusion
        • Migrating From Lucee CFML
    • Installation
      • Modules
    • Running BoxLang
      • AWS Lambda
      • CommandBox
      • Chromebooks
      • CLI Scripting
      • Docker
      • GitHub Actions
      • JSR-223 Scripting
      • MiniServer
      • Try BoxLang!
    • BoxLang Cloud Servers
      • Microsoft Azure
      • Amazon Web Services
    • IDE & Tooling
      • BoxLang Debugger
        • MiniServer Debugging
        • CommandBox Debugging
      • BoxLang Compiler
      • CFML Feature Audit
      • CFML to BoxLang Transpiler
    • Runtime Configuration
      • Directives
      • Caches
      • Datasources
      • Experimental
      • Executors
      • Logging
      • Modules
      • Security
  • BoxLang Language
    • Program Structure
    • Syntax & Semantics
      • Comments
      • Variables
      • Variable Scopes
      • Operators
      • Null & Nothingness
      • Strings
      • Numbers
      • Dates & Times
      • JSON
      • Arrays
      • Structures
      • Queries
      • Datasources
      • Conditionals
      • Attempts
      • Data Navigators
      • Exception Management
      • Code Locking
      • Closures => Context Aware
      • Lambdas -> Pure Functions
      • Includes
      • Threading
    • Classes & O.O.
      • Properties
      • Functions
      • Static Constructs
      • Final Constructs
      • Abstract Constructs
      • Interfaces
    • Reference
      • API Docs
      • Lexical Elements
        • Scopes and Constants
        • Keywords
        • Operators
        • Literals
        • Comments
        • Tokens
        • Semicolons
        • Identifiers
        • Packages and Imports
        • Java Interoperability
        • Errors
      • Types
        • array
        • class
        • datetime
        • file
        • numeric
        • query
        • stream
        • string
        • struct
        • xml
      • Built-in Functions
        • array
          • ArrayAppend
          • ArrayAvg
          • ArrayClear
          • ArrayContains
          • ArrayContainsNoCase
          • ArrayDelete
          • ArrayDeleteAt
          • ArrayDeleteNoCase
          • ArrayEach
          • ArrayEvery
          • ArrayFilter
          • ArrayFind
          • ArrayFindAll
          • ArrayFindAllNoCase
          • ArrayFindNoCase
          • ArrayFirst
          • ArrayGetMetadata
          • ArrayIndexExists
          • ArrayInsertAt
          • ArrayIsDefined
          • ArrayLast
          • ArrayMap
          • ArrayMax
          • ArrayMedian
          • ArrayMerge
          • ArrayMid
          • ArrayMin
          • ArrayNew
          • ArrayPop
          • ArrayPrepend
          • ArrayPush
          • ArrayRange
          • ArrayReduce
          • ArrayReduceRight
          • ArrayResize
          • ArrayReverse
          • ArraySet
          • ArrayShift
          • ArraySlice
          • ArraySome
          • ArraySort
          • ArraySplice
          • ArraySum
          • ArraySwap
          • ArrayToList
          • ArrayToStruct
          • ArrayUnshift
        • async
          • ExecutorGet
          • ExecutorHas
          • ExecutorList
          • ExecutorNew
          • ExecutorShutdown
          • ExecutorStatus
          • FutureNew
          • IsInThread
          • isThreadAlive
          • IsThreadInterrupted
          • RunAsync
          • ThreadInterrupt
          • ThreadJoin
          • ThreadNew
          • ThreadTerminate
        • binary
          • BinaryDecode
          • BinaryEncode
          • BitAnd
          • BitMaskClear
          • BitMaskRead
          • BitMaskSet
          • BitNot
          • BitOr
          • bitShln
          • bitShrn
          • BitXor
        • cache
          • Cache
          • CacheFilter
          • CacheNames
          • CacheProviders
          • CacheService
        • cli
          • CLIClear
          • CLIExit
          • CLIGetArgs
          • CLIRead
        • conversion
          • DataNavigate
          • JSONDeserialize
          • JSONPrettify
          • JSONSerialize
          • LSParseNumber
          • ParseNumber
          • ToBase64
          • ToBinary
          • ToModifiable
          • ToNumeric
          • ToScript
          • ToString
          • ToUnmodifiable
        • decision
          • ArrayIsEmpty
          • arrayIsEmpty
          • Attempt
          • IsArray
          • IsBinary
          • IsBoolean
          • IsClosure
          • IsCustomFunction
          • IsDate
          • IsDateObject
          • IsDebugMode
          • IsDefined
          • IsEmpty
          • IsFileObject
          • IsIPv6
          • IsJSON
          • IsLeapYear
          • IsLocalHost
          • IsNull
          • IsNumeric
          • IsNumericDate
          • IsObject
          • IsQuery
          • IsSimpleValue
          • IsStruct
          • IsValid
          • IsXML
          • IsXmlAttribute
          • IsXMLDoc
          • IsXMLElem
          • IsXMLNode
          • IsXMLRoot
          • LSIsNumeric
          • structIsEmpty
        • encryption
          • Decrypt
          • DecryptBinary
          • Encrypt
          • EncryptBinary
          • GeneratePBKDFKey
          • GenerateSecretKey
          • Hash
          • Hash40
          • Hmac
        • format
          • BooleanFormat
          • DecimalFormat
          • LSNumberFormat
          • NumberFormat
        • i18n
          • ClearLocale
          • CurrencyFormat
          • GetLocale
          • GetLocaleDisplayName
          • GetLocaleInfo
          • IsCurrency
          • LSCurrencyFormat
          • LSIsCurrency
          • LSParseCurrency
          • ParseCurrency
          • SetLocale
        • io
          • ContractPath
          • CreateTempDirectory
          • CreateTempFile
          • DirectoryCopy
          • DirectoryCreate
          • DirectoryDelete
          • DirectoryExists
          • DirectoryList
          • DirectoryMove
          • DirectoryRename
          • ExpandPath
          • FileAppend
          • FileClose
          • FileCopy
          • FileDelete
          • FileExists
          • FileGetMimeType
          • FileInfo
          • FileIsEOF
          • FileMove
          • FileOpen
          • FileRead
          • FileReadBinary
          • FileReadLine
          • FileSeek
          • FileSetAccessMode
          • FileSetAttribute
          • FileSetLastModified
          • FileSkipBytes
          • FileWrite
          • FileWriteLine
          • GetCanonicalPath
          • GetDirectoryFromPath
          • GetFileInfo
          • getTempFile
        • java
          • CreateDynamicProxy
        • jdbc
          • IsInTransaction
          • IsWithinTransaction
          • PreserveSingleQuotes
          • QueryExecute
          • TransactionCommit
          • TransactionRollback
          • TransactionSetSavepoint
        • list
          • GetToken
          • ListAppend
          • ListAvg
          • ListChangeDelims
          • ListCompact
          • ListContains
          • ListContainsNoCase
          • ListDeleteAt
          • ListEach
          • ListEvery
          • ListFilter
          • ListFind
          • ListFindNoCase
          • ListFirst
          • ListGetAt
          • ListIndexExists
          • ListInsertAt
          • ListItemTrim
          • ListLast
          • ListLen
          • ListMap
          • ListPrepend
          • ListQualify
          • ListReduceRight
          • ListRemoveDuplicates
          • ListRest
          • ListSetAt
          • ListSome
          • ListSort
          • ListToArray
          • ListTrim
          • ListValueCount
          • ListValueCountNoCase
        • math
          • Abs
          • Acos
          • Asin
          • Atn
          • Ceiling
          • Cos
          • DecrementValue
          • Exp
          • Fix
          • Floor
          • FormatBaseN
          • IncrementValue
          • InputBaseN
          • Int
          • Log
          • Log10
          • Max
          • Min
          • Pi
          • PrecisionEvaluate
          • Rand
          • Randomize
          • RandRange
          • Round
          • Sgn
          • Sin
          • Sqr
          • Tan
        • query
          • QueryAddColumn
          • QueryAddRow
          • QueryAppend
          • QueryClear
          • QueryColumnArray
          • QueryColumnCount
          • QueryColumnData
          • QueryColumnExists
          • QueryColumnList
          • QueryCurrentRow
          • QueryDeleteColumn
          • QueryDeleteRow
          • QueryEach
          • QueryEvery
          • QueryFilter
          • QueryGetCell
          • QueryGetResult
          • QueryInsertAt
          • QueryKeyExists
          • QueryMap
          • QueryNew
          • QueryPrepend
          • QueryRecordCount
          • QueryReduce
          • QueryRegisterFunction
          • QueryReverse
          • QueryRowData
          • QueryRowSwap
          • QuerySetCell
          • QuerySetRow
          • QuerySlice
          • QuerySome
          • QuerySort
        • runtime
          • BoxLangBIFProxy
        • scheduler
          • SchedulerGet
          • SchedulerGetAll
          • SchedulerList
          • SchedulerRestart
          • SchedulerShutdown
          • SchedulerStart
          • SchedulerStats
        • string
          • Ascii
          • CamelCase
          • Char
          • CharsetDecode
          • CharsetEncode
          • Compare
          • CompareNoCase
          • Find
          • FindNoCase
          • FindOneOf
          • Insert
          • JSStringFormat
          • KebabCase
          • LCase
          • Left
          • ListReduce
          • LJustify
          • LTrim
          • Mid
          • ParagraphFormat
          • PascalCase
          • QueryStringToStruct
          • ReEscape
          • ReFind
          • reFindNoCase
          • ReMatch
          • reMatchNoCase
          • RemoveChars
          • RepeatString
          • Replace
          • ReplaceList
          • ReplaceListNoCase
          • ReplaceNoCase
          • ReReplace
          • reReplaceNoCase
          • Reverse
          • Right
          • RJustify
          • RTrim
          • Slugify
          • SnakeCase
          • SpanExcluding
          • SpanIncluding
          • SQLPrettify
          • StringBind
          • StringEach
          • StringEvery
          • StringFilter
          • StringMap
          • StringReduce
          • StringReduceRight
          • StringSome
          • StringSort
          • StripCR
          • Trim
          • TrueFalseFormat
          • UCase
          • UCFirst
          • Val
          • Wrap
          • YesNoFormat
        • struct
          • StructAppend
          • StructClear
          • StructCopy
          • StructDelete
          • StructEach
          • StructEquals
          • StructEvery
          • StructFilter
          • StructFind
          • StructFindKey
          • StructFindValue
          • StructGet
          • StructGetMetadata
          • StructInsert
          • StructIsCaseSensitive
          • StructIsOrdered
          • StructKeyArray
          • StructKeyExists
          • StructKeyList
          • StructKeyTranslate
          • StructMap
          • StructNew
          • StructReduce
          • StructSome
          • StructSort
          • StructToQueryString
          • StructToSorted
          • StructUpdate
          • StructValueArray
        • system
          • ApplicationRestart
          • ApplicationStartTime
          • ApplicationStop
          • BoxAnnounce
          • BoxAnnounceAsync
          • BoxModuleReload
          • BoxRegisterInterceptionPoints
          • BoxRegisterInterceptor
          • BoxRegisterRequestInterceptor
          • BoxUnregisterInterceptor
          • BoxUnregisterRequestInterceptor
          • CallStackGet
          • CreateGUID
          • CreateObject
          • CreateUUID
          • DE
          • DebugBoxContexts
          • Dump
          • Duplicate
          • echo
          • EncodeForHTML
          • GetApplicationMetadata
          • GetBaseTagData
          • GetBaseTagList
          • GetBaseTemplatePath
          • GetBoxContext
          • GetBoxRuntime
          • GetBoxVersionInfo
          • GetClassMetadata
          • GetComponentList
          • GetContextRoot
          • GetCurrentTemplatePath
          • GetFileFromPath
          • GetFunctionCalledName
          • GetFunctionList
          • GetModuleInfo
          • GetModuleList
          • GetRequestClassLoader
          • GetSemver
          • GetSystemSetting
          • GetTempDirectory
          • GetTickCount
          • htmlEditFormat
          • IIF
          • Invoke
          • IsInstanceOf
          • JavaCast
          • ObjectDeserialize
          • ObjectSerialize
          • PagePoolClear
          • Print
          • Println
          • RunThreadInContext
          • SessionInvalidate
          • SessionRotate
          • SessionStartTime
          • Sleep
          • SystemCacheClear
          • SystemExecute
          • SystemOutput
          • Throw
          • Trace
          • URLDecode
          • URLEncodedFormat
          • writeDump
          • WriteLog
          • WriteOutput
        • temporal
          • ClearTimezone
          • CreateDate
          • CreateDateTime
          • CreateODBCDate
          • CreateODBCDateTime
          • CreateODBCTime
          • CreateTime
          • CreateTimeSpan
          • DateAdd
          • DateCompare
          • DateConvert
          • DateDiff
          • DateFormat
          • DatePart
          • DateTimeFormat
          • Day
          • DayOfWeek
          • DayOfWeekAsString
          • DayOfWeekShortAsString
          • DayOfYear
          • DaysInMonth
          • DaysInYear
          • FirstDayOfMonth
          • GetNumericDate
          • GetTime
          • GetTimezone
          • GetTimezoneInfo
          • Hour
          • Millisecond
          • Minute
          • Month
          • MonthAsString
          • MonthShortAsString
          • Nanosecond
          • Now
          • Offset
          • ParseDateTime
          • Quarter
          • Second
          • SetTimezone
          • TimeFormat
          • Week
          • Year
        • type
          • ArrayLen
          • GetMetaData
          • Len
          • NullValue
          • StringLen
          • StructCount
        • xml
          • XMLChildPos
          • XMLElemNew
          • XMLFormat
          • XMLGetNodeType
          • XMLNew
          • XMLParse
          • XMLSearch
          • XMLTransform
          • XMLValidate
        • zip
          • Compress
          • Extract
          • IsZipFile
      • Components
        • async
          • Thread
        • cache
          • Cache
        • debug
          • Timer
        • io
          • Directory
          • File
        • jdbc
          • ProcParam
          • StoredProc
          • DBInfo
          • ProcResult
          • Query
          • QueryParam
          • Transaction
        • net
          • HTTPParam
          • HTTP
        • system
          • Throw
          • InvokeArgument
          • Application
          • Invoke
          • Abort
          • Include
          • Component
          • Execute
          • Flush
          • SaveContent
          • Output
          • Log
          • Sleep
          • Setting
          • Param
          • Lock
          • Associate
          • Silent
          • ProcessingDirective
          • Trace
          • Exit
          • Dump
          • Loop
        • xml
          • XML
        • zip
          • Zip
      • Exceptions
  • BoxLang Framework
    • Application.bx
    • Asynchronous Programming
    • Caching
      • Cache Service
      • BoxCache Provider
      • Custom Cache Providers
      • Custom Object Stores
      • Custom Eviction Policies
    • File Handling
    • Interceptors
      • Core Interception Points
        • Application Events
        • Cache Service Events
        • Cache Provider Events
        • Cache Object Store Events
        • Datasource Service Events
        • Dump Events
        • Dynamic Object Events
        • Function Invocations
        • HTTP Events
        • Life-cycle Events
        • Logging Events
        • Module Events
        • Module Service Events
        • Object Marshalling Events
        • Query Invocations
        • Runtime Events
        • Request Context Events
        • Scheduler Events
        • Scheduler Service Events
        • Template Invocations
        • Transaction Events
      • Request Interception Points
    • HTTP/S Calls
    • Java Interop
    • JDBC Transactions
    • Modules
      • AI
      • Compat CFML
        • Reference
          • Types
            • array
            • datetime
            • numeric
            • string
            • struct
          • Built-in Functions
            • cache
              • CacheCount
              • CacheGetAsAttempt
              • CacheRegionRemove
              • CacheRemoveAll
              • CachePut
              • CacheRegionExists
              • CacheGetSession
              • CacheGetEngineProperties
              • CacheGet
              • CacheGetDefaultCacheName
              • CacheGetProperties
              • CacheSetProperties
              • CacheGetAllIds
              • CacheIdExists
              • cacheKeyExists
              • CacheRemove
              • cacheDelete
              • CacheGetAll
              • CacheGetMetadata
              • CacheGetOrFail
              • CacheClear
              • CacheRegionNew
            • conversion
              • JSONDeserialize
            • encryption
              • Hash
              • Hash40
            • format
              • HTMLCodeFormat
              • DollarFormat
            • struct
              • DeleteClientVariable
            • system
              • Throw
              • ObjectSave
              • GetFunctionData
              • GetComponentMetadata
              • GetVariable
              • GetTagData
              • GetClientVariablesList
              • GetContextRoot
              • ObjectLoad
              • SetVariable
            • temporal
              • LSWeek
              • LSDayOfWeek
              • LSIsDate
              • DateCompare
              • GetHTTPTimestring
              • LSDateTimeFormat
              • LSDateFormat
              • LSTimeFormat
              • DayOfWeekAsString
              • DayOfWeekShortAsString
              • MonthAsString
              • MonthShortAsString
              • ToLegacyDate
              • createDate
              • LSParseDateTime
              • DateTimeFormat
              • DateFormat
              • TimeFormat
            • type
              • GetMetaData
          • Components
            • net
              • HTTP
      • CSRF
      • ESAPI
      • Evaluating Code
      • FTP
      • Image Manipulation
      • INI Files
      • JDBC
      • Jython
      • Mail
      • Markdown
      • ORM
      • OSHI - Operating System + Hardware
      • Password Encryption
      • PDF
      • Redis
      • UI Forms
      • WDDX
      • Web Support
      • Yaml
  • Extra Credit
    • MVC
    • Dependency Injection
Powered by GitBook
LogoLogo

Social Media

  • X
  • FaceBook
  • LinkedIn
  • YouTube

Bug Tracking

  • Runtimes
  • IDE
  • Modules

Support

  • Professional
  • Community
  • Slack

Copyright & Register Trademark by Ortus Solutions, Corp

On this page
  • Overview
  • Core Concepts
  • Getting Started
  • Accessing the Cache Service
  • Working with Caches
  • Cache Management
  • BoxLang BIF Integration
  • Advanced Usage
  • Monitoring and Diagnostics
  • Best Practices
  • Integration Patterns
  • Conclusion

Was this helpful?

Edit on GitHub
Export as PDF
  1. BoxLang Framework
  2. Caching

Cache Service

The CacheService manages all the caches in a BoxLang application

PreviousCachingNextBoxCache Provider

Last updated 1 day ago

Was this helpful?

The Cache Service is the central management layer for all caching functionality in BoxLang. It acts as a registry and orchestrator for cache providers, handling their lifecycle, configuration, and providing a unified interface for cache operations across your application.

Overview

The Cache Service serves as the foundation of BoxLang's caching infrastructure by:

  • Managing Cache Providers: Registering, creating, and maintaining multiple cache instances

  • Lifecycle Coordination: Handling startup, shutdown, and maintenance operations

  • Provider Registry: Managing both core and custom cache provider implementations

  • Event Broadcasting: Announcing cache-related events throughout the system

  • Global Operations: Providing system-wide cache management capabilities

Core Concepts

Cache Providers vs Cache Service

  • Cache Providers (ICacheProvider): Individual cache instances that handle specific caching needs

  • Cache Service (CacheService): The service layer that manages multiple cache providers

Think of the Cache Service as a "cache manager" that coordinates multiple specialized cache instances within your application.

Service Lifecycle

The Cache Service follows BoxLang's service lifecycle pattern:

  1. Configuration Load: Reads cache configurations from BoxLang settings

  2. Startup: Creates and initializes all configured caches

  3. Operation: Provides access to registered caches during runtime

  4. Shutdown: Gracefully shuts down all cache providers

Getting Started

Accessing the Cache Service

The Cache Service is available through the cacheService() BIF

// Get the cache service
cacheService = cacheService();

// Access the default cache
defaultCache = cacheService.getDefaultCache();

// Access a named cache  
myCache = cacheService.getCache("myCache");

// Using BIFs (recommended)
defaultCache = cache();
myCache = cache("myCache");

Working with Caches

Basic Cache Operations

// Get a cache instance
userCache = cache("userCache");

// Store data
userCache.set("user:123", userData);

// Retrieve data
result = userCache.get("user:123");
if (result.isPresent()) {
    user = result.get();
}

// Check if key exists
exists = userCache.lookup("user:123");

// Remove data
userCache.clear("user:123");

Cache Validation

// Check if a cache exists
if (arrayContains(cacheNames(), "sessionCache")) {
    sessionCache = cache("sessionCache");
    // Use the cache...
}

// Get available caches
registeredCaches = cacheNames();

Cache Management

Creating Default Caches

The simplest way to create a new cache:

// Create a cache with default BoxLang provider and settings
newCache = cacheService().createDefaultCache("myNewCache");

// Create with custom configuration
config = {
    "name": "myCache",
    "maxObjects": 5000,
    "defaultTimeout": 1800, // 30 minutes
    "evictionPolicy": "LRU"
};

customCache = cacheService().createDefaultCache("myCache", config);

Creating Custom Provider Caches

// Create cache with specific provider
properties = {
    "maxObjects": 10000,
    "defaultTimeout": 3600,
    "objectStore": "ConcurrentHashMap"
};

cache = cacheService().createCache(
    "highPerformanceCache", 
    "BoxLang", 
    properties
);

Conditional Cache Creation

// Create only if it doesn't exist
cache = cacheService().createCacheIfAbsent(
    "conditionalCache",
    "BoxLang",
    defaultProperties
);

Manual Registration

If you have a pre-configured cache provider:

// Create and configure your cache
myCache = new CustomCacheProvider()
    .setName("myCustomCache")
    .configure(cacheService(), config);

// Register it with the service
cacheService().registerCache(myCache);

Cache Replacement

// Replace an existing cache with a new implementation
newImplementation = new ImprovedCacheProvider()
    .setName("existingCache")
    .configure(cacheService(), newConfig);

cacheService().replaceCache("existingCache", newImplementation);

Individual Cache Shutdown

// Shutdown and remove a specific cache
cacheService().shutdownCache("temporaryCache");

Bulk Operations

// Clear all data from all caches
cacheService().clearAllCaches();

// Trigger reaping (cleanup) on all caches
cacheService().reapAllCaches();

// Remove and shutdown all caches
cacheService().removeAllCaches();

BoxLang BIF Integration

BoxLang provides convenient Built-in Functions (BIFs) that offer a developer-friendly interface to the Cache Service functionality. These BIFs abstract the Java API complexity and provide native BoxLang syntax for common caching operations.

Available Cache BIFs

BIF
Cache Service Equivalent
Purpose

cache()

cacheService.getCache()

Get a cache instance by name

cacheFilter()

N/A (Utility function)

Create filters for cache key operations

cacheNames()

cacheService.getRegisteredCaches()

List all registered cache names

cacheProviders()

cacheService.getRegisteredProviders()

List all registered cache providers

cacheService()

Direct access

Access the cache service directly

Basic Cache Operations

// BoxLang BIF approach
userCache = cache("userSessions");
userCache.set("user:123", userData, 1800);
user = userCache.get("user:123");

// Equivalent direct service calls
userCache = cacheService().getCache("userSessions");
userCache.set("user:123", userData, 1800, 0);
user = userCache.get("user:123");

Service Discovery

// BoxLang BIFs
allCaches = cacheNames();
allProviders = cacheProviders();

// Check if cache exists
if (arrayContains(cacheNames(), "myCache")) {
    cache("myCache").clearAll();
}
// Equivalent direct service calls
allCaches = cacheService().getRegisteredCaches();
allProviders = cacheService().getRegisteredProviders();

// Check if cache exists
if (cacheService().hasCache("myCache")) {
    cacheService().getCache("myCache").clearAll();
}

Advanced Service Operations

// BoxLang BIF approach - Direct service access
service = cacheService();
service.createCache("dynamicCache", "BoxLang", {
    "maxObjects": 5000,
    "defaultTimeout": 1800
});

// Bulk operations
service.clearAllCaches();
service.reapAllCaches();
// Equivalent explicit service access
service = getBoxContext().getRuntime().getCacheService();
service.createCache("dynamicCache", "BoxLang", properties);

// Bulk operations
service.clearAllCaches();
service.reapAllCaches();

Filter Operations

// BoxLang BIF approach with filters
userFilter = cacheFilter("user:*");
cache().clear(userFilter);

// Regex filtering
emailFilter = cacheFilter(".*@domain\.com$", true);
cache().get(emailFilter);

// Custom filter functions
cache().clear(function(key) {
    return key.getName().startsWith("temp_");
});

The equivalent direct service operations would require implementing ICacheKeyFilter or using the built-in filter classes.

BoxLang Application Integration

// Application startup - using BIFs
function initializeApplicationCaches() {
    service = cacheService();
    
    // Create application-specific caches
    service.createCache("userSessions", "BoxLang", {
        "maxObjects": 10000,
        "defaultTimeout": 1800,
        "evictionPolicy": "LRU"
    });
    
    service.createCache("apiResponses", "BoxLang", {
        "maxObjects": 5000,
        "defaultTimeout": 300,
        "evictionPolicy": "LFU"
    });
    
    // Verify caches were created
    writeOutput("Created caches: " & arrayToList(cacheNames()));
}

// Application operations - using cache BIFs
function getUserData(userID) {
    var cacheKey = "user:#userID#";
    var userData = cache("userSessions").get(cacheKey);
    
    if (userData.isPresent()) {
        return userData.get();
    }
    
    // Load and cache user data
    userData = loadUserFromDatabase(userID);
    cache("userSessions").set(cacheKey, userData, 1800);
    
    return userData;
}

Mixed Java/BoxLang Usage

// BoxLang service layer calling Java
class {
    
    property name="cacheManager" inject="CacheManager";
    
    function setupApplicationCaches() {
        // Call Java service to create caches
        cacheManager.setupApplicationCaches();
        
        // The cache will be accessible from BoxLang BIFs
        writeLog("Created system cache, accessible via cache('systemCache')", "info");
    }
}
// BoxLang usage of Java-created caches
systemData = cache("systemCache").get("config");
cache("systemCache").set("lastUpdate", now());

// BoxLang component using mixed approach
component {
    
    function initializeCaches() {
        // Create some caches via BoxLang
        cacheService().createDefaultCache("userSessions");
        
        // Create others via Java (if you have Java modules)
        var javaService = createObject("java", "com.mycompany.CacheSetupService");
        javaService.createAdvancedCaches();
        
        // All caches accessible via BIFs
        writeOutput("Available caches: " & arrayToList(cacheNames()));
    }
}

Advanced Usage

Task Scheduling Integration

The Cache Service provides a shared task scheduler for cache operations:

// Access the cache service task scheduler
scheduler = cacheService().getTaskScheduler();

// Use it for cache-related background tasks
scheduler.submit(function() {
    // Custom cache maintenance logic
    performCustomMaintenance();
});

Event Integration

The Cache Service broadcasts events throughout cache lifecycles:

// Events are announced automatically:
// - BEFORE_CACHE_SERVICE_STARTUP / AFTER_CACHE_SERVICE_STARTUP
// - BEFORE_CACHE_SERVICE_SHUTDOWN / AFTER_CACHE_SERVICE_SHUTDOWN
// - BEFORE_CACHE_SHUTDOWN / AFTER_CACHE_SHUTDOWN
// - BEFORE_CACHE_REMOVAL / AFTER_CACHE_REMOVAL
// - BEFORE_CACHE_REPLACEMENT
// - AFTER_CACHE_REGISTRATION

// Listen to cache events through the interceptor service
interceptorService = getBoxContext().getRuntime().getInterceptorService();
interceptorService.register("MyCacheListener", new CacheListener());

Error Handling

try {
    cache = cacheService().getCache("nonExistentCache");
} catch (any e) {
    // Handle cache not found
    writeLog("Cache not found: " & e.message, "warn");
    
    // Create the cache if needed
    cache = cacheService().createDefaultCache("nonExistentCache");
}

Monitoring and Diagnostics

Cache Inspection

// Get cache information
registeredCaches = cacheNames();
registeredProviders = cacheProviders();

// Inspect individual caches
cache = cache("myCache");
stats = cache.getStats();
cacheSize = cache.getSize();
isEnabled = cache.isEnabled();

Performance Monitoring

// Monitor cache performance
function monitorCaches() {
    caches = cacheNames();
    
    for (var cacheName in caches) {
        cache = cache(cacheName);
        stats = cache.getStats();
        
        writeLog("Cache [#cacheName#]: Hits=#stats.getHits()#, Misses=#stats.getMisses()#, Size=#cache.getSize()#", "info");
    }
}

Best Practices

Cache Naming Conventions

// Use descriptive, hierarchical names
cacheService().createDefaultCache("user.sessions");
cacheService().createDefaultCache("product.catalog");
cacheService().createDefaultCache("api.responses.v1");

Resource Management

// Always shutdown caches when done (if managing manually)
function cleanupTemporaryCache(cacheName) {
    try {
        cache = cache(cacheName);
        // Use the cache...
    } finally {
        // Clean up if it's a temporary cache
        if (left(cacheName, 5) == "temp.") {
            cacheService().shutdownCache(cacheName);
        }
    }
}

Provider Selection

// Choose providers based on requirements
function createOptimalCache(name, requirements) {
    var provider = "";
    var properties = {};
    
    if (requirements.isDistributed) {
        provider = "Redis";
        properties.host = requirements.redisHost;
        properties.port = requirements.redisPort;
    } else if (requirements.isPersistent) {
        provider = "BoxLang";
        properties.objectStore = "Disk";
        properties.diskPath = requirements.diskPath;
    } else {
        provider = "BoxLang";
        properties.objectStore = "ConcurrentHashMap";
    }
    
    properties.maxObjects = requirements.maxSize;
    properties.defaultTimeout = requirements.timeoutSeconds;
    
    return cacheService().createCache(name, provider, properties);
}

Error Recovery

// Implement graceful fallbacks
function getOrCreateCache(cacheName) {
    try {
        return cache(cacheName);
    } catch (any e) {
        writeLog("Cache [#cacheName#] not found, creating default cache", "warn");
        return cacheService().createDefaultCache(cacheName);
    }
}

Integration Patterns

Application Startup

// Initialize application-specific caches during startup
function initializeApplicationCaches() {
    var service = cacheService();
    
    // User session cache
    service.createDefaultCache("user.sessions", {
        "name": "user.sessions",
        "provider": "BoxLang",
        "properties": {
            "maxObjects": 10000,
            "defaultTimeout": 1800,
            "evictionPolicy": "LRU"
        }
    });
    
    // API response cache
    service.createDefaultCache("api.responses", {
        "name": "api.responses", 
        "provider": "BoxLang",
        "properties": {
            "maxObjects": 5000,
            "defaultTimeout": 300,
            "evictionPolicy": "LFU"
        }
    });
}

Module Integration

// BoxLang component for module integration
class {
    
    function onStartup(runtime) {
        var cacheService = runtime.getCacheService();
        
        // Register custom provider
        cacheService.registerProvider("MyModuleCache", createObject("java", "com.mymodule.MyModuleCacheProvider"));
        
        // Create module-specific caches
        cacheService.createCache("module.data", "MyModuleCache", moduleConfig);
    }
}

Application Usage Patterns

Service Layer Integration

// Cache-enabled service component
class {
    
    function getUserById(userID) {
        var cacheKey = "user:#userID#";
        var result = cache("users").get(cacheKey);
        
        if (result.isPresent()) {
            return result.get();
        }
        
        // Load from database
        var user = userDAO.findById(userID);
        
        // Cache for 30 minutes
        cache("users").set(cacheKey, user, 1800);
        
        return user;
    }
    
    function invalidateUser(userID) {
        var cacheKey = "user:#userID#";
        cache("users").clear(cacheKey);
    }
}

Request-Scoped Caching

// Request-level cache management
class {
    
    function onRequestStart() {
        // Create request-specific cache
        var requestCache = cacheService().createDefaultCache("request.#createUUID()#");
        request.cache = requestCache;
    }
    
    function onRequestEnd() {
        // Cleanup request cache
        if (structKeyExists(request, "cache")) {
            cacheService().shutdownCache(request.cache.getName());
        }
    }
}

Conclusion

The Cache Service provides a robust foundation for all caching needs in BoxLang applications. By centralizing cache management, it enables:

  • Scalable Architecture: Easy addition of new cache providers and instances

  • Consistent Interface: Uniform access patterns across different cache implementations

  • Lifecycle Management: Proper resource handling and cleanup

  • Event Integration: Seamless integration with BoxLang's event system

  • Flexible Configuration: Runtime and configuration-based cache setup

Whether you're using built-in providers or creating custom implementations, the Cache Service ensures your caching infrastructure remains manageable, performant, and maintainable as your application grows.