A specialized 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. Alternatively MultiBackgroundInitializer can create a temporary ExecutorService and delete it after initialization is complete.
Create specialized BackgroundInitializer objects for the initialization tasks to be performed and add them to the MultiBackgroundInitializer using the addInitializer(String, BackgroundInitializer) method.
After all initializers have been added, call the start() method.
When access to the result objects produced by the BackgroundInitializer objects is needed call the 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 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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	MultiBackgroundInitializer.MultiBackgroundInitializerResults A data class for storing the results of the background initialization performed by `MultiBackgroundInitializer`.

Modifier and Type	Field and Description
private final Map<String, BackgroundInitializer<?>>	childInitializers A map with the child initializers.

Constructor Summary

Access	Constructor and Description
public	MultiBackgroundInitializer() Constructs a new instance of `MultiBackgroundInitializer`.
public	MultiBackgroundInitializer(final ExecutorService the `ExecutorService` for executing the background tasks. exec) Constructs a new instance of `MultiBackgroundInitializer` and initializes it with the given external `ExecutorService`.

Method Summary

Modifier and Type	Method and Description
public void	addInitializer(final String the name of the initializer (must not be null). name, final BackgroundInitializer<?> the `BackgroundInitializer` to add (must not be null). backgroundInitializer) Adds a new `BackgroundInitializer` to this object.
public void	close() Overrides org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer.close. Calls the closer of all child `BackgroundInitializer` objects.
protected int	Returns: the number of tasks required for background processing. getTaskCount() Overrides org.apache.commons.lang3.concurrent.BackgroundInitializer.getTaskCount. Gets the number of tasks needed for executing all child `BackgroundInitializer` objects in parallel.
protected MultiBackgroundInitializer.MultiBackgroundInitializerResults	Returns: the results object. initialize() Overrides org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer.initialize. Creates the results object.
public boolean	Returns: Whether all child `BackgroundInitializer` objects instance are initialized. Once initialized, always returns true. If there are no child `BackgroundInitializer` objects return false. isInitialized() Overrides org.apache.commons.lang3.concurrent.BackgroundInitializer.isInitialized. Tests whether this all child `BackgroundInitializer` objects are initialized.

Inherited from org.apache.commons.lang3.concurrent.BackgroundInitializer:: builder get getActiveExecutor getExternalExecutor getFuture getTypedException isStarted setExternalExecutor start

childInitializers	back to summary
private final Map<String, BackgroundInitializer<?>> childInitializers A map with the child initializers.

Constructor Detail

MultiBackgroundInitializer	back to summary
public MultiBackgroundInitializer() Constructs a new instance of `MultiBackgroundInitializer`.

MultiBackgroundInitializer back to summary

MultiBackgroundInitializer	back to summary
public MultiBackgroundInitializer(final ExecutorService exec) Constructs a new instance of `MultiBackgroundInitializer` and initializes it with the given external `ExecutorService`. Parameters exec:ExecutorService the `ExecutorService` for executing the background tasks.

public MultiBackgroundInitializer(final ExecutorService exec)

Constructs a new instance of MultiBackgroundInitializer and initializes it with the given external ExecutorService.

Parameters

exec:ExecutorService: the ExecutorService for executing the background tasks.

Method Detail

addInitializer back to summary

addInitializer	back to summary
public void addInitializer(final String name, final BackgroundInitializer<?> backgroundInitializer) Adds a new `BackgroundInitializer` to this object. When this `MultiBackgroundInitializer` is started, the given initializer will be processed. This method must not be called after `start()` has been invoked. Parameters name:String the name of the initializer (must not be null). backgroundInitializer:BackgroundInitializer<?> the `BackgroundInitializer` to add (must not be null). Exceptions NullPointerException: if either `name` or `backgroundInitializer` is `null`. IllegalStateException: if `start()` has already been called.

public void addInitializer(final String name, final BackgroundInitializer<?> backgroundInitializer)

Adds a new BackgroundInitializer to this object. When this MultiBackgroundInitializer is started, the given initializer will be processed. This method must not be called after start() has been invoked.

Parameters

name:String: the name of the initializer (must not be null).
backgroundInitializer:BackgroundInitializer<?>: the BackgroundInitializer to add (must not be null).

Exceptions

NullPointerException:: if either name or backgroundInitializer is null.
IllegalStateException:: if start() has already been called.

