Class MultiBackgroundInitializer
- java.lang.Object
-
- org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer<T,java.lang.Exception>
-
- org.apache.commons.lang3.concurrent.BackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults>
-
- org.apache.commons.lang3.concurrent.MultiBackgroundInitializer
-
- All Implemented Interfaces:
ConcurrentInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults>
,FailableSupplier<MultiBackgroundInitializer.MultiBackgroundInitializerResults,ConcurrentException>
public class MultiBackgroundInitializer extends BackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults>
A specializedBackgroundInitializer
implementation that can deal with multiple background initialization tasks.This class has a similar purpose as
BackgroundInitializer
. However, it is not limited to a single background initialization task. Rather it manages an arbitrary number ofBackgroundInitializer
objects, executes them, and waits until they are completely initialized. This is useful for applications that have to perform multiple initialization tasks that can run in parallel (i.e. that do not depend on each other). This class takes care about the management of anExecutorService
and shares it with theBackgroundInitializer
objects it is responsible for; so the using application need not bother with these details.The typical usage scenario for
MultiBackgroundInitializer
is as follows:- Create a new instance of the class. Optionally pass in a pre-configured
ExecutorService
. AlternativelyMultiBackgroundInitializer
can create a temporaryExecutorService
and delete it after initialization is complete. - Create specialized
BackgroundInitializer
objects for the initialization tasks to be performed and add them to theMultiBackgroundInitializer
using theaddInitializer(String, BackgroundInitializer)
method. - After all initializers have been added, call the
BackgroundInitializer.start()
method. - When access to the result objects produced by the
BackgroundInitializer
objects is needed call theBackgroundInitializer.get()
method. The object returned here provides access to all result objects created during initialization. It also stores information about exceptions that have occurred.
MultiBackgroundInitializer
starts a special controller task that starts allBackgroundInitializer
objects added to the instance. Before the an initializer is started it is checked whether this initializer already has anExecutorService
set. If this is the case, thisExecutorService
is used for running the background task. Otherwise the currentExecutorService
of thisMultiBackgroundInitializer
is shared with the initializer.The easiest way of using this class is to let it deal with the management of an
ExecutorService
itself: If no externalExecutorService
is provided, the class creates a temporaryExecutorService
(that is capable of executing all background tasks in parallel) and destroys it at the end of background processing.Alternatively an external
ExecutorService
can be provided - either at construction time or later by calling theBackgroundInitializer.setExternalExecutor(ExecutorService)
method. In this case all background tasks are scheduled at this externalExecutorService
. Important note: When using an externalExecutorService
be sure that the number of threads managed by the service is large enough. Otherwise a deadlock can happen! This is the case in the following scenario:MultiBackgroundInitializer
starts a task that starts all registeredBackgroundInitializer
objects and waits for their completion. If for instance a single threadedExecutorService
is used, none of the background tasks can be executed, and the task created byMultiBackgroundInitializer
waits forever.- Since:
- 3.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
MultiBackgroundInitializer.MultiBackgroundInitializerResults
A data class for storing the results of the background initialization performed byMultiBackgroundInitializer
.-
Nested classes/interfaces inherited from class org.apache.commons.lang3.concurrent.BackgroundInitializer
BackgroundInitializer.Builder<I extends BackgroundInitializer<T>,T>
-
Nested classes/interfaces inherited from class org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer
AbstractConcurrentInitializer.AbstractBuilder<I extends AbstractConcurrentInitializer<T,E>,T,B extends AbstractConcurrentInitializer.AbstractBuilder<I,T,B,E>,E extends java.lang.Exception>
-
-
Field Summary
-
Fields inherited from interface org.apache.commons.lang3.function.FailableSupplier
NUL
-
-
Constructor Summary
Constructors Constructor Description MultiBackgroundInitializer()
Creates a new instance ofMultiBackgroundInitializer
.MultiBackgroundInitializer(java.util.concurrent.ExecutorService exec)
Creates a new instance ofMultiBackgroundInitializer
and initializes it with the given externalExecutorService
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addInitializer(java.lang.String name, BackgroundInitializer<?> backgroundInitializer)
Adds a newBackgroundInitializer
to this object.void
close()
Calls the closer of all childBackgroundInitializer
objectsboolean
isInitialized()
Tests whether this all childBackgroundInitializer
objects are initialized.-
Methods inherited from class org.apache.commons.lang3.concurrent.BackgroundInitializer
builder, get, getExternalExecutor, getFuture, isStarted, setExternalExecutor, start
-
-
-
-
Constructor Detail
-
MultiBackgroundInitializer
public MultiBackgroundInitializer()
Creates a new instance ofMultiBackgroundInitializer
.
-
MultiBackgroundInitializer
public MultiBackgroundInitializer(java.util.concurrent.ExecutorService exec)
Creates a new instance ofMultiBackgroundInitializer
and initializes it with the given externalExecutorService
.- Parameters:
exec
- theExecutorService
for executing the background tasks
-
-
Method Detail
-
addInitializer
public void addInitializer(java.lang.String name, BackgroundInitializer<?> backgroundInitializer)
Adds a newBackgroundInitializer
to this object. When thisMultiBackgroundInitializer
is started, the given initializer will be processed. This method must not be called afterBackgroundInitializer.start()
has been invoked.- Parameters:
name
- the name of the initializer (must not be null)backgroundInitializer
- theBackgroundInitializer
to add (must not be null)- Throws:
java.lang.NullPointerException
- if eithername
orbackgroundInitializer
isnull
java.lang.IllegalStateException
- ifstart()
has already been called
-
close
public void close() throws ConcurrentException
Calls the closer of all childBackgroundInitializer
objects- Overrides:
close
in classAbstractConcurrentInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults,java.lang.Exception>
- Throws:
ConcurrentException
- throws an ConcurrentException that will have all other exceptions as suppressed exceptions. ConcurrentException thrown by children will be unwrapped.- Since:
- 3.14.0
-
isInitialized
public boolean isInitialized()
Tests whether this all childBackgroundInitializer
objects are initialized. Once initialized, always returns true.- Overrides:
isInitialized
in classBackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults>
- Returns:
- whether all child
BackgroundInitializer
objects instance are initialized. Once initialized, always returns true. If there are no childBackgroundInitializer
objects return false. - Since:
- 3.14.0
-
-