@ExperimentalApi @ParametersAreNonnullByDefault public interface

RequestCache

com.atlassian.jira.cache.request.RequestCache<K, V>

@ExperimentalApi

This interface is considered usable by external developers but its contracts have not stabilized.

Experimental APIs may be changed at any time before being marked @Internal or @PublicApi.

Class Overview

Represents a "request-scoped" cache local to the calling thread.

Note that "request" here means a short-lived job including but not limited to HTTP requests and scheduled jobs.

WARNING: Request-scoped caches revert to read-through behaviour if a thread attempts to access one without first establishing a request context. Under those conditions, calls to get(Object) and get(Object, Supplier) effectively always "miss" and use the CacheLoader or Supplier respectively. This can have a serious performance impact, so background threads are advised to create a temporary request context explicitly with JiraThreadLocalUtil when performing JQL queries, examining issue data, or any other significant piece of work.

WARNING: Request caches are effectively unbounded. In the unusual case of a single request examining a large number of issues or any similarly large piece of work, it is strongly recommended that it be broken into batches so that the request caches can be explicitly cleared between the batches.

See Also

Summary

Public Methods
@Nonnull V get(K key, Supplier<V> supplier)
Retrieves the value for a key by retrieving it from the request cache if possible and by using the specified supplier, otherwise.
@Nonnull V get(K key)
Retrieves the value for a key by retrieving it from the request cache if possible and by using the request cache's cache loader, otherwise.
@Nullable V getIfPresent(K key)
Retrieves the value for a key by retrieving it from the request cache if possible and otherwise giving up and returning null.
void remove(K key)
Discards any value cached for the given key.
void removeAll()
Discards all values from this request cache.

Public Methods

@Nonnull public V get (K key, Supplier<V> supplier)

Retrieves the value for a key by retrieving it from the request cache if possible and by using the specified supplier, otherwise.

This is useful when the key used to identify the data does not have enough information to construct the value or when using it would be less efficient. For example, we may have a whole Issue available but only want to use its id as the key for the request cache. If the cache loader then had to use the IssueManager to reload the issue's data, this would be very wasteful. But the Supplier can hold onto the Issue that we already have and still allow just the id to be used as the cache key.

When there is no request-scoped context defined, the request cache is always empty and the value is lazily loaded. If there is a request-scoped context but the value is not yet in the cache, it is lazily loaded and the result is saved to the cache.

Parameters
key the key for which to retrieve a value
supplier a supplier that can load the value if it is not in the cache; this will be used instead of the CacheLoader supplied when the cache was created. The Supplier must not return a null value.
Returns
  • the retrieved or loaded value

@Nonnull public V get (K key)

Retrieves the value for a key by retrieving it from the request cache if possible and by using the request cache's cache loader, otherwise.

When there is no request-scoped context defined, the request cache is always empty and the value is lazily loaded. If there is a request-scoped context but the value is not yet in the cache, it is lazily loaded and the result is saved to the cache.

Parameters
key the key for which to retrieve a value
Returns
  • the retrieved or loaded value

@Nullable public V getIfPresent (K key)

Retrieves the value for a key by retrieving it from the request cache if possible and otherwise giving up and returning null.

When there is no request-scoped context defined or if the value is not already in the request cache, then null is returned without attempting to load the value.

Parameters
key the key for which to retrieve a value
Returns
  • the value, if an only if it is already present in the cache

public void remove (K key)

Discards any value cached for the given key. If there is no request-scoped context active, then this method has no effect.

Parameters
key the key to be invalidated / removed from the cache

public void removeAll ()

Discards all values from this request cache. If there is no request-scoped context active, then this method has no effect.