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 SummaryNested 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.BackgroundInitializerBackgroundInitializer.Builder<I extends BackgroundInitializer<T>,T> Nested classes/interfaces inherited from class org.apache.commons.lang3.concurrent.AbstractConcurrentInitializerAbstractConcurrentInitializer.AbstractBuilder<I extends AbstractConcurrentInitializer<T,E>, T, B extends AbstractConcurrentInitializer.AbstractBuilder<I, T, B, E>, E extends Exception> 
- 
Field SummaryFields inherited from interface org.apache.commons.lang3.function.FailableSupplierNUL
- 
Constructor SummaryConstructorsConstructorDescriptionCreates a new instance ofMultiBackgroundInitializer.Creates a new instance ofMultiBackgroundInitializerand initializes it with the given externalExecutorService.
- 
Method SummaryModifier 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.BackgroundInitializerbuilder, get, getActiveExecutor, getExternalExecutor, getFuture, getTypedException, isStarted, setExternalExecutor, start
- 
Constructor Details- 
MultiBackgroundInitializerpublic MultiBackgroundInitializer()Creates a new instance ofMultiBackgroundInitializer.
- 
MultiBackgroundInitializerCreates a new instance ofMultiBackgroundInitializerand initializes it with the given externalExecutorService.- Parameters:
- exec- the- ExecutorServicefor executing the background tasks
 
 
- 
- 
Method Details- 
addInitializerAdds 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- the- BackgroundInitializerto add (must not be null)
- Throws:
- NullPointerException- if either- nameor- backgroundInitializeris- null
- IllegalStateException- if- start()has already been called
 
- 
closeCalls the closer of all childBackgroundInitializerobjects- Overrides:
- closein class- AbstractConcurrentInitializer<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
 
- 
getTaskCountReturns 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 class- BackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults>
- Returns:
- the number of tasks required for background processing
 
- 
initializeprotected 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 class- AbstractConcurrentInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults,- Exception> 
- Returns:
- the results object
- Throws:
- Exception- if an error occurs
 
- 
isInitializedTests whether this all childBackgroundInitializerobjects are initialized. Once initialized, always returns true.- Overrides:
- isInitializedin class- BackgroundInitializer<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
 
 
-