close back to summary

close	back to summary
public void close() throws ConcurrentException Overrides org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer.close. Calls the closer of all child `BackgroundInitializer` objects. Annotations @Override Exceptions ConcurrentException: throws an ConcurrentException that will have all other exceptions as suppressed exceptions. ConcurrentException thrown by children will be unwrapped. Since 3.14.0

public void close() throws ConcurrentException

Overrides org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer.close.

Calls the closer of all child BackgroundInitializer objects.

Annotations

@Override

Exceptions

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 back to summary

getTaskCount	back to summary
protected int getTaskCount() Overrides org.apache.commons.lang3.concurrent.BackgroundInitializer.getTaskCount. Gets the number of tasks needed for executing all child `BackgroundInitializer` objects in parallel. This implementation sums up the required tasks for all child initializers (which is necessary if one of the child initializers is itself a `MultiBackgroundInitializer` ). Then it adds 1 for the control task that waits for the completion of the children. Returns:int the number of tasks required for background processing. Annotations @Override

protected int getTaskCount()

Overrides org.apache.commons.lang3.concurrent.BackgroundInitializer.getTaskCount.

Gets the number of tasks needed for executing all child BackgroundInitializer objects in parallel. This implementation sums up the required tasks for all child initializers (which is necessary if one of the child initializers is itself a MultiBackgroundInitializer ). Then it adds 1 for the control task that waits for the completion of the children.

Returns:int

the number of tasks required for background processing.

Annotations

@Override

initialize back to summary

initialize	back to summary
protected MultiBackgroundInitializer.MultiBackgroundInitializerResults initialize() throws Exception Overrides org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer.initialize. Creates the results object. This implementation starts all child `BackgroundInitializer` objects. Then it collects their results and creates a `MultiBackgroundInitializerResults` object with this data. If a child initializer throws a checked exceptions, it is added to the results object. Unchecked exceptions are propagated. Returns:MultiBackgroundInitializer.MultiBackgroundInitializerResults the results object. Annotations @Override Exceptions Exception: if an error occurs.

protected MultiBackgroundInitializer.MultiBackgroundInitializerResults initialize() throws Exception

Overrides org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer.initialize.

Creates the results object. This implementation starts all child BackgroundInitializer objects. Then it collects their results and creates a MultiBackgroundInitializerResults object with this data. If a child initializer throws a checked exceptions, it is added to the results object. Unchecked exceptions are propagated.

Returns:MultiBackgroundInitializer.MultiBackgroundInitializerResults

the results object.

Annotations

@Override

Exceptions

Exception:: if an error occurs.

isInitialized back to summary

isInitialized	back to summary
public boolean isInitialized() Overrides org.apache.commons.lang3.concurrent.BackgroundInitializer.isInitialized. Tests whether this all child `BackgroundInitializer` objects are initialized. Once initialized, always returns true. Returns:boolean Whether all child `BackgroundInitializer` objects instance are initialized. Once initialized, always returns true. If there are no child `BackgroundInitializer` objects return false. Annotations @Override Since 3.14.0

public boolean isInitialized()

Overrides org.apache.commons.lang3.concurrent.BackgroundInitializer.isInitialized.

Tests whether this all child BackgroundInitializer objects are initialized. Once initialized, always returns true.

Returns:boolean

Whether all child BackgroundInitializer objects instance are initialized. Once initialized, always returns true. If there are no child BackgroundInitializer objects return false.

Annotations

@Override

Since

3.14.0

org.apache.commons.lang3.concurrent back to summary

public Class MultiBackgroundInitializer.MultiBackgroundInitializerResults

Class Inheritance

extends Object

java.lang.Object
org.apache.commons.lang3.concurrent.MultiBackgroundInitializer.MultiBackgroundInitializerResults

A data class for storing the results of the background initialization performed by MultiBackgroundInitializer. Objects of this inner class are returned by MultiBackgroundInitializer#initialize(). They allow access to all result objects produced by the BackgroundInitializer objects managed by the owning instance. It is also possible to retrieve status information about single BackgroundInitializers, i.e. whether they completed normally or caused an exception.

Field Summary

Modifier and Type	Field and Description
private final Map<String, ConcurrentException>	exceptions A map with the exceptions.
private final Map<String, BackgroundInitializer<?>>	initializers A map with the child initializers.
private final Map<String, Object>	resultObjects A map with the result objects.

