Package 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

Modifier and Type	Field	Description
static java.util.concurrent.atomic.AtomicReference<ContextManagerProvider>	INSTANCE

Method Summary

Modifier and Type	Method	Description
default ContextManager	getContextManager()	Gets a ContextManager for the current thread-context ClassLoader.
ContextManager	getContextManager(java.lang.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, java.lang.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 java.util.concurrent.atomic.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:

java.lang.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 java.lang.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:

java.lang.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:

java.lang.IllegalStateException - if more than one ThreadContextProvider provides the same thread context type

See Also:

getContextManager(ClassLoader)

getContextManager

ContextManager getContextManager(java.lang.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:

java.lang.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:

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

registerContextManager

default void registerContextManager(ContextManager manager,
                                    java.lang.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:

java.lang.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:

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

See Also:

registerContextManager(ContextManager, ClassLoader)