Chapter 3. Set Up Expiration

3.1. About Expiration

Red Hat JBoss Data Grid uses expiration to attach one or both of the following values to an entry:

  • A lifespan value.
  • A maximum idle time value.

Expiration can be specified on a per-entry or per-cache basis and the per-entry configuration overrides per-cache configurations. If expiration is configured at the cache level, then the expiration defaults apply to all entries which do not explicitly specify a lifespan or max-idle value.

If expiration is not configured at the cache level, cache entries are created immortal (i.e. they will never expire) by default. Any entries that have lifespan or max-idle defined are mortal, as they will eventually be removed from the cache once one of these conditions are met.

Expired entries, unlike evicted entries, are removed globally, which removes them from memory, cache stores and the cluster.

Expiration automates the removal of entries that have not been used for a specified period of time from the memory. Expiration and eviction are different because:

  • expiration removes entries based on the period they have been in memory. Expiration only removes entries when the life span period concludes or when an entry has been idle longer than the specified idle time.
  • eviction removes entries based on how recently (and often) they are used. Eviction only removes entries when too many entries are present in the memory. If a cache store has been configured, evicted entries are persisted in the cache store.
Important

It is not recommended to use max-idle in clustered mode. This is because max-idle is not updated on all nodes at the same time, and thus JBoss Data Grid can’t reliably expire entries across the cluster. For more information on the limitations of using max-idle in clustered mode see this knowledgebase solution.

3.2. Expiration Operations

Expiration in Red Hat JBoss Data Grid allows you to set a life span or maximum idle time value for each key/value pair stored in the cache.

The life span or maximum idle time can be set to apply cache-wide or defined for each key/value pair using the cache API. The life span (lifespan) or maximum idle time (max-idle) defined for an individual key/value pair overrides the cache-wide default for the entry in question.

3.3. Eviction and Expiration Comparison

Expiration is a top-level construct in Red Hat JBoss Data Grid, and is represented in the global configuration, as well as the cache API.

Eviction is limited to the cache instance it is used in, whilst expiration is cluster-wide. Expiration life spans (lifespan) and idle time (max-idle) values are replicated alongside each cache entry.

3.4. Cache Entry Expiration Behavior

Red Hat JBoss Data Grid does not guarantee that an entry is removed immediately upon timeout. Instead, a number of mechanisms are used in collaboration to ensure efficient removal. An expired entry is removed from the cache when either:

  • An entry is passivated/overflowed to disk and is discovered to have expired.
  • The expiration maintenance thread discovers that an entry it has found is expired.

If a user requests an entry that is expired but not yet removed, a null value is sent to the user. This mechanism ensures that the user never receives an expired entry. The entry is eventually removed by the expiration thread.

3.5. Configure Expiration

In Red Hat JBoss Data Grid, expiration is configured in a manner similar to eviction.

Configure Expiration

  1. Add the Expiration Tag

    Add the expiration tag to your project’s cache tags as follows: 

    <expiration />

  2. Set the Expiration Lifespan

    Set the lifespan value to set the period of time (in milliseconds) an entry can remain in memory. The following is an example of this step: 

    <expiration lifespan="1000" />

  3. Set the Maximum Idle Time

    Set the time that entries are allowed to remain idle (unused) after which they are removed (in milliseconds). The default value is -1 for unlimited time. 

    <expiration lifespan="1000" max-idle="1000" />

3.6. Troubleshooting Expiration

If expiration does not appear to be working, it may be due to an entry being marked for expiration but not being removed.

Multiple-cache operations such as put() are passed a life span value as a parameter. This value defines the interval after which the entry must expire. In cases where eviction is not configured and the life span interval expires, it can appear as if Red Hat JBoss Data Grid has not removed the entry. For example, when viewing JMX statistics, such as the number of entries , you may see an out of date count, or the persistent store associated with JBoss Data Grid may still contain this entry. Behind the scenes, JBoss Data Grid has marked it as an expired entry, but has not removed it. Removal of such entries happens as follows:

  • An entry is passivated/overflowed to disk and is discovered to have expired.
  • The expiration maintenance thread discovers that an entry it has found is expired.

Any attempt to use get() or containsKey() for the expired entry causes JBoss Data Grid to return a null value. The expired entry is later removed by the expiration thread.