@PublicApi public interface

JiraThreadLocalUtil

com.atlassian.jira.util.thread.JiraThreadLocalUtil
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

The main purpose of this component is to setup and clear ThreadLocal variables that can otherwise interfere with the smooth running of JIRA by leaking resources or allowing stale cached information to survive between requests.

Services that are registered as a JiraService do not need to use this component, because this cleanup is performed automatically as part of the service's execution lifecycle. This should also generally be true of scheduler jobs, such as those executed through SAL's PluginScheduler or the new SchedulerService, but this was not implemented correctly in JIRA v6.3.x, so scheduled jobs should also use this component just to be safe.

Additionally, any plugin that creates its own threads for background processing must use this component to guard its work. Prior to JIRA v6.0, the only way to do this was to access the jira-core class JiraThreadLocalUtils directly.

You must place the cleanup call to postCall(Logger) or postCall(Logger, WarningCallback) in a finally block to guarantee correct behaviour. For example: 

 public void run()
 {
     jiraThreadLocalUtil.preCall();
     try
     {
         // do runnable code here
     }
     finally
     {
         jiraThreadLocalUtil.postCall(log, myWarningCallback);
     }
 }

Summary

Nested Classes
interface JiraThreadLocalUtil.WarningCallback This interface is used as a callback mechanism in the case where "runnable code" has completed and the postCall determines that it did not clean up properly. 
Public Methods
void postCall(Logger log)
This convenience method is equivalent to postCall(log, null).
void postCall(Logger log, JiraThreadLocalUtil.WarningCallback warningCallback)
This should be called in a finally block to clear up ThreadLocals once the runnable stuff has been done.
void preCall()
This should be called before any "runnable code" is called.

Public Methods

public void postCall (Logger log)

This convenience method is equivalent to postCall(log, null).

Parameters
log as for postCall(Logger, WarningCallback)

public void postCall (Logger log, JiraThreadLocalUtil.WarningCallback warningCallback)

This should be called in a finally block to clear up ThreadLocals once the runnable stuff has been done.

Parameters
log the log to write error messages to in case of any problems
warningCallback the callback to invoke in case where problems are detected after the runnable code is done running and its not cleaned up properly. This may be null, in which case those problems are logged as errors.

public void preCall ()

This should be called before any "runnable code" is called. This will setup a clean ThreadLocal environment for the runnable code to execute in.