org.apache.commons.lang3.concurrent

Class BackgroundInitializer<T>

java.lang.Object

org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer<T,Exception>

org.apache.commons.lang3.concurrent.BackgroundInitializer<T>

Type Parameters:

T - the type of the object managed by this initializer class

All Implemented Interfaces:

ConcurrentInitializer<T>, FailableSupplier<T,ConcurrentException>

Direct Known Subclasses:

CallableBackgroundInitializer, MultiBackgroundInitializer

public class BackgroundInitializer<T>
extends AbstractConcurrentInitializer<T,Exception>

A class that allows complex initialization operations in a background task.

Applications often have to do some expensive initialization steps when they are started, e.g. constructing a connection to a database, reading a configuration file, etc. Doing these things in parallel can enhance performance as the CPU load can be improved. However, when access to the resources initialized in a background thread is actually required, synchronization has to be performed to ensure that their initialization is complete.

This abstract base class provides support for this use case. A concrete subclass must implement the AbstractConcurrentInitializer.initialize() method. Here an arbitrary initialization can be implemented, and a result object can be returned. With this method in place the basic usage of this class is as follows (where MyBackgroundInitializer is a concrete subclass):

 MyBackgroundInitializer initializer = new MyBackgroundInitializer();
 initializer.start();
 // Now do some other things. Initialization runs in a parallel thread
 ...
 // Wait for the end of initialization and access the result object
 Object result = initializer.get();
 

After the construction of a BackgroundInitializer object its start() method has to be called. This starts the background processing. The application can now continue to do other things. When it needs access to the object produced by the BackgroundInitializer it calls its get() method. If initialization is already complete, get() returns the result object immediately. Otherwise it blocks until the result object is fully constructed.

BackgroundInitializer is a thin wrapper around a Future object and uses an ExecutorService for running the background initialization task. It is possible to pass in an ExecutorService at construction time or set one using setExternalExecutor() before start() was called. Then this object is used to spawn the background task. If no ExecutorService has been provided, BackgroundInitializer creates a temporary ExecutorService and destroys it when initialization is complete.

The methods provided by BackgroundInitializer provide for minimal interaction with the wrapped Future object. It is also possible to obtain the Future object directly. Then the enhanced functionality offered by Future can be used, e.g. to check whether the background operation is complete or to cancel the operation.

Since:

3.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BackgroundInitializer.Builder<I extends BackgroundInitializer<T>,T> Builds a new instance.

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

Constructors

Modifier	Constructor and Description
protected	BackgroundInitializer() Creates a new instance of BackgroundInitializer.
protected	BackgroundInitializer(ExecutorService exec) Creates a new instance of BackgroundInitializer and initializes it with the given ExecutorService.

Method Summary

Modifier and Type	Method and Description
static <T> BackgroundInitializer.Builder<BackgroundInitializer<T>,T>	builder() Creates a new builder.
T	get() Gets the result of the background initialization.
protected ExecutorService	getActiveExecutor() Gets the ExecutorService that is actually used for executing the background task.
ExecutorService	getExternalExecutor() Gets the external ExecutorService to be used by this class.
Future<T>	getFuture() Gets the Future object that was created when start() was called.
protected int	getTaskCount() Gets the number of background tasks to be created for this initializer.
protected Exception	getTypedException(Exception e) Gets an Exception with a type of E as defined by a concrete subclass of this class.
boolean	isInitialized() Tests whether this instance is initialized.
boolean	isStarted() Tests whether this BackgroundInitializer has already been started.
void	setExternalExecutor(ExecutorService externalExecutor) Sets an ExecutorService to be used by this class.
boolean	start() Starts the background initialization.

Methods inherited from class org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer

close, initialize

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.commons.lang3.function.FailableSupplier

nul

Constructor Detail

BackgroundInitializer

protected BackgroundInitializer()

Creates a new instance of BackgroundInitializer. No external ExecutorService is used.

BackgroundInitializer

protected BackgroundInitializer(ExecutorService exec)

Creates a new instance of BackgroundInitializer and initializes it with the given ExecutorService. If the ExecutorService is not null, the background task for initializing this object will be scheduled at this service. Otherwise a new temporary ExecutorService is created.

Parameters:

exec - an external ExecutorService to be used for task. execution

Method Detail

builder

public static <T> BackgroundInitializer.Builder<BackgroundInitializer<T>,T> builder()

Creates a new builder.

Type Parameters:

T - the type of object to build.

Returns:

a new builder.

Since:

3.14.0

get

public T get()
      throws ConcurrentException

Gets the result of the background initialization. This method blocks until initialization is complete. If the background processing caused a runtime exception, it is directly thrown by this method. Checked exceptions, including InterruptedException are wrapped in a ConcurrentException. Calling this method before start() was called causes an IllegalStateException exception to be thrown.

Returns:

the object produced by this initializer.

Throws:

ConcurrentException - if a checked exception occurred during background processing.

IllegalStateException - if start() has not been called.

getActiveExecutor

protected final ExecutorService getActiveExecutor()

Gets the ExecutorService that is actually used for executing the background task. This method can be called after start() (before start() it returns null). If an external executor was set, this is also the active executor. Otherwise this method returns the temporary executor that was created by this object.

Returns:

the ExecutorService for executing the background task.

getExternalExecutor

public final ExecutorService getExternalExecutor()

Gets the external ExecutorService to be used by this class.

Returns:

the ExecutorService.

getFuture

public Future<T> getFuture()

Gets the Future object that was created when start() was called. Therefore this method can only be called after start().

Returns:

the Future object wrapped by this initializer.

Throws:

IllegalStateException - if start() has not been called.

getTaskCount

protected int getTaskCount()

Gets the number of background tasks to be created for this initializer. This information is evaluated when a temporary ExecutorService is created. This base implementation returns 1. Derived classes that do more complex background processing can override it. This method is called from a synchronized block by the start() method. Therefore overriding methods should be careful with obtaining other locks and return as fast as possible.

Returns:

the number of background tasks required by this initializer.

getTypedException

protected Exception getTypedException(Exception e)

Gets an Exception with a type of E as defined by a concrete subclass of this class.

Specified by:

getTypedException in class AbstractConcurrentInitializer<T,Exception>

Parameters:

e - The actual exception that was thrown

Returns:

a new exception with the actual type of E, that wraps e.

isInitialized

public boolean isInitialized()

Tests whether this instance is initialized. Once initialized, always returns true. If initialization failed then the failure will be cached and this will never return true.

Specified by:

isInitialized in class AbstractConcurrentInitializer<T,Exception>

Returns:

true if initialization completed successfully, otherwise false.

Since:

3.14.0

isStarted

public boolean isStarted()

Tests whether this BackgroundInitializer has already been started.

Returns:

a flag whether the start() method has already been called.

setExternalExecutor

public final void setExternalExecutor(ExecutorService externalExecutor)

Sets an ExecutorService to be used by this class. The ExecutorService passed to this method is used for executing the background task. Thus it is possible to re-use an already existing ExecutorService or to use a specially configured one. If no ExecutorService is set, this instance creates a temporary one and destroys it after background initialization is complete. Note that this method must be called before start(); otherwise an exception is thrown.

Parameters:

externalExecutor - the ExecutorService to be used.

Throws:

IllegalStateException - if this initializer has already been started.

start

public boolean start()

Starts the background initialization. With this method the initializer becomes active and invokes the AbstractConcurrentInitializer.initialize() method in a background task. A BackgroundInitializer can be started exactly once. The return value of this method determines whether the start was successful: only the first invocation of this method returns true, following invocations will return false.

Returns:

a flag whether the initializer could be started successfully.