Skip to content

Martini Package Cache Configuration

Overview

Cache configuration defines the named caches available to your Martini package. Each cache is declared in a single caches.conf file placed in the Configuration directory of your Martini package and is backed by one of three providers: Guava, Ehcache, or Redis.

Configuring caches at the package level lets your services, workflows, and Groovy code share fast, temporary data storage without modifying application logic. You select the provider that matches your deployment — in-memory for single-node environments, or distributed for horizontally scaled ones.

What You Will Learn

  • How to create and structure a caches.conf file in a Martini package
  • The key properties that control cache entry lifecycle (expireAfterWrite, expireAfterAccess)
  • The differences between Guava, Ehcache, and Redis providers and when to choose each
  • How to configure provider-specific properties such as heap, offHeap, disk, and connectionName
  • How to troubleshoot common cache configuration errors

When To Use This

Use Martini package cache configuration when:

  • Your services or workflows repeatedly query a database or external API for the same data
  • You want to share temporary state across multiple service or workflow calls within the same Martini package
  • You need configurable expiration policies to control how long data remains valid in cache
  • You are scaling your Martini deployment horizontally and need a shared cache backed by Redis
  • You want to decouple provider selection from your service or workflow logic so you can swap backends without rewriting logic

Prerequisites

Before configuring caches in a Martini package, ensure the following are in place:

Cache Configuration File

The caches.conf file is the central place where you declare every named cache your Martini package uses. Placing all cache definitions in one file makes it easy to review, tune, and swap providers independently of your service or workflow logic.

Setting Up the caches.conf File

To activate caching in your Martini package, create a file named caches.conf in the Configuration directory. This file uses HOCON (Human-Optimized Config Object Notation) format to declare one or more named caches.

The general structure of caches.conf is:

1
2
3
4
5
cacheName {
    provider = ("guava"|"ehcache"|"redis")
    (expireAfterWrite|expireAfterAccess) = (number, milliseconds by default)
    // Additional provider-specific properties
}

To create a cache configuration:

  1. Expand your Martini package.
  2. Navigate to the Configuration directory inside the package.
  3. Right-click the Configuration directory , select New > File, and name the file caches.conf.
  4. Add named cache blocks using the HOCON structure above.
  5. Save the file, then restart the Martini package for the changes to take effect.

Expected result: The named cache become available to all services, workflows, and Groovy code within the Martini package.

Cache Configuration File Key Terms

The following terms describe the core building blocks of a caches.conf entry.

Term Definition
cacheName The unique identifier you assign to a cache. Used when calling Cache Functions in services, workflows, or Groovy code. Must match exactly at runtime.
provider The cache backend: guava, ehcache, or redis. Determines storage type, scalability, and persistence behavior.
expireAfterAccess Duration (milliseconds by default) before a cache entry is evicted following its last read or write access.
expireAfterWrite Duration (milliseconds by default) before a cache entry is evicted following its creation or most recent replacement.
HOCON Human-Optimized Config Object Notation — a configuration format used by Martini package config files. Supports time-unit suffixes such as 30s, 10m, and 1h.

Cache Configuration File Properties

These common properties apply across all cache providers and control entry lifecycle behavior.

Property Example Value What It Controls
provider "guava" Selects the caching backend for this named cache. Accepted values: "guava", "ehcache", "redis".
expireAfterWrite 30s Evicts a cache entry after this duration since creation or last write. Supports time units: ms, s, m, h.
expireAfterAccess 1h Evicts a cache entry after this duration since last read or write. Takes precedence over expireAfterWrite when both are set.

Note

You must specify at least expireAfterWrite or expireAfterAccess. Omitting both means entries never expire automatically, which can cause unbounded memory growth over time.

How Cache Configuration File Works

When a Martini package starts, Martini reads caches.conf and initializes each declared cache according to its provider and property settings. Each named cache is registered in memory and becomes immediately available to all services, workflows, and Groovy code inside that package.

Cache entries are stored and retrieved by key. When a Cache Function is called at runtime, Martini routes the operation to the correct provider transparently. Expiration policies run in the background and automatically evict stale entries based on the configured expireAfterWrite or expireAfterAccess duration.

Important: Changes to caches.conf take effect only after restarting the Martini package . Editing the file while the package is running does not modify existing cache state or registrations.

Cache Configuration File Benefits and Use Cases

Centralizing cache definitions in caches.conf separates infrastructure concerns from workflow or service logic. This approach lets you:

  • Swap providers (for example, moving from Guava to Redis for horizontal scaling) without changing any service, workflow, or Groovy code
  • Adjust expiration policies per cache independently, tuning each one to match the data's expected freshness requirements
  • Review and audit all cached data structures in one place during code reviews or incident investigation

Troubleshooting Cache Configuration File Issues

Problem Detection Cause Fix Affected Versions
Cache Function throws an exception when getting a cache item Runtime exception thrown when calling a Cache Function to retrieve an item caches.conf is missing from the Configuration directory, or the file contains HOCON syntax errors Create the caches.conf file in the Configuration directory with the required cache definitions. Validate the HOCON syntax, then restart the Martini package. All versions
Configuration changes have no effect after editing Updated expiration or provider settings are ignored at runtime Martini package was not restarted after modifying caches.conf Restart the Martini package from the Navigator to apply the updated configuration. All versions
Cache not found at runtime Runtime exception referencing an unknown cache name The cache name used in workflow or service logic does not match the key declared in caches.conf Ensure the cache name in your workflow or service or Groovy code exactly matches the cacheName key in caches.conf (case-sensitive). All versions

Cache Providers

