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
  • BoxLang Cache Engine
  • Cache Aggregation
  • Features at a Glance
  • Configuration
  • Default Caches
  • Providers
  • Object Stores
  • Eviction Policies
  • Cache BIFs (Built-in Functions)
  • Overview
  • Available Cache BIFs
  • cache(cacheName)
  • cacheFilter( filter, useRegex )
  • cacheNames()
  • cacheProviders()
  • cacheService()
  • Practical Usage Patterns
  • Advanced Patterns
  • Best Practices
  • Keep Exploring

Was this helpful?

Edit on GitHub
Export as PDF
  1. BoxLang Framework

Caching

BoxLang ships with an enterprise Caching Engine and Cache Agnostic API Aggregator!

PreviousAsynchronous ProgrammingNextCache Service

Last updated 1 day ago

Was this helpful?

BoxLang Cache Engine

The BoxLang Cache Engine is a high-performance caching solution designed to optimize data retrieval speeds for applications using the BoxLang programming language. By leveraging advanced caching algorithms and memory management techniques, it minimizes latency, enhances scalability, and improves the overall efficiency of data access. Whether handling frequent read operations or reducing server load, the BoxLang Cache Engine serves as an essential component for deploying robust and responsive applications.

Cache Aggregation

The BoxLang Cache Engine also functions as a powerful cache aggregator. This capability allows it to aggregate various cache providers under a single, unified interface, simplifying the management and operation of caching systems. By providing a centralized API, BoxLang Cache Engine streamlines access to multiple caching solutions, ensuring seamless integration and enhanced flexibility. This feature is particularly beneficial for applications that require a diverse set of caching tactics, as it reduces complexity and boosts overall system coherence.

Features at a Glance

  • Cache Aggregator

    • Ability to aggregate different caching engines via our ICacheProvider interface

    • Ability to aggregate different configurations of the same caches

    • Rich aggregation event model

    • Granular logging

  • Fast and Simple to use

    • Simple API and configuration parameters

    • Small Footprint

  • Solid Core

    • Multi-Threaded

    • Based on Java Concurrency Classes

  • Extensible & Flexible

    • CachelListeners for event broadcasting

    • Create custom eviction policies

    • Create custom cache providers

    • Create custom cache key filters

    • Create custom object storages

  • Highly Configurable

    • JVM Threshold Checks

    • Object Limits

    • Ability to time-expire objects

    • Eternal (singletons) and time-lived objects

    • Fully configurable at runtime via dynamic configurations and hot updates

Configuration

Default Caches

Cache
Object Store
Hint

default

ConcurrentStore

The default cache in BoxLang is used for queries, templates, and many more internal usages.

bxSessions

ConcurrentStore

If you activate session management in your web or client applications, user session information will be stored here.

bxRegex

ConcurrentSoftReferenceStore

This is where all dynamic regular expressions are compiled and kept.

Providers

Object Stores

Eviction Policies

The BoxCache also ships with several different eviction policies that are triggered on eviction conditions like:

  • Max objects reached

  • Memory threshold

  • Garbage collections

  • Much more.

Policy
Purpose

LRU (Least Recently Used)

Evicts the objects that haven't been accessed for the longest time. Best for applications with temporal locality where recently accessed items are more likely to be accessed again. Ideal for general-purpose caching scenarios.

MRU (Most Recently Used)

Evicts the most recently accessed objects first. Useful when you want to keep older, established data and remove newly added items. Good for scenarios where recent additions are less valuable than historical data.

LFU (Least Frequently Used)

Evicts objects with the lowest access frequency count. Maintains items that are accessed often, regardless of when they were last accessed. Perfect for caching frequently requested data like popular products or common API responses.

MFU (Most Frequently Used)

Evicts the most frequently accessed objects first. Counterintuitive but useful in scenarios where you want to cycle out "hot" data to make room for less popular items that might become important. Rare use case but valuable for specialized applications.

FIFO (First In, First Out)

Evicts objects in the order they were added to the cache. Simple queue-based eviction that doesn't consider access patterns. Good for time-sensitive data where older entries naturally become less relevant, like news feeds or log entries.

LIFO (Last In, First Out)

Evicts the most recently added objects first, like a stack. Keeps older established data while removing newer additions. Useful when you want to maintain a stable core dataset and only temporarily cache additional items.

Random

Evicts objects randomly without considering access patterns or insertion order. Provides consistent average performance without the overhead of tracking access metadata. Good for scenarios where no clear access pattern exists or when you want to avoid the worst-case behaviors of other policies.

Cache BIFs (Built-in Functions)

BoxLang provides a comprehensive set of Built-in Functions (BIFs) that offer convenient access to the caching infrastructure. These BIFs provide a developer-friendly interface for working with caches, filters, and the cache service without requiring direct Java interaction.

