FileSystemStore

Disk-based persistent cache store with file system storage for durability across restarts

The FileSystemStore leverages disk-based storage to persist cache items as serialized entities on the file system. This store provides durability across application restarts and is highly efficient for caching scenarios that require persistence without the complexity of a database.

✨ Features

Persistent Storage: Cache survives application restarts
Efficient Serialization: Uses optimized Java serialization for fast read/write operations
File-Based Management: Each cache entry stored as a separate file for easy inspection
Automatic Cleanup: Expired entries are automatically removed during reaping
Directory-Based Organization: Simple file system structure for cache storage
Eviction Support: Compatible with all BoxCache eviction policies (LRU, LFU, FIFO, LIFO, RANDOM)

📋 Configuration Example

"diskCache": {
    "provider": "BoxCacheProvider",
    "properties": {
        "objectStore": "FileSystemStore",
        "directory": "/var/caches/app_cache",
        "maxObjects": 5000,
        "evictionPolicy": "LRU",
        "evictCount": 50,
        "defaultTimeout": 7200,
        "defaultLastAccessTimeout": 3600,
        "reapFrequency": 300
    }
}

⚙️ Configuration Properties

directory (required)

The absolute path of the directory that will hold all the serialized cache entries on disk. The directory will be created if it doesn't exist (requires appropriate file system permissions).

"directory": "/var/caches/myapp"

File System Permissions:

Ensure the BoxLang runtime has read/write permissions to the specified directory
Use absolute paths to avoid ambiguity
Consider disk space availability for large caches
Regular disk maintenance may be needed for long-running applications

Standard BoxCache Properties

The FileSystemStore supports all standard BoxCache configuration properties:

maxObjects (recommended)

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

"maxObjects": 5000

evictionPolicy

The eviction policy to use when the cache reaches capacity. Options: LRU, LFU, FIFO, LIFO, RANDOM. Default is LRU.

"evictionPolicy": "LRU"

evictCount

How many objects to evict when the cache reaches capacity. Default is 1.

"evictCount": 50

defaultTimeout

The maximum time in seconds to keep an object in the cache regardless of access. 0 = never expire. Default is 3600 (1 hour).

"defaultTimeout": 7200

defaultLastAccessTimeout

The maximum time in seconds since last access before an object expires. Default is 1800 (30 minutes).

"defaultLastAccessTimeout": 3600

reapFrequency

How often (in seconds) to check for and remove expired objects. Default is 120 (2 minutes).

"reapFrequency": 300

resetTimeoutOnAccess

If true, the last access timeout resets on every access (session-like behavior). Default is false.

"resetTimeoutOnAccess": false

useLastAccessTimeouts

If true, the last access timeout is used for eviction. Default is true.

"useLastAccessTimeouts": true

💡 Usage Examples

Template Compilation Cache

"templateCache": {
    "provider": "BoxCacheProvider",
    "properties": {
        "objectStore": "FileSystemStore",
        "directory": "/var/caches/templates",
        "maxObjects": 10000,
        "evictionPolicy": "LRU",
        "defaultTimeout": 0,
        "reapFrequency": 600
    }
}

Application Configuration Cache

"configCache": {
    "provider": "BoxCacheProvider",
    "properties": {
        "objectStore": "FileSystemStore",
        "directory": "/var/caches/config",
        "maxObjects": 500,
        "evictionPolicy": "FIFO",
        "defaultTimeout": 86400
    }
}

Asset Processing Cache

"assetCache": {
    "provider": "BoxCacheProvider",
    "properties": {
        "objectStore": "FileSystemStore",
        "directory": "/var/caches/assets",
        "maxObjects": 2000,
        "evictionPolicy": "LFU",
        "defaultTimeout": 3600,
        "defaultLastAccessTimeout": 1800,
        "reapFrequency": 300
    }
}

🎯 Best Practices

When to Use FileSystemStore:

Application configuration caches that should survive restarts
Compiled template caches for faster startup times
Asset processing results (image thumbnails, compiled assets)
Data that's expensive to regenerate but doesn't change frequently
Development/staging environments where persistence is valuable

Performance Tips:

SSD Recommended: Use solid-state drives for better I/O performance
Separate Volume: Consider using a dedicated disk volume for cache storage
Directory Structure: Each cache entry is a separate file for easy management
Disk Space: Monitor available disk space and set appropriate maxObjects
Reap Frequency: Tune reapFrequency based on cache churn rate
Eviction Strategy: Use LRU for most scenarios, LFU for stable access patterns

Important Considerations:

Not Distributed: Each application instance maintains its own file-based cache
I/O Performance: File system performance depends on disk speed (SSDs strongly recommended)
Serialization: Only Java-serializable objects can be cached
File System Limits: Some file systems have limits on files per directory
Disk Space: Monitor disk usage to prevent out-of-space errors
Permissions: Ensure proper file system permissions for the cache directory
Backup/Restore: Cache directories can be backed up but may become stale

🗂️ File System Structure

The FileSystemStore creates a simple, flat directory structure:

/var/caches/app_cache/
├── cache_entry_key1.ser
├── cache_entry_key2.ser
├── cache_entry_key3.ser
└── ...

Each cache entry is stored as a separate .ser file named after the cache key (with special characters escaped). This makes it easy to:

Inspect cache contents using file system tools
Manually clear specific cache entries if needed
Backup/restore cache data
Monitor cache size using disk usage tools

BoxCache Overview
Cache Configuration
Eviction Policies
ConcurrentStore - For in-memory caching
JDBCStore - For distributed caching scenarios
BlackHoleStore - For testing without persistence

PreviousConcurrentSoftReferenceStore NextJDBCStore

Last updated 13 days ago

Was this helpful?