CallableBackgroundInitializer
Date: 2017-02-08

org.apache.commons.lang3.concurrent

## Class CallableBackgroundInitializer<T>

- java.lang.Object
- - 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>

      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 `java.util.concurrent.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

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CallableBackgroundInitializer(java.util.concurrent.Callable<T> call)` Creates a new instance of `CallableBackgroundInitializer` and sets the `Callable` to be executed in a background thread.
    `CallableBackgroundInitializer(java.util.concurrent.Callable<T> call, java.util.concurrent.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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected T` | `initialize()` Performs initialization in a background thread.

    - ### Methods inherited from class org.apache.commons.lang3.concurrent.BackgroundInitializer

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

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### CallableBackgroundInitializer

          public CallableBackgroundInitializer(java.util.concurrent.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:
        `java.lang.IllegalArgumentException` - if the `Callable` is null

    - #### CallableBackgroundInitializer

          public CallableBackgroundInitializer(java.util.concurrent.Callable<T> call,
                                       java.util.concurrent.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:
        `java.lang.IllegalArgumentException` - if the `Callable` is null

  - ### Method Detail

    - #### initialize

          protected T initialize()
                          throws java.lang.Exception

      Performs initialization in a background thread. This implementation delegates to the `Callable` passed at construction time of this object.
      Specified by:
        `initialize` in class `BackgroundInitializer<T>`
      Returns:
        the result of the initialization
      Throws:
        `java.lang.Exception` - if an error occurs