Session Class

Use the Cache.Session class to add, retrieve, and manage values in the session cache. The session cache is active as long as the user’s Salesforce session is valid (the user is logged in, and the session is not expired).

Cache

Cache Key Format

This table lists the format of the key parameter that some methods in this class take, such as put, get, and contains.

Key Format	Description
namespace.partition.key	Fully qualified key name.
key	Refers to a partition marked as default when the namespace.partition prefix is omitted.
local.partition.key	Use the local prefix to refer to the org’s namespace when the org doesn’t have a namespace defined. If the org has a namespace defined, the local prefix also refers to that org’s namespace.

• If no default partition is specified in the org, calling a cache method without fully qualifying the key name causes a ​Cache.Session.SessionCacheException to be thrown.
• The local prefix in an installed managed package refers to the namespace of the subscriber org and not the package’s namespace. The cache put calls are not allowed in a partition that the invoking class doesn’t own.

This class is the controller for a sample Visualforce page (shown in the subsequent code sample). The cached values are initially added to the cache by the init() method, which the Visualforce page invokes when it loads through the action attribute. The cache keys don’t contain the namespace.partition prefix. They all refer to a default partition in your org. The Visualforce page expects a partition named myPartition. To run this sample, create a default partition in your org with the name myPartition.

The Visualforce page contains four output components. The first three components call get methods on the controller that return the following values from the cache: a date, data based on the MyData inner class, and a counter. The next output component uses the $Cache.Session global variable to get the cached string value for the key named output. Next, the $Cache.Session global variable is used again in the Visualforce page to iterate over the elements of a cached value of type List. The size of the list is also returned.

The Visualforce page also contains two buttons. The Rerender button invokes the go() method on the controller. This method increases the values of the counter and the custom data in the cache. If you click Rerender, the two counters increase by one each time. The go() method retrieves the values of these counters from the cache, increments their values by one, and stores them again in the cache.

The Remove button deletes the date-time value (with key datetime) from the cache. As a result, the value next to Cached datetime: is cleared on the page.

This is the Visualforce page that corresponds to the SessionCacheController class.

This is the output of the page after clicking the Rerender button twice. The counter value could differ in your case if a key named counter was already in the cache before running this sample.

• Session Constants

  The Session class provides a constant that you can use when setting the time-to-live (TTL) value.

• Session Methods

See Also

• Apex Developer Guide: Platform Cache

The Session class provides a constant that you can use when setting the time-to-live (TTL) value.

Constant	Description
MAX_TTL_SECS	Represents the maximum amount of time, in seconds, to keep the cached value in the session cache.

The following are methods for Session. All methods are static.

• contains(key)

  Returns true if the session cache contains a cached value corresponding to the specified key.

• contains(setOfKeys)

  Returns true if the cache contains values for a specified set of keys.

• get(key)

  Returns the cached value corresponding to the specified key from the session cache.

• get(keys)

  Returns the cached values corresponding to the specified set of keys from the session cache.

• get(cacheBuilder, key)

  Returns the cached value corresponding to the specified key from the session cache. Use this method if your cached value is a class that implements the CacheBuilder interface.

• getAvgGetSize()

  Returns the average item size of all the keys fetched from the session cache, in bytes.

• getAvgGetTime()

  Returns the average time taken to get a key from the session cache, in nanoseconds.

• getAvgValueSize()

  Deprecated and available only in API versions 49.0 and earlier. Returns the average item size for keys in the session cache, in bytes.

• getCapacity()

  Returns the percentage of session cache capacity that has been used.

• getKeys()

  Returns all keys that are stored in the session cache and visible to the invoking namespace.

• getMaxGetSize()

  Returns the maximum item size of all the keys fetched from the session cache, in bytes.

• getMaxGetTime()

  Returns the maximum time taken to get a key from the session cache, in nanoseconds.

• getMaxValueSize()

  Deprecated and available only in API versions 49.0 and earlier. Returns the maximum item size for keys in the session cache, in bytes.

• getMissRate()

  Returns the miss rate in the session cache.

• getName()

  Returns the name of the default cache partition.

• getNumKeys()

  Returns the total number of keys in the session cache.

• getPartition(partitionName)

  Returns a partition from the session cache that corresponds to the specified partition name.

