org.eclipse.microprofile.context.spi

## Interface ContextManagerProvider

    public interface ContextManagerProvider

A provider implementation supplied by the container, which creates and caches instances of `ContextManager` per class loader, which in turn create new instances of `ManagedExecutor.Builder` and `ThreadContext.Builder`.

The container must register its `ContextManagerProvider` implementation via the `register` method, or by providing an implementation via the standard `ServiceLoader` mechanism.

`ContextManagerProvider` implementations that wish to use the `ServiceLoader` registration mechanism must include a file of the following name and location in their jar:

`META-INF/services/org.eclipse.microprofile.context.spi.ContextManagerProvider`

The content of the aforementioned file must be exactly one line, specifying the fully qualified name of a `ContextManagerProvider` implementation that is provided within the JAR file.

If there is no manually registered `ContextManagerProvider` (via `register(ContextManagerProvider)`), any call to `instance()` will look up any `ContextManagerProvider` implementation via the aforementioned `ServiceLoader` mechanism. If there are more than one such implementation registered, the `instance()` method will throw an exception as documented

### Field Summary

Fields
`static AtomicReference<ContextManagerProvider>` `INSTANCE`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
`default ContextManager` `getContextManager()` Gets a `ContextManager` for the current thread-context `ClassLoader`.
`ContextManager` `getContextManager(ClassLoader classloader)` Gets a `ContextManager` for the given `ClassLoader`.
`default ContextManager.Builder` `getContextManagerBuilder()` Returns a new `ContextManager.Builder` to create new `ContextManager` instances.
`static ContextManagerProvider` `instance()` Obtains the `ContextManagerProvider` instance that has been previously registered, or uses `ServiceLoader` to load and register a `ContextManagerProvider` from the current context class loader.
`static ContextManagerProviderRegistration` `register(ContextManagerProvider provider)` Allows the container to register the `ContextManagerProvider` implementation.
`default void` `registerContextManager(ContextManager manager, ClassLoader classLoader)` Registers the given `ContextManager` for the given `ClassLoader`, so that further calls to `getContextManager(ClassLoader)` for the same `ClassLoader` will return this instance instead of creating a new one.
`default void` `releaseContextManager(ContextManager manager)` Releases a `ContextManager` that was previously registered with `registerContextManager(ContextManager, ClassLoader)`.

### Field Detail

#### INSTANCE

    static final AtomicReference<ContextManagerProvider> INSTANCE

### Method Detail

#### instance

    static ContextManagerProvider instance()

Obtains the `ContextManagerProvider` instance that has been previously registered, or uses `ServiceLoader` to load and register a `ContextManagerProvider` from the current context class loader.

Returns:
  the registered `ContextManagerProvider` instance.
Throws:
  `IllegalStateException` - if there are no registered `ContextManagerProvider` and we could not discover any via `ServiceLoader`, or if there are more than one `ServiceLoader` results.

#### register

    static ContextManagerProviderRegistration register(ContextManagerProvider provider)
                                                throws IllegalStateException

Allows the container to register the `ContextManagerProvider` implementation. At most one implementation can be registered at any given point in time. In order to register a different implementation, the container must first unregister its previous implementation.

Parameters:
  `provider` - the provider implementation to register.
Returns:
  registration instance that gives the caller control over unregistering.
Throws:
  `IllegalStateException` - if an implementation is already registered.

#### getContextManager

    default ContextManager getContextManager()

Gets a `ContextManager` for the current thread-context `ClassLoader`. This is equivalent to calling `getContextManager(Thread.currentThread().getContextClassLoader())`, which is the default implementation of this method.

Returns:
  a `ContextManager` for the current thread-context `ClassLoader`.
Throws:
  `IllegalStateException` - if more than one `ThreadContextProvider` provides the same thread context `type`
See Also:
  `getContextManager(ClassLoader)`

#### getContextManager

    ContextManager getContextManager(ClassLoader classloader)

Gets a `ContextManager` for the given `ClassLoader`. If there is already a `ContextManager` registered for the given `ClassLoader` or the context manager provider uses a single fixed set of `ThreadContextProvider` regardless of the class loader, the existing instance will be returned. If not, one will be created, either by provider-specific mechanisms if `ContextManager.Builder` is not supported, or with a `ContextManager.Builder` using the specified `ClassLoader` (with `ContextManager.Builder.forClassLoader(ClassLoader)`) and with `ContextManager.Builder.addDiscoveredThreadContextProviders()` called in order to load all `ThreadContextProvider` discoverable from the given `ClassLoader`. If created, the new `ContextManager` will then be registered for the given `ClassLoader` with `registerContextManager(ContextManager, ClassLoader)`.

Parameters:
  `classloader` - the class loader for which to obtain the context manager.
Returns:
  a `ContextManager` for the given `ClassLoader`.
Throws:
  `IllegalStateException` - if more than one `ThreadContextProvider` provides the same thread context `type`
See Also:
  `ContextManager.Builder.addDiscoveredThreadContextProviders()`, `ContextManager.Builder.build()`, `registerContextManager(ContextManager, ClassLoader)`

#### getContextManagerBuilder

    default ContextManager.Builder getContextManagerBuilder()

Returns a new `ContextManager.Builder` to create new `ContextManager` instances. Watch out that instances created this way will not be automatically registered here, so you need to call `registerContextManager(ContextManager, ClassLoader)` yourself if you need to.

Returns:
  a new `ContextManager.Builder`
Throws:
  `UnsupportedOperationException` - if the `ContextManagerProvider` always uses the same set of `ThreadContextProvider` or is inseparable from the container.

#### registerContextManager

    default void registerContextManager(ContextManager manager,
                                        ClassLoader classLoader)

Registers the given `ContextManager` for the given `ClassLoader`, so that further calls to `getContextManager(ClassLoader)` for the same `ClassLoader` will return this instance instead of creating a new one.

Parameters:
  `manager` - The `ContextManager` to register
  `classLoader` - The `ClassLoader` to register it for
Throws:
  `UnsupportedOperationException` - if the `ContextManagerProvider` always uses the same set of `ThreadContextProvider` or is inseparable from the container.
See Also:
  `getContextManager(ClassLoader)`, `releaseContextManager(ContextManager)`

#### releaseContextManager

    default void releaseContextManager(ContextManager manager)

Releases a `ContextManager` that was previously registered with `registerContextManager(ContextManager, ClassLoader)`.

Parameters:
  `manager` - The `ContextManager` to release
Throws:
  `UnsupportedOperationException` - if the `ContextManagerProvider` always uses the same set of `ThreadContextProvider` or is inseparable from the container.
See Also:
  `registerContextManager(ContextManager, ClassLoader)`