public class MultiBackgroundInitializer extends BackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults>
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:
ExecutorService. Alternatively MultiBackgroundInitializer can
create a temporary ExecutorService and delete it after initialization
is complete.BackgroundInitializer objects for the
initialization tasks to be performed and add them to the MultiBackgroundInitializer using the
addInitializer(String, BackgroundInitializer) method.BackgroundInitializer.start() method.
BackgroundInitializer objects is needed call the BackgroundInitializer.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.
| Modifier and Type | Class and Description |
|---|---|
static class |
MultiBackgroundInitializer.MultiBackgroundInitializerResults
A data class for storing the results of the background initialization
performed by
MultiBackgroundInitializer. |
| Constructor and Description |
|---|
MultiBackgroundInitializer()
Creates a new instance of
MultiBackgroundInitializer. |
MultiBackgroundInitializer(ExecutorService exec)
Creates a new instance of
MultiBackgroundInitializer and
initializes it with the given external ExecutorService. |
| Modifier and Type | Method and Description |
|---|---|
void |
addInitializer(String name,
BackgroundInitializer<?> init)
Adds a new
BackgroundInitializer to this object. |
protected int |
getTaskCount()
Returns the number of tasks needed for executing all child
BackgroundInitializer objects in parallel. |
protected MultiBackgroundInitializer.MultiBackgroundInitializerResults |
initialize()
Creates the results object.
|
get, getActiveExecutor, getExternalExecutor, getFuture, isStarted, setExternalExecutor, startpublic MultiBackgroundInitializer()
MultiBackgroundInitializer.public MultiBackgroundInitializer(ExecutorService exec)
MultiBackgroundInitializer and
initializes it with the given external ExecutorService.exec - the ExecutorService for executing the background
taskspublic void addInitializer(String name, BackgroundInitializer<?> init)
BackgroundInitializer to this object. When this
MultiBackgroundInitializer is started, the given initializer will
be processed. This method must not be called after BackgroundInitializer.start() has
been invoked.name - the name of the initializer (must not be null)init - the BackgroundInitializer to add (must not be
null)IllegalArgumentException - if a required parameter is missingIllegalStateException - if start() has already been calledprotected int getTaskCount()
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.getTaskCount in class BackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults>protected MultiBackgroundInitializer.MultiBackgroundInitializerResults initialize() throws Exception
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.initialize in class BackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults>Exception - if an error occursCopyright © 2001–2016 The Apache Software Foundation. All rights reserved.