# UTIL_Cache

**Class** · Group: `Utilities`

Learn it: [Utilities guide](/utilities-guide)

<div class="apex-member apex-class">

```apex
global inherited sharing class UTIL_Cache
```

Factory for Platform Cache instances with nested interface pattern.
Provides intelligent cache management with automatic fallback from Session to Org cache,
bulk operations, and user-scoped keys.

Key Features:

    - **Framework Safe**: Defaults to UTIL_Cache.getPlatformCacheName() for internal package usage.

    - **Your Own Partitions**: Supports custom partitions in your org via .withPartition().

    - **Governor Friendly**: Uses putAll and getAll to minimize cache commits/reads.

    - **Bulk Optimized**: getAll() uses native Platform Cache bulk retrieval for optimal performance.

    - **Graceful Failure**: Silently handles missing partitions or cache unavailability.

Performance Notes:

    - getAll() and getFromCache() use optimized single-key get() instead of contains() + get() pattern.

    - contains() uses get() instead of contains() to reduce network round-trips.

    - putAll() and removeAll() iterate as Platform Cache does not support bulk operations with TTL.

    - Each cache operation reduces round-trips by eliminating redundant contains() checks.

**Concurrency model — non-atomic across transactions:**
All cache operations are per-transaction. Salesforce Platform Cache exposes NO
compare-and-swap, NO atomic-increment, and NO cross-transaction lock primitive — so a
read-modify-write pattern (e.g. `Integer current = (Integer)cache.get(KEY); cache.put(KEY, current + 1);`)
silently loses 80-95% of writes under realistic 50-100 parallel transaction load (last-writer-wins).
Empirically: the parallel-cache-contention extended load test runs 100 parallel HTTP POSTs each
incrementing the same counter; final counter is consistently `[1, 100]` rather than 100 — i.e. 85-94
lost updates per run. All 100 calls return `WRITE_SUCCESS` from their own transaction's perspective.
For counter-style use cases (rate limiters, dedupe caches, distributed semaphores) persist to a
custom object instead and use SOQL `FOR UPDATE` row locks; that is the only Salesforce-native atomic
primitive. See "Don't Use Cache for Counters or Semaphores" in the Utilities Developer Guide
(Platform Cache Framework → Best Practices) for the full pattern with the seed-the-row prerequisite.

**Example**

```apex
UTIL_Cache.Store cache = UTIL_Cache.org();
cache.put('configKey', configValue, 3600);
Object cached = cache.get('configKey');
```

**See Also:** [UTIL_System](/reference/apex/util-system)

</div>

---

## Methods

