Package com.atlassian.jira.cache.request

Interface RequestCache<K,V>

@ExperimentalApi @ParametersAreNonnullByDefault public interface RequestCache<K,V>
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.

Since:
v6.4.8
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    V
    get(K key, com.atlassian.cache.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.
    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.

  • Method Details

    • get

      @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.

      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

    • getIfPresent

      @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.

      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

    • get

      @Nonnull V get(K key, com.atlassian.cache.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

    • remove

      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

    • removeAll

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