Class MultiBackgroundInitializer
- All Implemented Interfaces:
ConcurrentInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults>,FailableSupplier<MultiBackgroundInitializer.MultiBackgroundInitializerResults,ConcurrentException>
BackgroundInitializer 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 of BackgroundInitializer 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 an ExecutorService and shares it
with the BackgroundInitializer 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. AlternativelyMultiBackgroundInitializercan create a temporaryExecutorServiceand delete it after initialization is complete. - Create specialized
BackgroundInitializerobjects for the initialization tasks to be performed and add them to theMultiBackgroundInitializerusing theaddInitializer(String, BackgroundInitializer)method. - After all initializers have been added, call the
BackgroundInitializer.start()method. - When access to the result objects produced by the
BackgroundInitializerobjects 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 all BackgroundInitializer objects added to the instance.
Before the an initializer is started it is checked whether this initializer
already has an ExecutorService set. If this is the case, this
ExecutorService is used for running the background task. Otherwise the
current ExecutorService of this MultiBackgroundInitializer 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 external ExecutorService is
provided, the class creates a temporary ExecutorService (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 the
BackgroundInitializer.setExternalExecutor(ExecutorService) method. In this case all
background tasks are scheduled at this external ExecutorService.
Important note: When using an external
ExecutorService 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 registered BackgroundInitializer objects and waits for
their completion. If for instance a single threaded ExecutorService
is used, none of the background tasks can be executed, and the task created
by MultiBackgroundInitializer waits forever.
- Since:
- 3.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classA 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 Exception> -
Field Summary
Fields inherited from interface org.apache.commons.lang3.function.FailableSupplier
NUL -
Constructor Summary
ConstructorsConstructorDescriptionCreates a new instance ofMultiBackgroundInitializer.Creates a new instance ofMultiBackgroundInitializerand initializes it with the given externalExecutorService. -
Method Summary
Modifier and TypeMethodDescriptionvoidaddInitializer(String name, BackgroundInitializer<?> backgroundInitializer) Adds a newBackgroundInitializerto this object.voidclose()Calls the closer of all childBackgroundInitializerobjectsprotected intReturns the number of tasks needed for executing all childBackgroundInitializerobjects in parallel.Creates the results object.booleanTests whether this all childBackgroundInitializerobjects are initialized.Methods inherited from class org.apache.commons.lang3.concurrent.BackgroundInitializer
builder, get, getActiveExecutor, getExternalExecutor, getFuture, getTypedException, isStarted, setExternalExecutor, start
-
Constructor Details
-
MultiBackgroundInitializer
public MultiBackgroundInitializer()Creates a new instance ofMultiBackgroundInitializer. -
MultiBackgroundInitializer
Creates a new instance ofMultiBackgroundInitializerand initializes it with the given externalExecutorService.- Parameters:
exec- theExecutorServicefor executing the background tasks
-
-
Method Details
-
addInitializer
Adds a newBackgroundInitializerto this object. When thisMultiBackgroundInitializeris 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- theBackgroundInitializerto add (must not be null)- Throws:
NullPointerException- if eithernameorbackgroundInitializerisnullIllegalStateException- ifstart()has already been called
-
close
Calls the closer of all childBackgroundInitializerobjects- Overrides:
closein classAbstractConcurrentInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults,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
-
getTaskCount
Returns the number of tasks needed for executing all childBackgroundInitializerobjects in parallel. This implementation sums up the required tasks for all child initializers (which is necessary if one of the child initializers is itself aMultiBackgroundInitializer). Then it adds 1 for the control task that waits for the completion of the children.- Overrides:
getTaskCountin classBackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults>- Returns:
- the number of tasks required for background processing
-
initialize
protected MultiBackgroundInitializer.MultiBackgroundInitializerResults initialize() throws ExceptionCreates the results object. This implementation starts all childBackgroundInitializerobjects. Then it collects their results and creates aMultiBackgroundInitializer.MultiBackgroundInitializerResultsobject with this data. If a child initializer throws a checked exceptions, it is added to the results object. Unchecked exceptions are propagated.- Overrides:
initializein classAbstractConcurrentInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults,Exception> - Returns:
- the results object
- Throws:
Exception- if an error occurs
-
isInitialized
Tests whether this all childBackgroundInitializerobjects are initialized. Once initialized, always returns true.- Overrides:
isInitializedin classBackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults>- Returns:
- whether all child
BackgroundInitializerobjects instance are initialized. Once initialized, always returns true. If there are no childBackgroundInitializerobjects return false. - Since:
- 3.14.0
-