Class 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
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 SummaryNested ClassesModifier and TypeClassDescriptionstatic classBackgroundInitializer.Builder<I extends BackgroundInitializer<T>,T> Builds a new instance.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 SummaryConstructorsModifierConstructorDescriptionprotectedCreates a new instance ofBackgroundInitializer.protectedCreates a new instance ofBackgroundInitializerand initializes it with the givenExecutorService.
- 
Method SummaryModifier and TypeMethodDescriptionstatic <T> BackgroundInitializer.Builder<BackgroundInitializer<T>,T> builder()Creates a new builder.get()Returns the result of the background initialization.protected final ExecutorServiceReturns theExecutorServicethat is actually used for executing the background task.final ExecutorServiceReturns the externalExecutorServiceto be used by this class.protected intReturns the number of background tasks to be created for this initializer.protected ExceptionGets an Exception with a type of E as defined by a concrete subclass of this class.booleanTests whether this instance is initialized.booleanReturns a flag whether thisBackgroundInitializerhas already been started.final voidsetExternalExecutor(ExecutorService externalExecutor) Sets anExecutorServiceto be used by this class.booleanstart()Starts the background initialization.Methods inherited from class org.apache.commons.lang3.concurrent.AbstractConcurrentInitializerclose, initialize
- 
Constructor Details- 
BackgroundInitializerprotected BackgroundInitializer()Creates a new instance ofBackgroundInitializer. No externalExecutorServiceis used.
- 
BackgroundInitializerCreates a new instance ofBackgroundInitializerand initializes it with the givenExecutorService. If theExecutorServiceis not null, the background task for initializing this object will be scheduled at this service. Otherwise a new temporaryExecutorServiceis created.- Parameters:
- exec- an external- ExecutorServiceto be used for task execution
 
 
- 
- 
Method Details- 
builderCreates a new builder.- Type Parameters:
- T- the type of object to build.
- Returns:
- a new builder.
- Since:
- 3.14.0
 
- 
getReturns 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, includingInterruptedExceptionare wrapped in aConcurrentException. Calling this method beforestart()was called causes anIllegalStateExceptionexception 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
 
- 
getActiveExecutorReturns theExecutorServicethat is actually used for executing the background task. This method can be called afterstart()(beforestart()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 ExecutorServicefor executing the background task
 
- 
getExternalExecutorReturns the externalExecutorServiceto be used by this class.- Returns:
- the ExecutorService
 
- 
getFutureReturns theFutureobject that was created whenstart()was called. Therefore this method can only be called afterstart().- Returns:
- the Futureobject wrapped by this initializer
- Throws:
- IllegalStateException- if- start()has not been called
 
- 
getTaskCountReturns the number of background tasks to be created for this initializer. This information is evaluated when a temporaryExecutorServiceis 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 thestart()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
 
- 
getTypedExceptionGets an Exception with a type of E as defined by a concrete subclass of this class.- Specified by:
- getTypedExceptionin 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.
 
- 
isInitializedTests 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:
- isInitializedin class- AbstractConcurrentInitializer<T,- Exception> 
- Returns:
- true if initialization completed successfully, otherwise false
- Since:
- 3.14.0
 
- 
isStartedReturns a flag whether thisBackgroundInitializerhas already been started.- Returns:
- a flag whether the start()method has already been called
 
- 
setExternalExecutorSets anExecutorServiceto be used by this class. TheExecutorServicepassed to this method is used for executing the background task. Thus it is possible to re-use an already existingExecutorServiceor to use a specially configured one. If noExecutorServiceis set, this instance creates a temporary one and destroys it after background initialization is complete. Note that this method must be called beforestart(); otherwise an exception is thrown.- Parameters:
- externalExecutor- the- ExecutorServiceto be used
- Throws:
- IllegalStateException- if this initializer has already been started
 
- 
startStarts the background initialization. With this method the initializer becomes active and invokes theAbstractConcurrentInitializer.initialize()method in a background task. ABackgroundInitializercan 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
 
 
-