Constructor Summary

Access Constructor and Description

private

Access	Constructor and Description
private	MultiBackgroundInitializerResults(final Map<String, BackgroundInitializer<?>> the `BackgroundInitializer` objects. initializers, final Map<String, Object> the result objects. resultObjects, final Map<String, ConcurrentException> the exceptions. exceptions) Creates a new instance of `MultiBackgroundInitializerResults` and initializes it with maps for the `BackgroundInitializer` objects, their result objects and the exceptions thrown by them.

MultiBackgroundInitializerResults(final Map<String, BackgroundInitializer<?>>

the BackgroundInitializer objects.

initializers, final Map<String, Object>

the result objects.

resultObjects, final Map<String, ConcurrentException>

the exceptions.

exceptions)

Creates a new instance of MultiBackgroundInitializerResults and initializes it with maps for the BackgroundInitializer objects, their result objects and the exceptions thrown by them.

Method Summary

Modifier and Type	Method and Description
private BackgroundInitializer<?>	Returns: the initializer with this name. checkName(final String the name to check. name) Checks whether an initializer with the given name exists.
public ConcurrentException	Returns: the exception thrown by this initializer. getException(final String the name of the `BackgroundInitializer`. name) Gets the `ConcurrentException` object that was thrown by the `BackgroundInitializer` with the given name.
public BackgroundInitializer<?>	Returns: the `BackgroundInitializer` with this name. getInitializer(final String the name of the `BackgroundInitializer`. name) Gets the `BackgroundInitializer` with the given name.
public Object	Returns: the result object produced by this `BackgroundInitializer`. getResultObject(final String the name of the `BackgroundInitializer`. name) Gets the result object produced by the `BackgroundInitializer` with the given name.
public Set<String>	Returns: an (unmodifiable) set with the names of the managed `BackgroundInitializer` objects. initializerNames() Returns a set with the names of all `BackgroundInitializer` objects managed by the `MultiBackgroundInitializer`.
public boolean	Returns: a flag whether this initializer caused an exception. isException(final String the name of the `BackgroundInitializer`. name) Tests whether the `BackgroundInitializer` with the given name caused an exception.
public boolean	Returns: a flag whether the initialization was successful. isSuccessful() Tests whether the whole initialization was successful.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

exceptions	back to summary
private final Map<String, ConcurrentException> exceptions A map with the exceptions.

initializers	back to summary
private final Map<String, BackgroundInitializer<?>> initializers A map with the child initializers.

resultObjects	back to summary
private final Map<String, Object> resultObjects A map with the result objects.

Constructor Detail

MultiBackgroundInitializerResults back to summary

MultiBackgroundInitializerResults	back to summary
private MultiBackgroundInitializerResults(final Map<String, BackgroundInitializer<?>> initializers, final Map<String, Object> resultObjects, final Map<String, ConcurrentException> exceptions) Creates a new instance of `MultiBackgroundInitializerResults` and initializes it with maps for the `BackgroundInitializer` objects, their result objects and the exceptions thrown by them. Parameters initializers:Map<String, BackgroundInitializer<?>> the `BackgroundInitializer` objects. resultObjects:Map<String, Object> the result objects. exceptions:Map<String, ConcurrentException> the exceptions.

private MultiBackgroundInitializerResults(final Map<String, BackgroundInitializer<?>> initializers, final Map<String, Object> resultObjects, final Map<String, ConcurrentException> exceptions)

Creates a new instance of MultiBackgroundInitializerResults and initializes it with maps for the BackgroundInitializer objects, their result objects and the exceptions thrown by them.

Parameters

initializers:Map<String, BackgroundInitializer<?>>: the BackgroundInitializer objects.
resultObjects:Map<String, Object>: the result objects.
exceptions:Map<String, ConcurrentException>: the exceptions.

Method Detail

checkName	back to summary
private BackgroundInitializer<?> checkName(final String name) Checks whether an initializer with the given name exists. If not, throws an exception. If it exists, the associated child initializer is returned. Parameters name:String the name to check. Returns:BackgroundInitializer<?> the initializer with this name. Exceptions NoSuchElementException: if the name is unknown.

checkName

back to summary

private BackgroundInitializer<?> checkName(final String name)

