Package org.springframework.security.core.context

# Class ListeningSecurityContextHolderStrategy

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

All Implemented Interfaces:
  `SecurityContextHolderStrategy`

public final class ListeningSecurityContextHolderStrategy extends Object implements SecurityContextHolderStrategy
An API for notifying when the `SecurityContext` changes. Note that this does not notify when the underlying authentication changes. To get notified about authentication changes, ensure that you are using `setContext(org.springframework.security.core.context.SecurityContext)` when changing the authentication like so:

            SecurityContext context = SecurityContextHolder.createEmptyContext();
            context.setAuthentication(authentication);
            SecurityContextHolder.setContext(context);

To add a listener to the existing `SecurityContextHolder`, you can do:

      SecurityContextHolderStrategy original = SecurityContextHolder.getContextHolderStrategy();
      SecurityContextChangedListener listener = new YourListener();
      SecurityContextHolderStrategy strategy = new ListeningSecurityContextHolderStrategy(original, listener);
      SecurityContextHolder.setContextHolderStrategy(strategy);

NOTE: Any object that you supply to the `SecurityContextHolder` is now part of the static context and as such will not get garbage collected. To remove the reference, `reset the strategy` like so:

       SecurityContextHolder.setContextHolderStrategy(original);

This will then allow `YourListener` and its members to be garbage collected.

Since:
  5.6

## Constructor Summary

Constructors
Constructor
Description
`ListeningSecurityContextHolderStrategy(Collection<SecurityContextChangedListener> listeners)`
Construct a `ListeningSecurityContextHolderStrategy` based on `ThreadLocalSecurityContextHolderStrategy`
`ListeningSecurityContextHolderStrategy(SecurityContextChangedListener... listeners)`
Construct a `ListeningSecurityContextHolderStrategy` based on `ThreadLocalSecurityContextHolderStrategy`
`ListeningSecurityContextHolderStrategy(SecurityContextHolderStrategy delegate, Collection<SecurityContextChangedListener> listeners)`
Construct a `ListeningSecurityContextHolderStrategy`
`ListeningSecurityContextHolderStrategy(SecurityContextHolderStrategy delegate, SecurityContextChangedListener... listeners)`
Construct a `ListeningSecurityContextHolderStrategy`

## Method Summary

Modifier and Type
Method
Description
`void`
`clearContext()`
Clears the current context.
`SecurityContext`
`createEmptyContext()`
Creates a new, empty context implementation, for use by `SecurityContextRepository` implementations, when creating a new context for the first time.
`SecurityContext`
`getContext()`
Obtains the current context.
`Supplier<SecurityContext>`
`getDeferredContext()`
Obtains a `Supplier` that returns the current context.
`void`
`setContext(SecurityContext context)`
Sets the current context.
`void`
`setDeferredContext(Supplier<SecurityContext> deferredContext)`
Sets a `Supplier` that will return the current context.

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

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

## Constructor Details

### ListeningSecurityContextHolderStrategy

public ListeningSecurityContextHolderStrategy(Collection<SecurityContextChangedListener> listeners)
Construct a `ListeningSecurityContextHolderStrategy` based on `ThreadLocalSecurityContextHolderStrategy`

Parameters:
  `listeners` - the listeners that should be notified when the `SecurityContext` is `set` or `cleared`
Since:
  5.7

### ListeningSecurityContextHolderStrategy

public ListeningSecurityContextHolderStrategy(SecurityContextChangedListener... listeners)
Construct a `ListeningSecurityContextHolderStrategy` based on `ThreadLocalSecurityContextHolderStrategy`

Parameters:
  `listeners` - the listeners that should be notified when the `SecurityContext` is `set` or `cleared`
Since:
  5.7

### ListeningSecurityContextHolderStrategy

public ListeningSecurityContextHolderStrategy(SecurityContextHolderStrategy delegate, Collection<SecurityContextChangedListener> listeners)
Construct a `ListeningSecurityContextHolderStrategy`

Parameters:
  `listeners` - the listeners that should be notified when the `SecurityContext` is `set` or `cleared`
  `delegate` - the underlying `SecurityContextHolderStrategy`

### ListeningSecurityContextHolderStrategy

public ListeningSecurityContextHolderStrategy(SecurityContextHolderStrategy delegate, SecurityContextChangedListener... listeners)
Construct a `ListeningSecurityContextHolderStrategy`

Parameters:
  `listeners` - the listeners that should be notified when the `SecurityContext` is `set` or `cleared`
  `delegate` - the underlying `SecurityContextHolderStrategy`

## Method Details

### clearContext

public void clearContext()
Clears the current context.

Specified by:
  `clearContext` in interface `SecurityContextHolderStrategy`

### getContext

public SecurityContext getContext()
Obtains the current context.

Specified by:
  `getContext` in interface `SecurityContextHolderStrategy`
Returns:
  a context (never `null` - create a default implementation if necessary)

### getDeferredContext

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

Specified by:
  `getDeferredContext` in interface `SecurityContextHolderStrategy`
Returns:
  a `Supplier` that returns the current context (never `null` - create a default implementation if necessary)

### setContext

public void setContext(SecurityContext context)
Sets the current context.

Specified by:
  `setContext` in interface `SecurityContextHolderStrategy`
Parameters:
  `context` - to the new argument (should never be `null`, although implementations must check if `null` has been passed and throw an `IllegalArgumentException` in such cases)

### setDeferredContext

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

Specified by:
  `setDeferredContext` in interface `SecurityContextHolderStrategy`
Parameters:
  `deferredContext` - a `Supplier` that returns the `SecurityContext`

### createEmptyContext

public SecurityContext createEmptyContext()
Creates a new, empty context implementation, for use by `SecurityContextRepository` implementations, when creating a new context for the first time.

Specified by:
  `createEmptyContext` in interface `SecurityContextHolderStrategy`
Returns:
  the empty context.