Overview

Cache BIFs serve as the primary interface for BoxLang developers to interact with the caching system. They provide:

  • Simple Access: Easy retrieval of cache instances and services

  • Functional Approach: Chainable operations for cache manipulation

  • Filter Support: Powerful pattern matching for bulk operations

  • Service Discovery: Introspection capabilities for registered caches and providers

  • BoxLang Integration: Native BoxLang syntax and conventions

Available Cache BIFs

Summary Table

BIF
Purpose
Returns

cache()

Get a cache instance by name

ICacheProvider

cacheFilter()

Create filters for cache key operations

ICacheKeyFilter

cacheNames()

List all registered cache names

Array

cacheProviders()

List all registered cache providers

Array

cacheService()

Access the cache service directly

CacheService

cache(cacheName)

The primary BIF for accessing cache instances. Returns a cache provider that implements the ICacheProvider interface.

Syntax:

cache([cacheName="default"])

Parameters:

  • cacheName (string, optional): The name of the cache to retrieve. Defaults to "default"

Returns: ICacheProvider - The requested cache instance

Examples:

// Get the default cache
myCache = cache();

// Get a named cache
userCache = cache("userSessions");
apiCache = cache("apiResponses");

// Basic cache operations
cache().set("user:123", userData);
user = cache().get("user:123");
cache().clear("user:123");

// Chained operations
cache("userSessions")
    .set("session:abc123", sessionData, 1800) // 30 minutes
    .set("session:def456", otherSession, 3600); // 1 hour

// Check if cache exists and use it
if (arrayContains(cacheNames(), "productCache")) {
    product = cache("productCache").get("product:456");
}

cacheFilter( filter, useRegex )

Creates filter objects for performing bulk operations on cache keys using pattern matching.

Syntax:

cacheFilter(filter, [useRegex=false])

Parameters:

  • filter (string, required): The pattern to match against cache keys

  • useRegex (boolean, optional): Use regex pattern instead of wildcard. Defaults to false

Returns: ICacheKeyFilter - A filter object for cache operations

Wildcard Patterns:

  • * - Matches any sequence of characters

  • ? - Matches any single character

  • [abc] - Matches any character in the brackets

  • [a-z] - Matches any character in the range

Examples:

// Wildcard filtering (default)
userFilter = cacheFilter("user:*");
sessionFilter = cacheFilter("session:*");
tempFilter = cacheFilter("temp_*");

// Regex filtering
emailFilter = cacheFilter(".*@domain\.com$", true);
idFilter = cacheFilter("^id_\d{4,6}$", true);

// Use filters with cache operations
cache().clear(cacheFilter("temp_*")); // Clear all temp keys
cache().clear(cacheFilter("user:session_.*", true)); // Regex clear

// Get multiple keys with filter
userSessions = cache().get(cacheFilter("user:*"));
// Returns: { "user:123": userData, "user:456": otherUser, ... }

// Bulk operations with filters
cache().clear(cacheFilter("api:response:*")); // Clear API cache
cache().lookup(cacheFilter("product:*")); // Check which products are cached

// Complex patterns
cache().clear(cacheFilter("cache_temp_[0-9]*")); // Clear numbered temp caches
cache().get(cacheFilter("user_session_????")); // Get 4-char session IDs

Custom Filter Functions:

You can also use closures/lambdas as filters:

// Custom filter using closure
customFilter = function(key) {
    return key.getName().startsWith("special_") && 
           key.getName().length() > 10;
};

cache().clear(customFilter);

// One-liner custom filters
cache().clear(key => key.getName().contains("_expired_"));
cache().get(key => key.getName().endsWith("_active"));

cacheNames()

Returns an array of all registered cache names in the system.

Syntax:

cacheNames()

Returns: Array - Array of cache names as strings

Examples:

// Get all cache names
allCaches = cacheNames();
writeOutput("Available caches: " & arrayToList(allCaches));

// Check if specific cache exists
if (arrayContains(cacheNames(), "mySpecialCache")) {
    // Use the cache
    cache("mySpecialCache").set("key", "value");
} else {
    // Create the cache or handle missing cache
    writeOutput("Cache 'mySpecialCache' not found!");
}

// Iterate through all caches
for (cacheName in cacheNames()) {
    cacheInstance = cache(cacheName);
    writeOutput("Cache '#cacheName#' has #cacheInstance.getSize()# items");
}

// Filter cache names
userCaches = arrayFilter(cacheNames(), function(name) {
    return name.startsWith("user");
});

cacheProviders()

Returns an array of all registered cache provider names.

Syntax:

cacheProviders()

Returns: Array - Array of provider names as strings

Examples:

