CallableBackgroundInitializer (Apache Commons Lang 3.20.0 API)
Description: declaration: package: org.apache.commons.lang3.concurrent, class: CallableBackgroundInitializer

# Class CallableBackgroundInitializer<T>

java.lang.Object
org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer<T, Exception>
org.apache.commons.lang3.concurrent.BackgroundInitializer<T>
org.apache.commons.lang3.concurrent.CallableBackgroundInitializer<T>

Type Parameters:
  `T` - the type of the object managed by this initializer class

All Implemented Interfaces:
  `ConcurrentInitializer<T>, FailableSupplier<T, ConcurrentException>`

public class CallableBackgroundInitializer<T> extends BackgroundInitializer<T>
A specialized `BackgroundInitializer` implementation that wraps a `Callable` object.

An instance of this class is initialized with a `Callable` object when it is constructed. The implementation of the `initialize()` method defined in the super class delegates to this `Callable` so that the `Callable` is executed in the background thread.

The `Callable` interface is a standard mechanism of the JDK to define tasks to be executed by another thread. The `CallableBackgroundInitializer` class allows combining this standard interface with the background initializer API.

Usage of this class is very similar to the default usage pattern of the `BackgroundInitializer` class: Just create an instance and provide the `Callable` object to be executed, then call the initializer's `BackgroundInitializer.start()` method. This causes the `Callable` to be executed in another thread. When the results of the `Callable` are needed the initializer's `BackgroundInitializer.get()` method can be called (which may block until background execution is complete). The following code fragment shows a typical usage example:

    // a Callable that performs a complex computation
    Callable<Integer> computationCallable = new MyComputationCallable();
    // setup the background initializer
    CallableBackgroundInitializer<Integer> initializer =
        new CallableBackgroundInitializer(computationCallable);
    initializer.start();
    // Now do some other things. Initialization runs in a parallel thread
    ...
    // Wait for the end of initialization and access the result
    Integer result = initializer.get();

Since:
  3.0

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from class BackgroundInitializer

  `BackgroundInitializer.Builder<I,T>`

  ### Nested classes/interfaces inherited from class AbstractConcurrentInitializer

  `AbstractConcurrentInitializer.AbstractBuilder<I,T,B,E>`

- ## Field Summary

  ### Fields inherited from interface FailableSupplier

  `NUL`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CallableBackgroundInitializer(Callable<T> call)`
  Creates a new instance of `CallableBackgroundInitializer` and sets the `Callable` to be executed in a background thread.
  `CallableBackgroundInitializer(Callable<T> call, ExecutorService exec)`
  Creates a new instance of `CallableBackgroundInitializer` and initializes it with the `Callable` to be executed in a background thread and the `ExecutorService` for managing the background execution.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected Exception`
  `getTypedException(Exception e)`
  Gets an Exception with a type of E as defined by a concrete subclass of this class.
  `protected T`
  `initialize()`
  Performs initialization in a background thread.

  ### Methods inherited from class BackgroundInitializer

  `builder, get, getActiveExecutor, getExternalExecutor, getFuture, getTaskCount, isInitialized, isStarted, setExternalExecutor, start`

  ### Methods inherited from class AbstractConcurrentInitializer

  `close`

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### CallableBackgroundInitializer

    public CallableBackgroundInitializer(Callable<T> call)
    Creates a new instance of `CallableBackgroundInitializer` and sets the `Callable` to be executed in a background thread.
    Parameters:
      `call` - the `Callable` (must not be null).
    Throws:
      `IllegalArgumentException` - if the `Callable` is null.

  - ### CallableBackgroundInitializer

    public CallableBackgroundInitializer(Callable<T> call, ExecutorService exec)
    Creates a new instance of `CallableBackgroundInitializer` and initializes it with the `Callable` to be executed in a background thread and the `ExecutorService` for managing the background execution.
    Parameters:
      `call` - the `Callable` (must not be null).
      `exec` - an external `ExecutorService` to be used for task execution.
    Throws:
      `IllegalArgumentException` - if the `Callable` is null.

- ## Method Details

  - ### getTypedException

    protected Exception getTypedException(Exception e)
    Gets an Exception with a type of E as defined by a concrete subclass of this class.
    Overrides:
      `getTypedException` in class `BackgroundInitializer<T>`
    Parameters:
      `e` - The actual exception that was thrown.
    Returns:
      a new exception with the actual type of E, that wraps e.

  - ### initialize

    protected T initialize() throws Exception
    Performs initialization in a background thread. This implementation delegates to the `Callable` passed at construction time of this object.
    Overrides:
      `initialize` in class `AbstractConcurrentInitializer<T, Exception>`
    Returns:
      the result of the initialization.
    Throws:
      `Exception` - if an error occurs.