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

Package org.apache.commons.lang3.concurrent

# 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 org.apache.commons.lang3.concurrent.BackgroundInitializer

  `BackgroundInitializer.Builder<I extends BackgroundInitializer<T>,T>`

  ## 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
  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 org.apache.commons.lang3.concurrent.BackgroundInitializer

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

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

  `close`

  ### Methods inherited from class java.lang.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