MicroProfile Context Propagation 1.3 · org.eclipse.microprofile.context.spi.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

Modifier and Type	Field and Description
public static final AtomicReference<ContextManagerProvider>	INSTANCE

Method Summary

Modifier and Type	Method and Description
public default ContextManager	Returns: a `ContextManager` for the current thread-context `ClassLoader`. getContextManager() Gets a `ContextManager` for the current thread-context `ClassLoader`.
public ContextManager	Returns: a `ContextManager` for the given `ClassLoader`. getContextManager(ClassLoader the class loader for which to obtain the context manager. classloader) Gets a `ContextManager` for the given `ClassLoader`.
public default ContextManager.Builder	Returns: a new `ContextManager.Builder` getContextManagerBuilder() Returns a new `ContextManager.Builder` to create new `ContextManager` instances.
public static ContextManagerProvider	Returns: the registered `ContextManagerProvider` instance. 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.
public static ContextManagerProviderRegistration	Returns: registration instance that gives the caller control over unregistering. register(ContextManagerProvider the provider implementation to register. provider) Allows the container to register the `ContextManagerProvider` implementation.
public default void	registerContextManager(ContextManager The `ContextManager` to register manager, ClassLoader The `ClassLoader` to register it for 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.
public default void	releaseContextManager(ContextManager The `ContextManager` to release manager) Releases a `ContextManager` that was previously registered with `registerContextManager(ContextManager, ClassLoader)`.

Field Detail

INSTANCE	back to summary
public static final AtomicReference<ContextManagerProvider> INSTANCE

Method Detail

getContextManager back to summary

getContextManager	back to summary
public 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:ContextManager a `ContextManager` for the current thread-context `ClassLoader`. Exceptions IllegalStateException: if more than one `ThreadContextProvider` provides the same thread context `type` See Also `getContextManager(ClassLoader)`

public 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:ContextManager

a ContextManager for the current thread-context ClassLoader.

Exceptions

IllegalStateException:: if more than one ThreadContextProvider provides the same thread context type

See Also

getContextManager(ClassLoader)

getContextManager back to summary

getContextManager	back to summary
public 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:ClassLoader the class loader for which to obtain the context manager. Returns:ContextManager a `ContextManager` for the given `ClassLoader`. Exceptions IllegalStateException: if more than one `ThreadContextProvider` provides the same thread context `type` See Also `ContextManager.Builder#addDiscoveredThreadContextProviders()`, `ContextManager.Builder#build()`, `registerContextManager(ContextManager, ClassLoader)`

public 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:ClassLoader: the class loader for which to obtain the context manager.

Returns:ContextManager

a ContextManager for the given ClassLoader.

Exceptions

IllegalStateException:: if more than one ThreadContextProvider provides the same thread context type

getContextManagerBuilder back to summary

getContextManagerBuilder	back to summary
public 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:ContextManager.Builder a new `ContextManager.Builder` Exceptions UnsupportedOperationException: if the `ContextManagerProvider` always uses the same set of `ThreadContextProvider` or is inseparable from the container.

public 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:ContextManager.Builder

a new ContextManager.Builder

Exceptions

UnsupportedOperationException:: if the ContextManagerProvider always uses the same set of ThreadContextProvider or is inseparable from the container.

instance back to summary

instance	back to summary
public 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:ContextManagerProvider the registered `ContextManagerProvider` instance. Exceptions IllegalStateException: if there are no registered `ContextManagerProvider` and we could not discover any via `ServiceLoader`, or if there are more than one `ServiceLoader` results.

public 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:ContextManagerProvider

the registered ContextManagerProvider instance.

Exceptions

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	back to summary
public 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:ContextManagerProvider the provider implementation to register. Returns:ContextManagerProviderRegistration registration instance that gives the caller control over unregistering. Exceptions IllegalStateException: if an implementation is already registered.

public 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:ContextManagerProvider: the provider implementation to register.

Returns:ContextManagerProviderRegistration

registration instance that gives the caller control over unregistering.

Exceptions

IllegalStateException:: if an implementation is already registered.

registerContextManager back to summary

registerContextManager	back to summary
public 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:ContextManager The `ContextManager` to register classLoader:ClassLoader The `ClassLoader` to register it for Exceptions UnsupportedOperationException: if the `ContextManagerProvider` always uses the same set of `ThreadContextProvider` or is inseparable from the container. See Also `getContextManager(ClassLoader)`, `releaseContextManager(ContextManager)`

public 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:ContextManager: The ContextManager to register
classLoader:ClassLoader: The ClassLoader to register it for

Exceptions

UnsupportedOperationException:: if the ContextManagerProvider always uses the same set of ThreadContextProvider or is inseparable from the container.

releaseContextManager back to summary

releaseContextManager	back to summary
public default void releaseContextManager(ContextManager manager) Releases a `ContextManager` that was previously registered with `registerContextManager(ContextManager, ClassLoader)`. Parameters manager:ContextManager The `ContextManager` to release Exceptions UnsupportedOperationException: if the `ContextManagerProvider` always uses the same set of `ThreadContextProvider` or is inseparable from the container. See Also `registerContextManager(ContextManager, ClassLoader)`

public default void releaseContextManager(ContextManager manager)

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

Parameters

manager:ContextManager: The ContextManager to release

Exceptions

UnsupportedOperationException:: if the ContextManagerProvider always uses the same set of ThreadContextProvider or is inseparable from the container.

public Interface ContextManagerProvider

Field Summary

Method Summary

Field Detail

Method Detail