Package org.springframework.security.core.context

# Class SecurityContextHolder

java.lang.Object
org.springframework.security.core.context.SecurityContextHolder

public class SecurityContextHolder extends Object
Associates a given `SecurityContext` with the current execution thread.

This class provides a series of static methods that delegate to an instance of `SecurityContextHolderStrategy`. The purpose of the class is to provide a convenient way to specify the strategy that should be used for a given JVM. This is a JVM-wide setting, since everything in this class is `static` to facilitate ease of use in calling code.

To specify which strategy should be used, you must provide a mode setting. A mode setting is one of the three valid `MODE_` settings defined as `static final` fields, or a fully qualified classname to a concrete implementation of `SecurityContextHolderStrategy` that provides a public no-argument constructor.

There are two ways to specify the desired strategy mode `String`. The first is to specify it via the system property keyed on `SYSTEM_PROPERTY`. The second is to call `setStrategyName(String)` before using the class. If neither approach is used, the class will default to using `MODE_THREADLOCAL`, which is backwards compatible, has fewer JVM incompatibilities and is appropriate on servers (whereas `MODE_GLOBAL` is definitely inappropriate for server use).

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`MODE_GLOBAL`
`static final String`
`MODE_INHERITABLETHREADLOCAL`
`static final String`
`MODE_THREADLOCAL`
`static final String`
`SYSTEM_PROPERTY`

## Constructor Summary

Constructors
Constructor
Description
`SecurityContextHolder()`

## Method Summary

Modifier and Type
Method
Description
`static void`
`clearContext()`
Explicitly clears the context value from the current thread.
`static SecurityContext`
`createEmptyContext()`
Delegates the creation of a new, empty context to the configured strategy.
`static SecurityContext`
`getContext()`
Obtain the current `SecurityContext`.
`static SecurityContextHolderStrategy`
`getContextHolderStrategy()`
Allows retrieval of the context strategy.
`static Supplier<SecurityContext>`
`getDeferredContext()`
Obtains a `Supplier` that returns the current context.
`static int`
`getInitializeCount()`
Primarily for troubleshooting purposes, this method shows how many times the class has re-initialized its `SecurityContextHolderStrategy`.
`static void`
`setContext(SecurityContext context)`
Associates a new `SecurityContext` with the current thread of execution.
`static void`
`setContextHolderStrategy(SecurityContextHolderStrategy strategy)`
Use this `SecurityContextHolderStrategy`.
`static void`
`setDeferredContext(Supplier<SecurityContext> deferredContext)`
Sets a `Supplier` that will return the current context.
`static void`
`setStrategyName(String strategyName)`
Changes the preferred strategy.
`String`
`toString()`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Field Details

### MODE_THREADLOCAL

public static final String MODE_THREADLOCAL

See Also:
  - Constant Field Values

### MODE_INHERITABLETHREADLOCAL

public static final String MODE_INHERITABLETHREADLOCAL

See Also:
  - Constant Field Values

### MODE_GLOBAL

public static final String MODE_GLOBAL

See Also:
  - Constant Field Values

### SYSTEM_PROPERTY

public static final String SYSTEM_PROPERTY

See Also:
  - Constant Field Values

## Constructor Details

### SecurityContextHolder

public SecurityContextHolder()

## Method Details

### clearContext

public static void clearContext()
Explicitly clears the context value from the current thread.

### getContext

public static SecurityContext getContext()
Obtain the current `SecurityContext`.

Returns:
  the security context (never `null`)

### getDeferredContext

public static Supplier<SecurityContext> getDeferredContext()
Obtains a `Supplier` that returns the current context.

Returns:
  a `Supplier` that returns the current context (never `null` - create a default implementation if necessary)
Since:
  5.8

### getInitializeCount

public static int getInitializeCount()
Primarily for troubleshooting purposes, this method shows how many times the class has re-initialized its `SecurityContextHolderStrategy`.

Returns:
  the count (should be one unless you've called `setStrategyName(String)` or `setContextHolderStrategy(SecurityContextHolderStrategy)` to switch to an alternate strategy).

### setContext

public static void setContext(SecurityContext context)
Associates a new `SecurityContext` with the current thread of execution.

Parameters:
  `context` - the new `SecurityContext` (may not be `null`)

### setDeferredContext

public static void setDeferredContext(Supplier<SecurityContext> deferredContext)
Sets a `Supplier` that will return the current context. Implementations can override the default to avoid invoking `Supplier.get()`.

Parameters:
  `deferredContext` - a `Supplier` that returns the `SecurityContext`
Since:
  5.8

### setStrategyName

public static void setStrategyName(String strategyName)
Changes the preferred strategy. Do NOT call this method more than once for a given JVM, as it will re-initialize the strategy and adversely affect any existing threads using the old strategy.

Parameters:
  `strategyName` - the fully qualified class name of the strategy that should be used.

### setContextHolderStrategy

public static void setContextHolderStrategy(SecurityContextHolderStrategy strategy)
Use this `SecurityContextHolderStrategy`. Call either `setStrategyName(String)` or this method, but not both. This method is not thread safe. Changing the strategy while requests are in-flight may cause race conditions. `SecurityContextHolder` maintains a static reference to the provided `SecurityContextHolderStrategy`. This means that the strategy and its members will not be garbage collected until you remove your strategy. To ensure garbage collection, remember the original strategy like so:

         SecurityContextHolderStrategy original = SecurityContextHolder.getContextHolderStrategy();
         SecurityContextHolder.setContextHolderStrategy(myStrategy);

And then when you are ready for `myStrategy` to be garbage collected you can do:

         SecurityContextHolder.setContextHolderStrategy(original);

Parameters:
  `strategy` - the `SecurityContextHolderStrategy` to use
Since:
  5.6

### getContextHolderStrategy

public static SecurityContextHolderStrategy getContextHolderStrategy()
Allows retrieval of the context strategy. See SEC-1188.

Returns:
  the configured strategy for storing the security context.

### createEmptyContext

public static SecurityContext createEmptyContext()
Delegates the creation of a new, empty context to the configured strategy.

### toString

public String toString()

Overrides:
  `toString` in class `Object`