| Method | Description |
|--------|-------------|
| global static [UTIL_Cache.Store](/reference/apex/util-cache-store) [auto](#auto)() | Creates a new cache instance backed by Platform Cache (Session → Org). |
| global static [UTIL_Cache.Store](/reference/apex/util-cache-store) [autoWithTransactionFallback](#autowithtransactionfallback)() | Returns a Store that tries Session → Org Platform Cache first and falls back to per-transaction in-memory storage when no Platform Cache scope is available. |
| global static [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) [getPlatformCacheName](#getplatformcachename)() | Returns the name of the platform cache partition used by the framework. |
| global static [UTIL_Cache.Store](/reference/apex/util-cache-store) [inTransaction](#intransaction)() | Convenience factory for transaction-scope cache (in-memory, per-Apex-transaction). |
| global static [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) [isAllocated](#isallocated)() | Checks whether the cache partition has capacity allocated by performing a put/get round-trip on each scope independently. |
| global static [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) [isAvailable](#isavailable)() | Checks if Platform Cache is available (static utility) |
| global static [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) [isAvailable](#isavailable)([UTIL_Cache.Scope](/reference/apex/util-cache-scope) cacheType) | Checks if a specific cache type is available (static utility) |
| global static [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) [isOrgAllocated](#isorgallocated)() | Checks whether the Organisation cache scope has capacity allocated by performing a put/get round-trip probe. |
| global static [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) [isSessionAllocated](#issessionallocated)() | Checks whether the Session cache scope has capacity allocated by performing a put/get round-trip probe. |
| global static [UTIL_Cache.Store](/reference/apex/util-cache-store) [org](#org)() | Convenience factory for Org cache with default partition. |
| global static [UTIL_Cache.Store](/reference/apex/util-cache-store) [partition](#partition)([String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) partitionName) | Convenience factory for a cache partition of your own. |
| global static [UTIL_Cache.Store](/reference/apex/util-cache-store) [session](#session)() | Convenience factory for Session cache with default partition. |

### auto

<div class="apex-member">

```apex
global static UTIL_Cache.Store auto()
```

Creates a new cache instance backed by Platform Cache (Session → Org).
Defaults to the Framework partition defined in UTIL_System.

**Durable-only.** When Platform Cache is unallocated (Session and Org both unavailable),
put/get operations return false / null and OperationResult reports Status.CACHE_UNAVAILABLE
— the failure is loud and visible. This factory does NOT silently fall back to
per-transaction in-memory storage. Use this factory when durability matters (security
keys, cross-transaction state). UTIL_SessionEncryption is the
canonical durability-required caller.

For graceful degradation to per-transaction memory when Platform Cache is missing, use
autoWithTransactionFallback() instead.

**Returns** [UTIL_Cache.Store](/reference/apex/util-cache-store) — New cache instance

**Example**

Basic usage with default configuration:

```apex
UTIL_Cache.Store cache = UTIL_Cache.auto();
cache.put('myKey', 'myValue');
String value = (String)cache.get('myKey');
```

</div>

### autoWithTransactionFallback

<div class="apex-member">

```apex
global static UTIL_Cache.Store autoWithTransactionFallback()
```

Returns a Store that tries Session → Org Platform Cache first and falls back
to per-transaction in-memory storage when no Platform Cache scope is available.

Use this factory when graceful degradation matters more than strict durability — e.g.
memorizing an expensive describe that benefits from cross-request reuse when available
but does not break if Platform Cache is unallocated.

Behavior:

- When Platform Cache is allocated: identical to auto() (Session → Org).

- When neither Platform Cache scope is allocated: the call succeeds via IN_TRANSACTION
scope. OperationResult.cacheTypeUsed reports the actual scope used (IN_TRANSACTION
when the fallback fired) so callers can detect the degraded path.

- Durability-critical callers (security keys, distributed state) MUST use auto(), not
this factory, so a missing Platform Cache still makes them fail instead of quietly falling back to the
transaction cache.

**Returns** [UTIL_Cache.Store](/reference/apex/util-cache-store) — Store with Session → Org → Transaction fallback chain

**Example**

```apex
UTIL_Cache.Store cache = UTIL_Cache.autoWithTransactionFallback();
cache.put('expensiveDescribe', describeResult);
UTIL_Cache.OperationResult result = cache.getLastOperationResult();
if(result.cacheTypeUsed == UTIL_Cache.Scope.IN_TRANSACTION)
{
    // Degraded — Platform Cache unallocated. Cache works for this transaction only.
}
```

</div>

### getPlatformCacheName

<div class="apex-member">

```apex
global static String getPlatformCacheName()
```

Returns the name of the platform cache partition used by the framework.

**Returns** [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) — Cache name prefixed with framework namespace (e.g. 'kern.Library')

**Example**

```apex
String cacheName = UTIL_Cache.getPlatformCacheName();
```

</div>

### inTransaction

<div class="apex-member">

```apex
global static UTIL_Cache.Store inTransaction()
```

Convenience factory for transaction-scope cache (in-memory, per-Apex-transaction).
Use for memorizing expensive describes, lazy-loaded singletons, or any value worth computing
once per request but that does not need to survive into the next transaction.

Unlike SESSION and ORG, transaction cache:

- Never serializes (no JSON round-trips, no compression).

- Has no key-name restrictions imposed by Platform Cache.

- Has no quota or partition allocation requirements.

- Is always available (isCacheAvailable() returns true unconditionally).

- Ignores ttlSeconds — implicit TTL is end-of-transaction.

Storage is shared across every inTransaction()-returned Store within the same transaction;
each Store instance has its own getLastOperationResult() so independent callers do not
trample each other's diagnostic state.

**Returns** [UTIL_Cache.Store](/reference/apex/util-cache-store) — Store backed by the per-transaction in-memory Map

**Example**

```apex
UTIL_Cache.Store cache = UTIL_Cache.inTransaction();
cache.put('expensiveDescribe', myDescribeResult);
Object cached = cache.get('expensiveDescribe');
```

</div>

### isAllocated

<div class="apex-member">

```apex
global static Boolean isAllocated()
```

Checks whether the cache partition has capacity allocated by performing
a put/get round-trip on each scope independently. Tests Org cache first, then Session.
Returns true if either scope can store and retrieve a value.

This approach avoids the AUTO mode fallback issue where Session put reports success
(partition exists) but silently drops data when 0 capacity is allocated.

**Returns** [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) — True if at least one cache scope (Org or Session) is functional

**Example**

```apex
if(UTIL_Cache.isAllocated())
{
    // Org cache or session cache can store and return a value
}
```

</div>

### isAvailable

<div class="apex-member">

```apex
global static Boolean isAvailable()
```

Checks if Platform Cache is available (static utility)

**Returns** [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) — True if any cache type is available

**Example**

Check if Platform Cache is configured in the org:

```apex
if(UTIL_Cache.isAvailable())
{
    UTIL_Cache.Store cache = UTIL_Cache.auto();
    cache.put('myKey', 'myValue');
}
else
{
    // No Platform Cache: compute the value again when you need it
}
```

</div>

<div class="apex-member">

```apex
global static Boolean isAvailable(UTIL_Cache.Scope cacheType)
```

Checks if a specific cache type is available (static utility)

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `cacheType` | [UTIL_Cache.Scope](/reference/apex/util-cache-scope) | The cache type to check |

**Returns** [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) — True if the cache type is available

**Example**

Check if a specific cache type is available:

```apex
if(UTIL_Cache.isAvailable(UTIL_Cache.Scope.SESSION))
{
    // Session cache can be used
}
if(UTIL_Cache.isAvailable(UTIL_Cache.Scope.ORG))
{
    // Org cache can be used
}
```

</div>

### isOrgAllocated

<div class="apex-member">

```apex
global static Boolean isOrgAllocated()
```

Checks whether the Organisation cache scope has capacity allocated by performing
a put/get round-trip probe.

**Returns** [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) — True if Organisation cache can store and retrieve data

**Example**

```apex
if(UTIL_Cache.isOrgAllocated())
{
    // Org cache can store and return a value
}
```

</div>

### isSessionAllocated

<div class="apex-member">

```apex
global static Boolean isSessionAllocated()
```

Checks whether the Session cache scope has capacity allocated by performing
a put/get round-trip probe.

**Returns** [Boolean](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_boolean.htm) — True if Session cache can store and retrieve data

**Example**

```apex
if(UTIL_Cache.isSessionAllocated())
{
    // Session cache can store and return a value
}
```

</div>

### org

<div class="apex-member">

```apex
global static UTIL_Cache.Store org()
```

Convenience factory for Org cache with default partition.
"Easy Button" for the most common use case - persistent org-wide caching.

**Returns** [UTIL_Cache.Store](/reference/apex/util-cache-store) — Org cache instance using framework default partition

**Example**

Quick access to Org cache for persistent data:

```apex
UTIL_Cache.Store cache = UTIL_Cache.org();
cache.put('globalConfig', myConfigObject);
```

</div>

### partition

<div class="apex-member">

```apex
global static UTIL_Cache.Store partition(String partitionName)
```

Convenience factory for a cache partition of your own.
Use it to store values in a partition you created in your org.

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `partitionName` | [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm) | Fully qualified partition name (e.g., 'local.MyPartition') |

**Returns** [UTIL_Cache.Store](/reference/apex/util-cache-store) — Cache instance configured for the specified partition

**Example**

Using a partition you created in your org:

```apex
UTIL_Cache.Store cache = UTIL_Cache.partition('local.MyPartition');
cache.put('myData', myData);
```

</div>

### session

<div class="apex-member">

```apex
global static UTIL_Cache.Store session()
```

Convenience factory for Session cache with default partition.
"Easy Button" for session-scoped caching (max 8 hours).

**Returns** [UTIL_Cache.Store](/reference/apex/util-cache-store) — Session cache instance using framework default partition

**Example**

Quick access to Session cache for temporary user data:

```apex
UTIL_Cache.Store cache = UTIL_Cache.session();
cache.put('userPreferences', prefsMap);
```

</div>

## Inner Classes

| Class | Description |
|-------|-------------|
| [OperationResult](/reference/apex/util-cache-operationresult) | Result of a cache operation with detailed status information |
| [Scope](/reference/apex/util-cache-scope) | Cache type enumeration |
| [Status](/reference/apex/util-cache-status) | Operation status enumeration |
| [Store](/reference/apex/util-cache-store) | Interface for Platform Cache operations |

---
