View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.concurrent;
18  
19  import java.util.Collections;
20  import java.util.HashMap;
21  import java.util.Map;
22  import java.util.NoSuchElementException;
23  import java.util.Objects;
24  import java.util.Set;
25  import java.util.concurrent.ExecutorService;
26  
27  /**
28   * A specialized {@link BackgroundInitializer} implementation that can deal with
29   * multiple background initialization tasks.
30   *
31   * <p>
32   * This class has a similar purpose as {@link BackgroundInitializer}. However,
33   * it is not limited to a single background initialization task. Rather it
34   * manages an arbitrary number of {@link BackgroundInitializer} objects,
35   * executes them, and waits until they are completely initialized. This is
36   * useful for applications that have to perform multiple initialization tasks
37   * that can run in parallel (i.e. that do not depend on each other). This class
38   * takes care about the management of an {@link ExecutorService} and shares it
39   * with the {@link BackgroundInitializer} objects it is responsible for; so the
40   * using application need not bother with these details.
41   * </p>
42   * <p>
43   * The typical usage scenario for {@link MultiBackgroundInitializer} is as
44   * follows:
45   * </p>
46   * <ul>
47   * <li>Create a new instance of the class. Optionally pass in a pre-configured
48   * {@link ExecutorService}. Alternatively {@link MultiBackgroundInitializer} can
49   * create a temporary {@link ExecutorService} and delete it after initialization
50   * is complete.</li>
51   * <li>Create specialized {@link BackgroundInitializer} objects for the
52   * initialization tasks to be performed and add them to the {@code
53   * MultiBackgroundInitializer} using the
54   * {@link #addInitializer(String, BackgroundInitializer)} method.</li>
55   * <li>After all initializers have been added, call the {@link #start()} method.
56   * </li>
57   * <li>When access to the result objects produced by the {@code
58   * BackgroundInitializer} objects is needed call the {@link #get()} method. The
59   * object returned here provides access to all result objects created during
60   * initialization. It also stores information about exceptions that have
61   * occurred.</li>
62   * </ul>
63   * <p>
64   * {@link MultiBackgroundInitializer} starts a special controller task that
65   * starts all {@link BackgroundInitializer} objects added to the instance.
66   * Before the an initializer is started it is checked whether this initializer
67   * already has an {@link ExecutorService} set. If this is the case, this {@code
68   * ExecutorService} is used for running the background task. Otherwise the
69   * current {@link ExecutorService} of this {@link MultiBackgroundInitializer} is
70   * shared with the initializer.
71   * </p>
72   * <p>
73   * The easiest way of using this class is to let it deal with the management of
74   * an {@link ExecutorService} itself: If no external {@link ExecutorService} is
75   * provided, the class creates a temporary {@link ExecutorService} (that is
76   * capable of executing all background tasks in parallel) and destroys it at the
77   * end of background processing.
78   * </p>
79   * <p>
80   * Alternatively an external {@link ExecutorService} can be provided - either at
81   * construction time or later by calling the
82   * {@link #setExternalExecutor(ExecutorService)} method. In this case all
83   * background tasks are scheduled at this external {@link ExecutorService}.
84   * <strong>Important note:</strong> When using an external {@code
85   * ExecutorService} be sure that the number of threads managed by the service is
86   * large enough. Otherwise a deadlock can happen! This is the case in the
87   * following scenario: {@link MultiBackgroundInitializer} starts a task that
88   * starts all registered {@link BackgroundInitializer} objects and waits for
89   * their completion. If for instance a single threaded {@link ExecutorService}
90   * is used, none of the background tasks can be executed, and the task created
91   * by {@link MultiBackgroundInitializer} waits forever.
92   * </p>
93   *
94   * @since 3.0
95   */
96  public class MultiBackgroundInitializer extends BackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults> {
97  
98      /**
99       * A data class for storing the results of the background initialization
100      * performed by {@link MultiBackgroundInitializer}. Objects of this inner
101      * class are returned by {@link MultiBackgroundInitializer#initialize()}.
102      * They allow access to all result objects produced by the
103      * {@link BackgroundInitializer} objects managed by the owning instance. It
104      * is also possible to retrieve status information about single
105      * {@link BackgroundInitializer}s, i.e. whether they completed normally or
106      * caused an exception.
107      */
108     public static class MultiBackgroundInitializerResults {
109         /** A map with the child initializers. */
110         private final Map<String, BackgroundInitializer<?>> initializers;
111 
112         /** A map with the result objects. */
113         private final Map<String, Object> resultObjects;
114 
115         /** A map with the exceptions. */
116         private final Map<String, ConcurrentException> exceptions;
117 
118         /**
119          * Creates a new instance of {@link MultiBackgroundInitializerResults} and initializes it with maps for the {@link BackgroundInitializer} objects, their
120          * result objects and the exceptions thrown by them.
121          *
122          * @param initializers  the {@link BackgroundInitializer} objects.
123          * @param resultObjects the result objects.
124          * @param exceptions    the exceptions.
125          */
126         private MultiBackgroundInitializerResults(final Map<String, BackgroundInitializer<?>> initializers, final Map<String, Object> resultObjects,
127                 final Map<String, ConcurrentException> exceptions) {
128             this.initializers = initializers;
129             this.resultObjects = resultObjects;
130             this.exceptions = exceptions;
131         }
132 
133         /**
134          * Checks whether an initializer with the given name exists. If not,
135          * throws an exception. If it exists, the associated child initializer
136          * is returned.
137          *
138          * @param name the name to check.
139          * @return the initializer with this name.
140          * @throws NoSuchElementException if the name is unknown.
141          */
142         private BackgroundInitializer<?> checkName(final String name) {
143             final BackgroundInitializer<?> init = initializers.get(name);
144             if (init == null) {
145                 throw new NoSuchElementException("No child initializer with name " + name);
146             }
147             return init;
148         }
149 
150         /**
151          * Gets the {@link ConcurrentException} object that was thrown by the
152          * {@link BackgroundInitializer} with the given name. If this
153          * initializer did not throw an exception, the return value is
154          * <strong>null</strong>. If the name cannot be resolved, an exception is thrown.
155          *
156          * @param name the name of the {@link BackgroundInitializer}.
157          * @return the exception thrown by this initializer.
158          * @throws NoSuchElementException if the name cannot be resolved.
159          */
160         public ConcurrentException getException(final String name) {
161             checkName(name);
162             return exceptions.get(name);
163         }
164 
165         /**
166          * Gets the {@link BackgroundInitializer} with the given name. If the
167          * name cannot be resolved, an exception is thrown.
168          *
169          * @param name the name of the {@link BackgroundInitializer}.
170          * @return the {@link BackgroundInitializer} with this name.
171          * @throws NoSuchElementException if the name cannot be resolved.
172          */
173         public BackgroundInitializer<?> getInitializer(final String name) {
174             return checkName(name);
175         }
176 
177         /**
178          * Gets the result object produced by the {@code
179          * BackgroundInitializer} with the given name. This is the object returned by the initializer's {@code initialize()} method. If this
180          * {@link BackgroundInitializer} caused an exception, <strong>null</strong> is returned. If the name cannot be resolved, an exception is thrown.
181          *
182          * @param name the name of the {@link BackgroundInitializer}.
183          * @return the result object produced by this {@code BackgroundInitializer}.
184          * @throws NoSuchElementException if the name cannot be resolved.
185          */
186         public Object getResultObject(final String name) {
187             checkName(name);
188             return resultObjects.get(name);
189         }
190 
191         /**
192          * Returns a set with the names of all {@link BackgroundInitializer} objects managed by the {@link MultiBackgroundInitializer}.
193          *
194          * @return an (unmodifiable) set with the names of the managed {@code BackgroundInitializer} objects.
195          */
196         public Set<String> initializerNames() {
197             return Collections.unmodifiableSet(initializers.keySet());
198         }
199 
200         /**
201          * Tests whether the {@link BackgroundInitializer} with the
202          * given name caused an exception.
203          *
204          * @param name the name of the {@link BackgroundInitializer}.
205          * @return a flag whether this initializer caused an exception.
206          * @throws NoSuchElementException if the name cannot be resolved.
207          */
208         public boolean isException(final String name) {
209             checkName(name);
210             return exceptions.containsKey(name);
211         }
212 
213         /**
214          * Tests whether the whole initialization was successful. This
215          * is the case if no child initializer has thrown an exception.
216          *
217          * @return a flag whether the initialization was successful.
218          */
219         public boolean isSuccessful() {
220             return exceptions.isEmpty();
221         }
222     }
223 
224     /** A map with the child initializers. */
225     private final Map<String, BackgroundInitializer<?>> childInitializers = new HashMap<>();
226 
227     /**
228      * Constructs a new instance of {@link MultiBackgroundInitializer}.
229      */
230     public MultiBackgroundInitializer() {
231     }
232 
233     /**
234      * Constructs a new instance of {@link MultiBackgroundInitializer} and
235      * initializes it with the given external {@link ExecutorService}.
236      *
237      * @param exec the {@link ExecutorService} for executing the background tasks.
238      */
239     public MultiBackgroundInitializer(final ExecutorService exec) {
240         super(exec);
241     }
242 
243     /**
244      * Adds a new {@link BackgroundInitializer} to this object. When this {@link MultiBackgroundInitializer} is started, the given initializer will be
245      * processed. This method must not be called after {@link #start()} has been invoked.
246      *
247      * @param name                  the name of the initializer (must not be <strong>null</strong>).
248      * @param backgroundInitializer the {@link BackgroundInitializer} to add (must not be <strong>null</strong>).
249      * @throws NullPointerException  if either {@code name} or {@code backgroundInitializer} is {@code null}.
250      * @throws IllegalStateException if {@code start()} has already been called.
251      */
252     public void addInitializer(final String name, final BackgroundInitializer<?> backgroundInitializer) {
253         Objects.requireNonNull(name, "name");
254         Objects.requireNonNull(backgroundInitializer, "backgroundInitializer");
255         synchronized (this) {
256             if (isStarted()) {
257                 throw new IllegalStateException("addInitializer() must not be called after start()!");
258             }
259             childInitializers.put(name, backgroundInitializer);
260         }
261     }
262 
263     /**
264      * Calls the closer of all child {@code BackgroundInitializer} objects.
265      *
266      * @throws ConcurrentException throws an ConcurrentException that will have all other exceptions as suppressed exceptions. ConcurrentException thrown by
267      *                             children will be unwrapped.
268      * @since 3.14.0
269      */
270     @Override
271     public void close() throws ConcurrentException {
272         ConcurrentException exception = null;
273         for (final BackgroundInitializer<?> child : childInitializers.values()) {
274             try {
275                 child.close();
276             } catch (final Exception e) {
277                 if (exception == null) {
278                     exception = new ConcurrentException();
279                 }
280                 if (e instanceof ConcurrentException) {
281                     // Because ConcurrentException is only created by classes in this package
282                     // we can safely unwrap it.
283                     exception.addSuppressed(e.getCause());
284                 } else {
285                     exception.addSuppressed(e);
286                 }
287             }
288         }
289         if (exception != null) {
290             throw exception;
291         }
292     }
293 
294     /**
295      * Gets the number of tasks needed for executing all child {@code
296      * BackgroundInitializer} objects in parallel. This implementation sums up
297      * the required tasks for all child initializers (which is necessary if one
298      * of the child initializers is itself a {@link MultiBackgroundInitializer}
299      * ). Then it adds 1 for the control task that waits for the completion of
300      * the children.
301      *
302      * @return the number of tasks required for background processing.
303      */
304     @Override
305     protected int getTaskCount() {
306         return 1 + childInitializers.values().stream().mapToInt(BackgroundInitializer::getTaskCount).sum();
307     }
308 
309     /**
310      * Creates the results object. This implementation starts all child {@code
311      * BackgroundInitializer} objects. Then it collects their results and
312      * creates a {@link MultiBackgroundInitializerResults} object with this
313      * data. If a child initializer throws a checked exceptions, it is added to
314      * the results object. Unchecked exceptions are propagated.
315      *
316      * @return the results object.
317      * @throws Exception if an error occurs.
318      */
319     @Override
320     protected MultiBackgroundInitializerResults initialize() throws Exception {
321         final Map<String, BackgroundInitializer<?>> inits;
322         synchronized (this) {
323             // create a snapshot to operate on
324             inits = new HashMap<>(childInitializers);
325         }
326         // start the child initializers
327         final ExecutorService exec = getActiveExecutor();
328         inits.values().forEach(bi -> {
329             if (bi.getExternalExecutor() == null) {
330                 // share the executor service if necessary
331                 bi.setExternalExecutor(exec);
332             }
333             bi.start();
334         });
335         // collect the results
336         final Map<String, Object> results = new HashMap<>();
337         final Map<String, ConcurrentException> excepts = new HashMap<>();
338         inits.forEach((k, v) -> {
339             try {
340                 results.put(k, v.get());
341             } catch (final ConcurrentException cex) {
342                 excepts.put(k, cex);
343             }
344         });
345         return new MultiBackgroundInitializerResults(inits, results, excepts);
346     }
347 
348     /**
349      * Tests whether this all child {@code BackgroundInitializer} objects are initialized. Once initialized, always returns true.
350      *
351      * @return Whether all child {@code BackgroundInitializer} objects instance are initialized. Once initialized, always returns true. If there are no child
352      *         {@code BackgroundInitializer} objects return false.
353      * @since 3.14.0
354      */
355     @Override
356     public boolean isInitialized() {
357         if (childInitializers.isEmpty()) {
358             return false;
359         }
360         return childInitializers.values().stream().allMatch(BackgroundInitializer::isInitialized);
361     }
362 }