// Get all available providers
providers = cacheProviders();
writeOutput("Available providers: " & arrayToList(providers));

// Check provider availability
if (arrayContains(cacheProviders(), "Redis")) {
    // Can create Redis caches
    writeOutput("Redis provider is available");
} else {
    writeOutput("Redis provider not registered");
}

// Display provider information
for (provider in cacheProviders()) {
    writeOutput("Provider available: #provider#");
}

cacheService()

Provides direct access to the underlying cache service for advanced operations.

Syntax:

cacheService()

Returns: CacheService - The cache service instance

Examples:

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

// Create new caches dynamically
service.createCache("newCache", "BoxLang", {
    "maxObjects": 5000,
    "defaultTimeout": 1800,
    "evictionPolicy": "LRU"
});

// Register custom providers
service.registerProvider("MyProvider", createObject("java", "com.mycompany.MyProvider"));

// Bulk operations
service.clearAllCaches(); // Clear all caches
service.reapAllCaches();  // Run maintenance on all caches

// Advanced cache management
service.replaceCache("oldCache", newCacheInstance);
service.shutdownCache("temporaryCache");

Practical Usage Patterns

Basic Caching Pattern

// Simple get-or-set pattern
function getUser(userID) {
    var cacheKey = "user:#userID#";
    var user = cache().get(cacheKey);
    
    if (user.isPresent()) {
        return user.get();
    }
    
    // Load from database
    user = userService.loadUser(userID);
    
    // Cache for 30 minutes
    cache().set(cacheKey, user, 1800);
    
    return user;
}

Session Management

// Session cache operations
function storeSession(sessionID, sessionData) {
    cache("sessions").set("session:#sessionID#", sessionData, 3600);
}

function getSession(sessionID) {
    return cache("sessions").get("session:#sessionID#");
}

function clearUserSessions(userID) {
    var filter = cacheFilter("session:*user:#userID#*");
    cache("sessions").clear(filter);
}

function cleanupExpiredSessions() {
    // Custom filter for expired sessions
    var expiredFilter = function(key) {
        var session = cache("sessions").getQuiet(key);
        return session.isPresent() && 
               session.get().lastActivity < dateAdd("h", -2, now());
    };
    
    cache("sessions").clear(expiredFilter);
}

API Response Caching

// API response caching with patterns
function cacheAPIResponse(endpoint, params, response) {
    var cacheKey = "api:#endpoint#:#hash(serialize(params))#";
    cache("apiCache").set(cacheKey, response, 600); // 10 minutes
}

function getCachedAPIResponse(endpoint, params) {
    var cacheKey = "api:#endpoint#:#hash(serialize(params))#";
    return cache("apiCache").get(cacheKey);
}

function clearAPICache(endpoint) {
    if (isNull(endpoint)) {
        // Clear all API cache
        cache("apiCache").clear(cacheFilter("api:*"));
    } else {
        // Clear specific endpoint
        cache("apiCache").clear(cacheFilter("api:#endpoint#:*"));
    }
}

Cache Warming and Preloading

// Cache warming function
function warmupCaches() {
    // Warm user cache with active users
    var activeUsers = userService.getActiveUsers();
    
    for (var user in activeUsers) {
        cache("users").set("user:#user.id#", user, 7200); // 2 hours
    }
    
    // Warm product cache
    var popularProducts = productService.getPopularProducts();
    
    for (var product in popularProducts) {
        cache("products").set("product:#product.id#", product, 3600);
    }
    
    writeOutput("Warmed #arrayLen(activeUsers)# users and #arrayLen(popularProducts)# products");
}

Cache Statistics and Monitoring

// Cache monitoring function
function getCacheReport() {
    var report = {};
    
    for (var cacheName in cacheNames()) {
        var cacheInstance = cache(cacheName);
        var stats = cacheInstance.getStats();
        
        report[cacheName] = {
            "size": cacheInstance.getSize(),
            "hits": stats.getHits(),
            "misses": stats.getMisses(),
            "hitRate": stats.getHitRate(),
            "enabled": cacheInstance.isEnabled()
        };
    }
    
    return report;
}

// Display cache status
function displayCacheStatus() {
    var report = getCacheReport();
    
    for (var cacheName in report) {
        var info = report[cacheName];
        writeOutput("Cache: #cacheName#");
        writeOutput("  Size: #info.size# items");
        writeOutput("  Hit Rate: #numberFormat(info.hitRate * 100, '0.00')#%");
        writeOutput("  Hits: #info.hits#, Misses: #info.misses#");
        writeOutput("  Status: #info.enabled ? 'Enabled' : 'Disabled'#");
        writeOutput("---");
    }
}

Dynamic Cache Creation

