Documentation: Plugin should call clearRequestCache for JiraAuthenticationContextImpl after execution

Problem Definition

JIRA caches different data in JiraAuthenticationContextImpl for each request in ThreadLocal. That data is cleared after each request by Jira in case of HTTP requests, so there is no problem there.
When you use com.atlassian.jira.security.JiraAuthenticationContext directly or indirectly from your code in separate thread, you need to clear the cache. In other case you will have thread which leaks ThreadLocal and holds large amount of memory in com.atlassian.jira.bc.issue.search.QueryCacheImpl$QueryCacheLiteralsKey.

Example of indirect use of JiraAuthenticationContext:

long hitcount = searchService.searchCount(user, pr.getQuery());

Suggested Solution

• Create/Update public documentation for developers which references JiraThreadLocalUtil or OffRequestThreadExecutor.
  • Explain use cases of JiraThreadLocalUtil and share examples of proper API method.
• As a workaround, you will need to add a cache clear somewhere to prevent these objects from accumulating over time. Here's some general docs on this api:
  • https://docs.atlassian.com/software/jira/docs/api/7.2.0/com/atlassian/jira/security/JiraAuthenticationContextImpl.html#clearRequestCache
• An example of how plugin vendor implemented this: TransitionWorkflowExtended.html

     try
     {
         // Execute as specified user
         authenticationContext.setUser(user);
         JiraAuthenticationContextImpl.clearRequestCache();
  
         // We have the workflow transition id.
         // Now we need to process and validate all the fields that can be set during the transition
         WorkflowTransitionUtil workflowTransitionUtil = (WorkflowTransitionUtil) JiraUtils.loadComponent(WorkflowTransitionUtilAddOnImpl.class);
         workflowTransitionUtil.setIssue(issue);
         workflowTransitionUtil.setAction(actionId);
         workflowTransitionUtil.setParams(params);
  
         // Validate input
         JellyUtils.processErrorCollection(workflowTransitionUtil.validate());
  
         // Progress the issue through workflow
         JellyUtils.processErrorCollection(workflowTransitionUtil.progress());
     }
     finally
     {
         // Restore the user
         authenticationContext.setUser(previousUser);
         JiraAuthenticationContextImpl.clearRequestCache();
     }