Merge pull request eclipse#30 from FroMage/classloaders

Support per-classloader configuration and specify when to load the ThreadContextProviders

api/src/main/java/org/eclipse/microprofile/concurrent/spi/ConcurrencyManager.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2018 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * 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.
+ */
+package org.eclipse.microprofile.concurrent.spi;
+
+import org.eclipse.microprofile.concurrent.ManagedExecutorBuilder;
+import org.eclipse.microprofile.concurrent.ThreadContextBuilder;
+
+/**
+ * {@link ConcurrencyManager} instances can be used to create {@link #newManagedExecutorBuilder()}
+ * or {@link #newThreadContextBuilder()}. Each {@link ConcurrencyManager} instance has its own set
+ * of {@link ThreadContextProvider} as defined during building with {@link ConcurrencyManagerBuilder#build()}
+ * or {@link ConcurrencyProvider#getConcurrencyManager()}.
+ *
+ * @see ConcurrencyProvider#getConcurrencyManager()
+ * @see ConcurrencyManagerBuilder
+ */
+public interface ConcurrencyManager {
+    /**
+     * Creates a new <code>ManagedExecutorBuilder</code> instance.
+     *
+     * @return a new <code>ManagedExecutorBuilder</code> instance.
+     */
+    ManagedExecutorBuilder newManagedExecutorBuilder();
+
+    /**
+     * Creates a new <code>ThreadContextBuilder</code> instance.
+     *
+     * @return a new <code>ThreadContextBuilder</code> instance.
+     */
+    ThreadContextBuilder newThreadContextBuilder(); 
+
+}

api/src/main/java/org/eclipse/microprofile/concurrent/spi/ConcurrencyManagerBuilder.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2018 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * 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.
+ */
+package org.eclipse.microprofile.concurrent.spi;
+
+/**
+ * Use this class to configure instances of {@link ConcurrencyManager}.
+ */
+public interface ConcurrencyManagerBuilder {
+
+    /**
+     * Use the specified {@link ThreadContextProvider} instances.
+     * @param providers the {@link ThreadContextProvider} instances to use.
+     * @return this builder
+     */
+    public ConcurrencyManagerBuilder withThreadContextProviders(ThreadContextProvider... providers);
+
+    /**
+     * Load all discoverable {@link ThreadContextProvider} instances via the {@link ServiceLoader}
+     * mechanism on the current thread-context {@link ClassLoader} (unless overridden by {@link #forClassLoader(ClassLoader)}).
+     * 
+     * @return this builder
+     */
+    public ConcurrencyManagerBuilder addDiscoveredThreadContextProviders();
+
+    /**
+     * Use the given {@link ClassLoader} for {@link #addDiscoveredThreadContextProviders()} instead
+     * of the current thread-context {@link ClassLoader}.
+     * 
+     * @param classLoader the {@link ClassLoader} to use for {@link #addDiscoveredThreadContextProviders()}
+     * @return this builder
+     */
+    public ConcurrencyManagerBuilder forClassLoader(ClassLoader classLoader);
+
+    /**
+     * Creates a new {@link ConcurrencyManager} with the specified configuration.
+     * @return a new {@link ConcurrencyManager} with the specified configuration.
+     */
+    public ConcurrencyManager build();
+}

api/src/main/java/org/eclipse/microprofile/concurrent/spi/ConcurrencyProvider.java

@@ -81,20 +81,6 @@ public static ConcurrencyProvider instance() {
         return provider;
     }
 