// Create caches based on application needs
function createUserCache(maxUsers) {
    var service = cacheService();
    
    if (!service.hasCache("userCache")) {
        service.createCache("userCache", "BoxLang", {
            "maxObjects": maxUsers * 2,
            "defaultTimeout": 3600,
            "evictionPolicy": "LRU",
            "objectStore": "ConcurrentHashMap"
        });
        
        writeOutput("Created user cache for #maxUsers# users");
    }
    
    return cache("userCache");
}

Error Handling and Fallbacks

// Safe cache operations with fallbacks
function safeGet(cacheKey, fallbackFunction) {
    try {
        var result = cache().get(cacheKey);
        if (result.isPresent()) {
            return result.get();
        }
    } catch (any e) {
        writeLog("Cache error: #e.message#", "error");
    }
    
    // Fallback to function
    var data = fallbackFunction();
    
    // Try to cache the result
    try {
        cache().set(cacheKey, data, 1800);
    } catch (any e) {
        writeLog("Cache set error: #e.message#", "warning");
    }
    
    return data;
}

Advanced Patterns

Cache Hierarchies

// Hierarchical cache clearing
function clearUserData(userID) {
    var filters = [
        cacheFilter("user:#userID#*"),           // User data
        cacheFilter("session:*user:#userID#*"),  // User sessions  
        cacheFilter("profile:#userID#*"),        // User profiles
        cacheFilter("pref:#userID#*")            // User preferences
    ];
    
    for (var filter in filters) {
        cache().clear(filter);
    }
}

Multi-Cache Operations

// Operate across multiple caches
function clearAllUserCaches(userID) {
    var userCaches = arrayFilter(cacheNames(), function(name) {
        return name.contains("user") || name.contains("session");
    });
    
    for (var cacheName in userCaches) {
        var userFilter = cacheFilter("*#userID#*");
        cache(cacheName).clear(userFilter);
    }
}

Cache Synchronization

// Synchronize data across multiple caches
function syncUserAcrossCaches(userID, userData) {
    var caches = ["primaryUsers", "secondaryUsers", "userProfiles"];
    
    for (var cacheName in caches) {
        if (arrayContains(cacheNames(), cacheName)) {
            cache(cacheName).set("user:#userID#", userData, 3600);
        }
    }
}

Best Practices

1. Cache Naming Conventions

// Use descriptive, hierarchical cache keys
cache().set("user:profile:#userID#", profile);
cache().set("api:response:v1:#endpoint#:#params#", response);
cache().set("session:data:#sessionID#", sessionData);
cache().set("config:app:#version#", configuration);

2. Efficient Filter Usage

// Prefer specific patterns over broad wildcards
cache().clear(cacheFilter("temp:session:*"));        // Good
cache().clear(cacheFilter("*"));                     // Avoid - too broad

// Use regex for complex patterns
cache().clear(cacheFilter("^user:temp_\d{8}$", true)); // Complex pattern

3. Error Handling

// Always handle cache failures gracefully
try {
    return cache().get(key).orElse(fallbackValue);
} catch (any e) {
    writeLog("Cache error: #e.message#", "error");
    return fallbackValue;
}

4. Performance Monitoring

// Regular cache performance checks
function monitorCachePerformance() {
    for (var cacheName in cacheNames()) {
        var cacheInstance = cache(cacheName);
        var hitRate = cacheInstance.getStats().getHitRate();
        
        if (hitRate < 0.7) { // Less than 70% hit rate
            writeLog("Cache '#cacheName#' has low hit rate: #hitRate#", "warning");
        }
    }
}

Keep Exploring

BoxLang's Cache BIFs provide a powerful and intuitive interface for working with the caching infrastructure. They enable developers to:

  • Access Caches Easily: Simple syntax for retrieving and using cache instances

  • Filter Operations: Powerful pattern matching for bulk cache operations

  • Service Discovery: Easy introspection of available caches and providers

  • Advanced Management: Direct access to cache service capabilities

By leveraging these BIFs, developers can implement sophisticated caching strategies while maintaining clean, readable BoxLang code. The functional approach supports both simple use cases and complex enterprise caching scenarios. Now that we have the basics, we will explore more in-depth how to use the BoxCache engine.

Multiple : FIFO, LFU, LIFO, LRU, MFU, MRU, Random

Memory Management & Memory Sensitive Caching based on

The main BoxLang configuration file configures the BoxCache boxlang.json which can be found in your $BOXLANG_HOME/config/boxlang.json. You can find all the .

Every BoxLang runtime comes pre-configured with the following mandatory caches for operation. You can configure them as you see fit. Please see the configuration area.

Eviction Policies
Java Soft References
documentation about configuration in the caches area
caches

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 Mong DB 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
BoxCache Diagram

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

JDCBStore

Stores caches in JDBC Databases

Each store can have different configuration properties as well.