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 }