Checks whether an initializer with the given name exists. If not, throws an exception. If it exists, the associated child initializer is returned.

Parameters

name:String: the name to check.

Returns:BackgroundInitializer<?>

the initializer with this name.

Exceptions

NoSuchElementException:: if the name is unknown.

getException back to summary

getException	back to summary
public ConcurrentException getException(final String name) Gets the `ConcurrentException` object that was thrown by the `BackgroundInitializer` with the given name. If this initializer did not throw an exception, the return value is null. If the name cannot be resolved, an exception is thrown. Parameters name:String the name of the `BackgroundInitializer`. Returns:ConcurrentException the exception thrown by this initializer. Exceptions NoSuchElementException: if the name cannot be resolved.

public ConcurrentException getException(final String name)

Gets the ConcurrentException object that was thrown by the BackgroundInitializer with the given name. If this initializer did not throw an exception, the return value is null. If the name cannot be resolved, an exception is thrown.

Parameters

name:String: the name of the BackgroundInitializer.

Returns:ConcurrentException

the exception thrown by this initializer.

Exceptions

NoSuchElementException:: if the name cannot be resolved.

getInitializer back to summary

getInitializer	back to summary
public BackgroundInitializer<?> getInitializer(final String name) Gets the `BackgroundInitializer` with the given name. If the name cannot be resolved, an exception is thrown. Parameters name:String the name of the `BackgroundInitializer`. Returns:BackgroundInitializer<?> the `BackgroundInitializer` with this name. Exceptions NoSuchElementException: if the name cannot be resolved.

public BackgroundInitializer<?> getInitializer(final String name)

Gets the BackgroundInitializer with the given name. If the name cannot be resolved, an exception is thrown.

Parameters

name:String: the name of the BackgroundInitializer.

Returns:BackgroundInitializer<?>

the BackgroundInitializer with this name.

Exceptions

NoSuchElementException:: if the name cannot be resolved.

getResultObject back to summary

getResultObject	back to summary
public Object getResultObject(final String name) Gets the result object produced by the `BackgroundInitializer` with the given name. This is the object returned by the initializer's `initialize()` method. If this `BackgroundInitializer` caused an exception, null is returned. If the name cannot be resolved, an exception is thrown. Parameters name:String the name of the `BackgroundInitializer`. Returns:Object the result object produced by this `BackgroundInitializer`. Exceptions NoSuchElementException: if the name cannot be resolved.

public Object getResultObject(final String name)

Gets the result object produced by the BackgroundInitializer with the given name. This is the object returned by the initializer's initialize() method. If this BackgroundInitializer caused an exception, null is returned. If the name cannot be resolved, an exception is thrown.

Parameters

name:String: the name of the BackgroundInitializer.

Returns:Object

the result object produced by this BackgroundInitializer.

Exceptions

NoSuchElementException:: if the name cannot be resolved.

initializerNames back to summary

initializerNames	back to summary
public Set<String> initializerNames() Returns a set with the names of all `BackgroundInitializer` objects managed by the `MultiBackgroundInitializer`. Returns:Set<String> an (unmodifiable) set with the names of the managed `BackgroundInitializer` objects.

public Set<String> initializerNames()

Returns a set with the names of all BackgroundInitializer objects managed by the MultiBackgroundInitializer.

Returns:Set<String>: an (unmodifiable) set with the names of the managed BackgroundInitializer objects.

isException back to summary

isException	back to summary
public boolean isException(final String name) Tests whether the `BackgroundInitializer` with the given name caused an exception. Parameters name:String the name of the `BackgroundInitializer`. Returns:boolean a flag whether this initializer caused an exception. Exceptions NoSuchElementException: if the name cannot be resolved.

public boolean isException(final String name)

Tests whether the BackgroundInitializer with the given name caused an exception.

Parameters

name:String: the name of the BackgroundInitializer.

Returns:boolean

a flag whether this initializer caused an exception.

Exceptions

NoSuchElementException:: if the name cannot be resolved.

isSuccessful	back to summary
public boolean isSuccessful() Tests whether the whole initialization was successful. This is the case if no child initializer has thrown an exception. Returns:boolean a flag whether the initialization was successful.

isSuccessful

back to summary

public boolean isSuccessful()

Tests whether the whole initialization was successful. This is the case if no child initializer has thrown an exception.

Returns:boolean: a flag whether the initialization was successful.