• isAvailable()

  Returns true if the session cache is available for use. The session cache isn’t available when an active session isn’t present, such as in asynchronous Apex or code called by asynchronous Apex. For example, if batch Apex causes an Apex trigger to execute, the session cache isn’t available in the trigger because the trigger runs in asynchronous context.

• put(key, value)

  Stores the specified key/value pair as a cached entry in the session cache. The put method can write only to the cache in your org’s namespace.

• put(key, value, visibility)

  Stores the specified key/value pair as a cached entry in the session cache and sets the cached value’s visibility.

• put(key, value, ttlSecs)

  Stores the specified key/value pair as a cached entry in the session cache and sets the cached value’s lifetime.

• put(key, value, ttlSecs, visibility, immutable)

  Stores the specified key/value pair as a cached entry in the session cache. This method also sets the cached value’s lifetime, visibility, and whether it can be overwritten by another namespace.

• remove(key)

  Deletes the cached value corresponding to the specified key from the session cache.

• remove(cacheBuilder, key)

  Deletes the cached value corresponding to the specified key from the session cache. Use this method if your cached value is a class that implements the CacheBuilder interface.

Returns true if the session cache contains a cached value corresponding to the specified key.

public static Boolean contains(String key)

• key:

  Type: String

  A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.

Type: Boolean

true if a cache entry is found. Othewise, false.

Returns true if the cache contains values for a specified set of keys.

public static Map <String, Boolean> contains (Set<String> keys)

• setOfKeys:

  Type: Set <String>

  A set of keys that uniquely identifies cached values. For information about the format of the key name, see Usage.

Type: Map <String, Boolean>

Returns the cache key and corresponding Boolean value indicating that the key entry exists. The Boolean value is false if the key entry doesn’t exist.

The number of input keys cannot exceed the maximum limit of 10.

In this example, the code checks for the presence of multiple keys on the default partition. It fetches the cache key and the corresponding Boolean value for the key entry from the session cache of the default partition.

In this example, the code checks for the presence of multiple keys on different partitions. It fetches the cache key and the corresponding Boolean value for the key entry from the session cache of different partitions.

Returns the cached value corresponding to the specified key from the session cache.

public static Object get(String key)

• key:

  Type: String

  A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.

Type:

Object The cached value as a generic object type. Cast the returned value to the appropriate type.

Because Cache.Session.get() returns an object, we recommend that you cast the returned value to a specific type to facilitate use of the returned value.

If a Cache.Session.get() call doesn’t find the referenced key, it returns null.

Returns the cached values corresponding to the specified set of keys from the session cache.

public static Map <String, Object> get (Set <String> keys)

• keys:

  Type: Set <String>

  A set of keys that uniquely identify cached values. For information about the format of the key name, see Usage.

Type: Map <String, Object>

Returns the cache key and corresponding value. Returns null when no corresponding value is found for an input key.

The number of input keys cannot exceed the maximum limit of 10.

Fetch multiple keys from the session cache of the default partition.

Fetch multiple keys from the session cache of different partitions.

Returns the cached value corresponding to the specified key from the session cache. Use this method if your cached value is a class that implements the CacheBuilder interface.

public static Object get(System.Type cacheBuilder, String key)

• cacheBuilder:

  Type: System.Type

  The Apex class that implements the CacheBuilder interface.

• key:

  Type: String

  A case-sensitive string value that, combined with the class name corresponding to the cacheBuilder parameter, uniquely identifies a cached value.

Type:

Object The cached value as a generic object type. Cast the returned value to the appropriate type.

Because Cache.Session.get(cacheBuilder, key) returns an object, cast the returned value to a specific type to facilitate use of the returned value.

Returns the average item size of all the keys fetched from the session cache, in bytes.

public static Long getAvgGetSize()

Type: Long

Returns the average time taken to get a key from the session cache, in nanoseconds.

public static Long getAvgGetTime()

Type: Long

Deprecated and available only in API versions 49.0 and earlier. Returns the average item size for keys in the session cache, in bytes.

public static Long getAvgValueSize()

Type: Long

Returns the percentage of session cache capacity that has been used.

public static Double getCapacity()

Type: Double

Used cache as a percentage number.

Returns all keys that are stored in the session cache and visible to the invoking namespace.

public static Set<String> getKeys()

Type: Set<String>

A set containing all cache keys.

Returns the maximum item size of all the keys fetched from the session cache, in bytes.

public static Long getMaxGetSize()

Type: Long

Returns the maximum time taken to get a key from the session cache, in nanoseconds.

