Skip to content

Cache Functions

Overview

Martini's Cache Functions let you store, retrieve, and invalidate named cache entries directly inside your workflows and services. By keeping frequently accessed data in a fast in-memory store, you avoid repeating expensive database queries or external API calls on every workflow or service execution.

Cache Functions work with named caches you declare in your Martini package configuration, giving you full control over what gets cached, for how long, and how it is invalidated.

What You Will Learn

  • How cacheGet, cachePut, and cacheInvalidate work and when to use each
  • The input parameters each function requires
  • How to configure the named cache provider that backs these functions
  • How to troubleshoot common cache function issues

When To Use This

Use Cache Functions when:

  • A workflow or service repeatedly fetches the same data from a database or external API within a short time window
  • You want to reduce response latency by serving repeated requests from memory instead of a live data source
  • You need to share computed results across multiple workflow or service calls within the same Martini package
  • You want to explicitly expire or remove a cached value when the underlying data changes

Prerequisites

Cache Functions Reference

Cache Functions are the core building blocks for interacting with named caches at runtime. Each function targets a specific named cache and acts on a single entry identified by its key.

Cache Functions Key Terms

The following terms describe the parameters and concepts common to all Cache Functions.

Term Definition
cacheName The identifier of the named cache to use. Must match a cache name declared in your Martini package's caches.conf file exactly.
key A unique string that identifies a specific entry within the cache. Used to store, retrieve, or remove a value.
value The data you want to store in the cache. Accepted as any object; typically a string, number, map, or serializable model object.
entry A single item stored in the cache, consisting of a key and its associated value.

Available Cache Functions

The table below are the common Cache Functions, their inputs, and their purpose.

Function Inputs What It Does
cacheGet cacheName, key Returns the value stored under key, or null if no entry exists.
cachePut cacheName, key, value Stores value under key. Overwrites any existing entry for key.
cacheInvalidate cacheName, key Removes the entry for key from the cache immediately.

How Cache Functions Work

Each Cache Function operates on the named cache you specify at the time of the call. Martini resolves the cache name to the provider configured in caches.conf (Guava, Ehcache, or Redis), so your function calls remain the same regardless of the underlying storage backend.

Typical read-through pattern:

  1. Call cacheGet with cacheName and key.
  2. If the returned value is not null, use it directly — the cache hit avoids a live data fetch.
  3. If the value is null (cache miss), fetch the data from the source (database, API, etc.).
  4. Call cachePut to store the fresh value under the same key for future requests.
  5. When the source data changes, call cacheInvalidate to remove the stale entry so the next request fetches and caches updated data.

Entry lifecycle:

  • Entries expire automatically according to the expireAfterWrite or expireAfterAccess policy defined in caches.conf.
  • cacheInvalidate removes an entry immediately, before its TTL expires.
  • cachePut on an existing key replaces the value and resets the entry's expiry timer.

Cache Functions Benefits and Use Cases

Cache Functions eliminate unnecessary repetition in your workflows and services, which directly improves throughput and reduces load on downstream systems.

Common scenarios include:

  • Reference data caching — Store lookup tables (country codes, product categories) that change infrequently but are read on every request.
  • API response caching — Cache the result of a slow or rate-limited third-party API call so only the first caller in a time window pays the latency cost and subsequent calls are served from cache without consuming your API quota.
  • Session-scoped computation — Store the result of an expensive calculation and share it across multiple steps within the same execution context.
  • Invalidation on write — Call cacheInvalidate immediately after updating a database record to ensure the next read fetches fresh data instead of a stale cached copy.

Troubleshooting Cache Function Issues

The following table covers the most common problems encountered when using Cache Functions.

Problem Detection Cause Fix Affected Versions
cacheGet always returns null No cached values retrieved; every call hits the source cacheName in the function does not match the name declared in caches.conf Verify the cacheName parameter matches the cache block name in caches.conf exactly All
cachePut has no effect Values stored but not retrievable on next call The cache entry expires too quickly due to a short TTL in caches.conf Increase expireAfterWrite or expireAfterAccess in caches.conf All
cacheInvalidate throws a runtime error Service fails with a cache-related exception The named cache does not exist or the Martini package has not been restarted Confirm the caches.conf file is saved and restart the Martini package to reload config All
Cache not available after package restart Functions fail with "cache not found" error caches.conf is missing from the Configuration directory of the Martini package Create the caches.conf file and declare the required named cache — see Martini Package Cache Configuration All

Configuring the Cache Provider

Cache Functions rely on named caches that you declare at the Martini package level. The provider you choose (Guava, Ehcache, or Redis) determines the storage type, capacity limits, and whether the cache is local or distributed.

Setting Up a Named Cache for Cache Functions

To make a named cache available to your Cache Functions, define it in the caches.conf file inside your Martini package's Configuration directory.

Minimal Guava example:

1
2
3
4
productCache {
    provider = "guava"
    expireAfterWrite = 5m
}

Using this cache in a Workflow:

  • cacheGet("productCache", "product-42") — retrieves the entry with key product-42
  • cachePut("productCache", "product-42", productObject) — stores productObject under product-42
  • cacheInvalidate("productCache", "product-42") — removes the entry immediately

Expected result: The workflow reads from and writes to the productCache Guava cache, with entries automatically evicted five minutes after they are written.

For full provider configuration options including Ehcache and Redis, see Martini Package Cache Configuration.

Helpful Resources