ContextManager.java
- /*
- * *************************************************************************************************************************************************************
- *
- * TheseFoolishThings: Miscellaneous utilities
- * http://tidalwave.it/projects/thesefoolishthings
- *
- * Copyright (C) 2009 - 2024 by Tidalwave s.a.s. (http://tidalwave.it)
- *
- * *************************************************************************************************************************************************************
- *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
- *
- * *************************************************************************************************************************************************************
- *
- * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
- * git clone https://github.com/tidalwave-it/thesefoolishthings-src
- *
- * *************************************************************************************************************************************************************
- */
- package it.tidalwave.util;
- import javax.annotation.Nonnull;
- import java.util.List;
- import java.util.Optional;
- import java.util.ServiceLoader;
- import java.util.function.Supplier;
- import it.tidalwave.role.spi.ContextManagerProvider;
- import static it.tidalwave.role.impl.ServiceLoaderLocator.lazySupplierOf;
- /***************************************************************************************************************************************************************
- *
- * A facility to register and unregister global and local DCI contexts.
- *
- * @author Fabrizio Giudici
- *
- **************************************************************************************************************************************************************/
- public interface ContextManager
- {
- /***********************************************************************************************************************************************************
- * A locator for the {@link ContextManager} which uses the {@link ServiceLoader} facility to be independent of
- * any DI framework.
- *
- * This locator caches the internal reference and this is ok for production use; during tests, since multiple
- * contexts are typically created and destroyed for each test, you should call {@link #reset()} after each test
- * has been completed.
- **********************************************************************************************************************************************************/
- static class Inner
- {
- private static final LazySupplier<ContextManager> CONTEXT_MANAGER_REF =
- LazySupplier.of(() -> Inner.CONTEXT_MANAGER_PROVIDER_REF.get().getContextManager());
- private static final LazySupplier<ContextManagerProvider> CONTEXT_MANAGER_PROVIDER_REF =
- lazySupplierOf(ContextManagerProvider.class);
- }
- /***********************************************************************************************************************************************************
- * Returns a singleton instance.
- *
- * @return the singleton instance
- **********************************************************************************************************************************************************/
- @Nonnull
- public static ContextManager getInstance()
- {
- return Inner.CONTEXT_MANAGER_REF.get();
- }
- /***********************************************************************************************************************************************************
- * <b>This method is for testing only.</b> Sets the global {@link ContextManagerProvider}. See note about
- * {@link #reset()}.
- *
- * @param provider the provider
- * @see #reset()
- **********************************************************************************************************************************************************/
- public static void set (@Nonnull final ContextManagerProvider provider)
- {
- Inner.CONTEXT_MANAGER_REF.clear();
- Inner.CONTEXT_MANAGER_PROVIDER_REF.set(provider);
- }
- /***********************************************************************************************************************************************************
- * <b>This method is for testing only.</b> Resets the global {@link ContextManagerProvider}; it must be called
- * at the test completion whenever {@link #set(ContextManagerProvider)} has been called, to avoid polluting the
- * context of further tests.
- *
- * @see #set(ContextManagerProvider)
- **********************************************************************************************************************************************************/
- public static void reset()
- {
- Inner.CONTEXT_MANAGER_REF.clear();
- Inner.CONTEXT_MANAGER_PROVIDER_REF.clear();
- }
- @FunctionalInterface
- public static interface RunnableWithException<E extends Throwable>
- {
- public void run()
- throws E;
- }
- @FunctionalInterface
- public static interface SupplierWithException<T, E extends Throwable>
- {
- public T get()
- throws E;
- }
- /***********************************************************************************************************************************************************
- * Returns the list of current contexts, ordered by their priority.
- *
- * @return the list of current contexts
- **********************************************************************************************************************************************************/
- @Nonnull
- public List<Object> getContexts();
- /***********************************************************************************************************************************************************
- * Finds a current context instance of the given type.
- *
- * @param <T> the static context type
- * @param contextType the dynamic context type
- * @return the requested context
- **********************************************************************************************************************************************************/
- @Nonnull
- public <T> Optional<T> findContextOfType (@Nonnull Class<T> contextType);
- /***********************************************************************************************************************************************************
- * Adds a global context.
- *
- * @param context the new context
- **********************************************************************************************************************************************************/
- public void addGlobalContext (@Nonnull Object context);
- /***********************************************************************************************************************************************************
- * Removes a global context.
- *
- * @param context the context
- **********************************************************************************************************************************************************/
- public void removeGlobalContext (@Nonnull Object context);
- /***********************************************************************************************************************************************************
- * Adds a local context.
- *
- * @param context the new context
- **********************************************************************************************************************************************************/
- public void addLocalContext (@Nonnull Object context);
- /***********************************************************************************************************************************************************
- * Removes a local context.
- *
- * @param context the context
- **********************************************************************************************************************************************************/
- public void removeLocalContext (@Nonnull Object context);
- /***********************************************************************************************************************************************************
- * Runs a {@link Task} associated with a new local context.
- *
- * @param <V> the type of the returned value
- * @param <T> the type of the exception that can be thrown
- * @param context the context
- * @param task the task
- * @return the value produced by the task
- * @throws T the exception(s) thrown by the task
- * @deprecated Use {@link #runWithContexts(Runnable, Object...)} or {@link #runWithContexts(Supplier, Object...)}
- **********************************************************************************************************************************************************/
- @Deprecated
- public default <V, T extends Throwable> V runWithContext (@Nonnull final Object context,
- @Nonnull final Task<V, T> task)
- throws T
- {
- return runWithContexts(List.of(context), task);
- }
- /***********************************************************************************************************************************************************
- * Runs a {@link Task} associated with a new bunch of local contexts.
- *
- * @param <V> the type of the returned value
- * @param <T> the type of the exception that can be thrown
- * @param contexts the contexts
- * @param task the task
- * @return the value produced by the task
- * @throws T the exception(s) thrown by the task
- * @deprecated Use {@link #runWithContexts(Runnable, Object...)} or {@link #runWithContexts(Supplier, Object...)}
- **********************************************************************************************************************************************************/
- @Deprecated
- public default <V, T extends Throwable> V runWithContexts (@Nonnull final List<Object> contexts,
- @Nonnull final Task<V, T> task)
- throws T
- {
- return runEWithContexts(task::run, contexts.toArray());
- }
- /***********************************************************************************************************************************************************
- * Runs a task associated with a new local context. This variant fits functional interfaces.
- *
- * @param <V> the type of the returned value of the task
- * @param context the context
- * @param task the task
- * @return the value produced by the task
- * @deprecated Use {@link #runWithContexts(Runnable, Object...)} or {@link #runWithContexts(Supplier, Object...)}
- **********************************************************************************************************************************************************/
- @Deprecated
- public default <V> V runWithContext (@Nonnull final Object context, @Nonnull final Supplier<V> task)
- {
- return runWithContexts(task, context);
- }
- /***********************************************************************************************************************************************************
- * Runs a task associated with a new bunch of local contexts. This variant fits functional interfaces.
- *
- * @param <V> the type of the returned value
- * @param contexts the contexts
- * @param task the task
- * @return the value produced by the task
- * @deprecated Use {@link #runWithContexts(Runnable, Object...)} or {@link #runWithContexts(Supplier, Object...)}
- **********************************************************************************************************************************************************/
- @Deprecated
- public default <V> V runWithContexts (@Nonnull final List<Object> contexts, @Nonnull final Supplier<V> task)
- {
- return runWithContexts(task, contexts.toArray());
- }
- /***********************************************************************************************************************************************************
- * Calls a runnable with some local contexts. This method fits functional interfaces.
- *
- * @param runnable the runnable
- * @param contexts the contexts
- * @since 3.2-ALPHA-12
- **********************************************************************************************************************************************************/
- public default void runWithContexts (@Nonnull final Runnable runnable, @Nonnull final Object ... contexts)
- {
- final SupplierWithException<Void, RuntimeException> se = () ->{ runnable.run(); return null; };
- runEWithContexts(se, contexts);
- }
- /***********************************************************************************************************************************************************
- * Calls a supplier with some local contexts. This method fits functional interfaces.
- *
- * @param <T> the type of the result
- * @param supplier the supplier
- * @param contexts the contexts
- * @return the value returned by the supplier
- * @since 3.2-ALPHA-12
- **********************************************************************************************************************************************************/
- @Nonnull
- public default <T> T runWithContexts (@Nonnull final Supplier<T> supplier, @Nonnull final Object ... contexts)
- {
- final SupplierWithException<T, RuntimeException> se = supplier::get;
- return runEWithContexts(se, contexts);
- }
- /***********************************************************************************************************************************************************
- * Calls a runnable with some local contexts. This method fits functional interfaces.
- *
- * @param <E> the type of the thrown exception
- * @param runnable the runnable to call
- * @param contexts the contexts
- * @throws E the original exception thrown by task
- * @since 3.2-ALPHA-12
- **********************************************************************************************************************************************************/
- public default <E extends Throwable> void runEWithContexts (@Nonnull final RunnableWithException<E> runnable,
- @Nonnull final Object ... contexts)
- throws E
- {
- final SupplierWithException<Void, E> se = () ->{ runnable.run(); return null; };
- runEWithContexts(se, contexts);
- }
- /***********************************************************************************************************************************************************
- * Calls a task with some local contexts. This method fits functional interfaces.
- *
- * @param <T> the type of the returned value
- * @param <E> the type of the thrown exception
- * @param task the task to call
- * @param contexts the contexts
- * @return the value returned by the supplier
- * @throws E the original exception thrown by task
- * @since 3.2-ALPHA-12
- **********************************************************************************************************************************************************/
- @Nonnull
- public <T, E extends Throwable> T runEWithContexts (@Nonnull SupplierWithException<T, E> task,
- @Nonnull Object ... contexts)
- throws E;
- /***********************************************************************************************************************************************************
- * Creates a binder that makes it possible to bind a local context by means of a try-with-resources instead of a
- * try/finally.
- *
- * <pre>
- * try (final ContextManager.Binder binder = contextManager.binder(context))
- * {
- * ...
- * }
- * </pre>
- *
- * @param contexts the contexts
- * @return a binder that can be used in try-with-resources
- * @since 3.2-ALPHA-12
- **********************************************************************************************************************************************************/
- @Nonnull
- public default Binder binder (@Nonnull final Object ... contexts)
- {
- return new Binder(this, contexts);
- }
- /***********************************************************************************************************************************************************
- * Used by
- * @since 3.2-ALPHA-12
- **********************************************************************************************************************************************************/
- public static class Binder implements AutoCloseable
- {
- @Nonnull
- private final ContextManager contextManager;
- @Nonnull
- private final Object[] contexts;
- private Binder (@Nonnull final ContextManager contextManager, @Nonnull final Object[] contexts)
- {
- this.contextManager = contextManager;
- this.contexts = contexts;
- for (final var context : contexts)
- {
- this.contextManager.addLocalContext(context);
- }
- }
- @Override
- public void close()
- {
- for (final var context : contexts)
- {
- this.contextManager.removeLocalContext(context);
- }
- }
- }
- }