-    /**
-     * Creates a new <code>ManagedExecutorBuilder</code> instance.
-     *
-     * @return a new <code>ManagedExecutorBuilder</code> instance.
-     */
-    ManagedExecutorBuilder newManagedExecutorBuilder();
-
-    /**
-     * Creates a new <code>ThreadContextBuilder</code> instance.
-     *
-     * @return a new <code>ThreadContextBuilder</code> instance.
-     */
-    ThreadContextBuilder newThreadContextBuilder(); 
-
     /**
      * Allows the container to register the <code>ConcurrencyProvider</code>
      * implementation. At most one implementation can be registered at any
@@ -112,4 +98,81 @@ public static ConcurrencyProviderRegistration register(ConcurrencyProvider provi
             throw new IllegalStateException("A ConcurrencyProvider implementation has already been registered.");
         }
     }
+
+    /**
+     * Gets a {@link ConcurrencyManager} for the current thread-context {@link ClassLoader}. This
+     * is equivalent to calling <code>getConcurrencyManager(Thread.currentThread().getContextClassLoader())</code>
+     * 
+     * @return a {@link ConcurrencyManager} for the current thread-context {@link ClassLoader}.
+     * @see #getConcurrencyManager(ClassLoader)
+     */
+    public ConcurrencyManager getConcurrencyManager();
+
+    /**
+     * Gets a {@link ConcurrencyManager} for the given {@link ClassLoader}. If there is already
+     * a {@link ConcurrencyManager} registered for the given {@link ClassLoader}, the existing
+     * instance will be returned. If not, one will be created using a {@link ConcurrencyManagerBuilder}
+     * using the specified {@link ClassLoader} (with {@link ConcurrencyManagerBuilder#forClassLoader(ClassLoader)})
+     * and with {@link ConcurrencyManagerBuilder#addDiscoveredThreadContextProviders()} called in
+     * order to load all {@link ThreadContextProvider} discoverable from the given {@link ClassLoader}.
+     * If created, the new {@link ConcurrencyManager} will then be registered for the given {@link ClassLoader}
+     * with {@link #registerConcurrencyManager(ConcurrencyManager, ClassLoader)}.
+     * 
+     * @return a {@link ConcurrencyManager} for the given {@link ClassLoader}.
+     * @see ConcurrencyManagerBuilder#addDiscoveredThreadContextProviders()
+     * @see ConcurrencyManagerBuilder#build()
+     * @see #registerConcurrencyManager(ConcurrencyManager, ClassLoader)
+     */
+    public ConcurrencyManager getConcurrencyManager(ClassLoader classLoader);
+
+    /**
+     * Returns a new {@link ConcurrencyManagerBuilder} to create new {@link ConcurrencyManager}
+     * instances. Watch out that instances created this way will not be automatically registered
+     * here, so you need to call {@link #registerConcurrencyManager(ConcurrencyManager, ClassLoader)}
+     * yourself if you need to.
+     * 
+     * @return a new {@link ConcurrencyManagerBuilder}
+     */
+    public ConcurrencyManagerBuilder getConcurrencyManagerBuilder();
+
+    /**
+     * Registers the given {@link ConcurrencyManager} for the given {@link ClassLoader}, so that
+     * further calls to {@link #getConcurrencyManager(ClassLoader)} for the same {@link ClassLoader}
+     * will return this instance instead of creating a new one.
+     * 
+     * @param manager The {@link ConcurrencyManager} to register
+     * @param classLoader The {@link ClassLoader} to register it for
+     * @see #getConcurrencyManager(ClassLoader)
+     * @see #releaseConcurrencyManager(ConcurrencyManager)
+     */
+    public void registerConcurrencyManager(ConcurrencyManager manager, ClassLoader classLoader);
+
+    /**
+     * Releases a {@link ConcurrencyManager} that was previously registered with 
+     * {@link #registerConcurrencyManager(ConcurrencyManager, ClassLoader)}.
+     * 
+     * @param manager The {@link ConcurrencyManager} to release
+     * @see #registerConcurrencyManager(ConcurrencyManager, ClassLoader)
+     */
+    public void releaseConcurrencyManager(ConcurrencyManager manager);
+
+    /**
+     * Creates a new <code>ManagedExecutorBuilder</code> instance using the 
+     * {@link ConcurrencyManager} returned by {@link #getConcurrencyManager()}.
+     *
+     * @return a new <code>ManagedExecutorBuilder</code> instance.
+     */
+    default ManagedExecutorBuilder newManagedExecutorBuilder() {
+        return getConcurrencyManager().newManagedExecutorBuilder();
+    }
+
+    /**
+     * Creates a new <code>ThreadContextBuilder</code> instance using the 
+     * {@link ConcurrencyManager} returned by {@link #getConcurrencyManager()}.
+     *
+     * @return a new <code>ThreadContextBuilder</code> instance.
+     */
+    default ThreadContextBuilder newThreadContextBuilder() {
+        return getConcurrencyManager().newThreadContextBuilder();
+    }
 }