public static Long getMaxGetTime()

Type: Long

Deprecated and available only in API versions 49.0 and earlier. Returns the maximum item size for keys in the session cache, in bytes.

public static Long getMaxValueSize()

Type: Long

Returns the miss rate in the session cache.

public static Double getMissRate()

Type: Double

Returns the name of the default cache partition.

public String getName()

Type: String

The name of the default cache partition.

Returns the total number of keys in the session cache.

public static Long getNumKeys()

Type: Long

Returns a partition from the session cache that corresponds to the specified partition name.

public static cache.SessionPartition getPartition(String partitionName)

• partitionName:

  Type: String

  A partition name that is qualified by the namespace, for example, namespace.partition.

Type: Cache.SessionPartition

After you get the session partition, you can add and retrieve the partition’s cache values.

Returns true if the session cache is available for use. The session cache isn’t available when an active session isn’t present, such as in asynchronous Apex or code called by asynchronous Apex. For example, if batch Apex causes an Apex trigger to execute, the session cache isn’t available in the trigger because the trigger runs in asynchronous context.

public static Boolean isAvailable()

Type: Boolean

true if the session cache is available. Otherwise, false.

Stores the specified key/value pair as a cached entry in the session cache. The put method can write only to the cache in your org’s namespace.

public static void put(String key, Object value)

• key:

  Type: String

  A string that uniquely identifies the value to be cached. For information about the format of the key name, see Usage.

• value:

  Type:

  Object The value to store in the cache. The cached value must be serializable.

Type: void

Stores the specified key/value pair as a cached entry in the session cache and sets the cached value’s visibility.

public static void put(String key, Object value, Cache.Visibility visibility)

• key:

  Type: String

  A string that uniquely identifies the value to be cached. For information about the format of the key name, see Usage.

• value:

  Type:

  Object The value to store in the cache. The cached value must be serializable.

• visibility:

  Type: Cache.Visibility

  Indicates whether the cached value is available only to Apex code that is executing in the same namespace or to Apex code executing from any namespace.

Type: void

Stores the specified key/value pair as a cached entry in the session cache and sets the cached value’s lifetime.

public static void put(String key, Object value, Integer ttlSecs)

• key:

  Type: String

  A string that uniquely identifies the value to be cached. For information about the format of the key name, see Usage.

• value:

  Type:

  Object The value to store in the cache. The cached value must be serializable.

• ttlSecs:

  Type: Integer

  The amount of time, in seconds, to keep the cached value in the session cache. The cached values remain in the cache as long as the Salesforce session hasn’t expired. The maximum value is 28,800 seconds or eight hours. The minimum value is 300 seconds or five minutes.

Type: void

Stores the specified key/value pair as a cached entry in the session cache. This method also sets the cached value’s lifetime, visibility, and whether it can be overwritten by another namespace.

public static void put(String key, Object value, Integer ttlSecs, cache.Visibility visibility, Boolean immutable)

• key:

  Type: String

  A string that uniquely identifies the value to be cached. For information about the format of the key name, see Usage.

• value:

  Type: Object

  The value to store in the cache. The cached value must be serializable.

• ttlSecs:

  Type: Integer

  The amount of time, in seconds, to keep the cached value in the session cache. The cached values remain in the cache as long as the Salesforce session hasn’t expired. The maximum value is 28,800 seconds or eight hours. The minimum value is 300 seconds or five minutes.

• visibility:

  Type: Cache.Visibility

  Indicates whether the cached value is available only to Apex code that is executing in the same namespace or to Apex code executing from any namespace.

• immutable:

  Type: Boolean

  Indicates whether the cached value can be overwritten by another namespace (false) or not (true).

Type: void

Deletes the cached value corresponding to the specified key from the session cache.

public static Boolean remove(String key)

• key:

  Type: String

  A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.

Type: Boolean

true if the cache value was successfully removed. Otherwise, false.

Deletes the cached value corresponding to the specified key from the session cache. Use this method if your cached value is a class that implements the CacheBuilder interface.

public static Boolean remove(System.Type cacheBuilder, String key)

• cacheBuilder:

  Type: System.Type

  The Apex class that implements the CacheBuilder interface.

• key:

  Type: String

  A case-sensitive string value that, combined with the class name corresponding to the cacheBuilder parameter, uniquely identifies a cached value.

Type: Boolean

true if the cache value was successfully removed. Otherwise, false.