Martini supports three cache providers, each suited to different performance, scalability, and persistence requirements. Select the provider that best matches your deployment environment and data lifecycle needs.

Guava Cache Provider

Guava Cache is an in-memory caching mechanism by Google designed for use within a single application instance. It provides low-latency access with automatic eviction based on size or time, making it well-suited for lightweight, local caching in single-node Martini deployments.

Use Guava when:

  • Your Martini deployment is single-node (not clustered)
  • You need fast, in-process cache access with minimal configuration overhead
  • Cache data does not need to survive a Martini package restart

Guava Cache Provider Configuration Properties

The following properties are specific to the Guava cache provider and control internal hash table behavior and maximum cache size.

Property Example Value What It Controls
provider "guava" Selects the Guava cache backend.
expireAfterWrite 30s Time before a cache entry expires after the last write operation.
heap 1000 Maximum number of entries held in memory. When the limit is reached, the least-recently-used entry is evicted.
initialCapacity 100 Initial size of the internal hash table. Tune this value to reduce resize operations when the expected cache volume is known upfront.

Example Guava cache configuration:

1
2
3
4
5
6
myGuavaCache {
    provider = "guava"
    expireAfterWrite = 30s
    heap = 1000
    initialCapacity = 100
}

Expected result: A cache named myGuavaCache is registered when the Martini package starts. Entries expire 30 seconds after their last write and the cache holds at most 1,000 entries in memory.

Ehcache Provider

Ehcache is a scalable, Java-based cache provider that supports in-memory (heap and off-heap) and disk-based storage tiers. It is suitable for caching large datasets that exceed available JVM heap memory, or when data must persist across Martini package restarts.

Use Ehcache when:

  • You need to cache large datasets that exceed JVM heap limits
  • Your use case requires disk-based persistence between Martini package restarts
  • You need fine-grained control over memory tiers (heap, off-heap, and disk)

Ehcache Provider Configuration Properties

Ehcache supports all common cache properties plus additional settings for multi-tier storage and serialization.

Property Example Value What It Controls
provider "ehcache" Selects the Ehcache backend.
expireAfterWrite 30m Time before cache entries expire after the last write.
expireAfterAccess 1h Time before cache entries expire after the last access.
heap 100 Maximum number of entries stored in JVM heap memory.
offHeap 10MB Size of the off-heap memory tier. Stores data outside the JVM heap to reduce garbage collection pressure.
disk 20MB Size of the disk storage tier for overflow or persistence beyond memory limits.
diskStore /tmp/disk File system path for disk-based cache data. Required when disk is configured.
key (type config) Configures the type and serializer for cache entry keys.
value (type config) Configures the type and serializer for cache entry values.

Example Ehcache configuration:

1
2
3
4
5
6
7
8
9
myEhcache {
    provider = "ehcache"
    expireAfterWrite = 30m
    expireAfterAccess = 1h
    heap = 100
    offHeap = 10MB
    disk = 20MB
    diskStore = /tmp/disk
}

Expected result: A cache named myEhcache uses up to 100 heap entries, spills overflow to 10 MB of off-heap memory, and persists entries to disk at /tmp/disk. Entries expire 30 minutes after their last write, or 1 hour after their last access.

Redis Cache Provider

Redis is a distributed, in-memory data store known for high availability, optional durability, and support for multi-node deployments. Use Redis when cached data must be shared across multiple Martini instances or when your deployment is horizontally scaled.

Use Redis when:

  • Your Martini environment is clustered or horizontally scaled
  • You need shared cache state visible across multiple Martini instances
  • Your use case requires high availability or optional persistence for cached data

Redis Cache Provider Configuration Properties

Redis supports all common cache properties plus connection and serialization settings specific to the Redis provider.

Property Example Value What It Controls
provider "redis" Selects the Redis cache backend.
connectionName "MyRedisConnection" The name of the Redis database connection configured in Martini. Must reference an existing connection.
expireAfterWrite 30s Time before cache entries expire after the last write.
codecClassName (fully qualified class name) Custom RedisCodec implementation used for entry serialization and deserialization. Optional.
asyncWrites false When true, write operations complete asynchronously, improving throughput at the cost of write guarantees.

Example Redis cache configuration:

1
2
3
4
5
6
myRedisCache {
    provider = "redis"
    connectionName = "MyRedisConnection"
    expireAfterWrite = 30s
    asyncWrites = false
}

Expected result: A cache named myRedisCache stores entries in the Redis instance identified by MyRedisConnection. Entries expire 30 seconds after their last write.

Choosing a Cache Provider

Use this reference to select the provider that best fits your deployment requirements.

Requirement Recommended Provider
Single-node, low-latency in-memory caching Guava
Large datasets or disk overflow support Ehcache
Multi-node distributed caching Redis
Cache persistence across package restarts Ehcache (with disk) or Redis
Minimal configuration overhead Guava

Troubleshooting Cache Provider Issues

Problem Detection Cause Fix Affected Versions
Redis cache fails to connect Runtime exception with a connection refused or unknown host error connectionName references a non-existent or misconfigured Redis connection in Martini Verify the Redis connection exists in Martini and that the connectionName value matches it exactly. All versions
Ehcache disk store errors IOException or permission denied entries in the Martini logs The diskStore path does not exist, or the Martini process lacks write permissions to that path Create the target directory and grant write permissions to the OS user running the Martini process. All versions
Cache entries missing after package restart (Guava) Expected values absent from a Guava-backed cache after restart Guava is purely in-memory and does not persist data across restarts Switch to Ehcache with disk storage or Redis if data must survive a Martini package restart. All versions

Helpful Resources