Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

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

Direct Known Subclasses:
  CallableBackgroundInitializer, MultiBackgroundInitializer

    public abstract class BackgroundInitializer<T>

extends Object
implements ConcurrentInitializer<T>

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 `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
Version:
  $Id: BackgroundInitializer.java 1082044 2011-03-16 04:26:58Z bayard $

Constructor Summary
`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
`T` | `get()` Returns the result of the background initialization.
`protected ExecutorService` | `getActiveExecutor()` Returns the `ExecutorService` that is actually used for executing the background task.
`ExecutorService` | `getExternalExecutor()` Returns the external `ExecutorService` to be used by this class.
`Future<T>` | `getFuture()` Returns the `Future` object that was created when `start()` was called.
`protected int` | `getTaskCount()` Returns the number of background tasks to be created for this initializer.
`protected abstract T` | `initialize()` Performs the initialization.
`boolean` | `isStarted()` Returns a flag 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 java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

### getExternalExecutor

    public final ExecutorService getExternalExecutor()

  Returns the external `ExecutorService` to be used by this class.

  Returns:
    the `ExecutorService`

### isStarted

    public boolean isStarted()

  Returns a flag 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 `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

### get

    public T get()
          throws ConcurrentException

  Returns 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.

  Specified by:
    `get` in interface `ConcurrentInitializer<T>`
  Returns:
    the object produced by this initializer
  Throws:
    `ConcurrentException` - if a checked exception occurred during background processing
    `IllegalStateException` - if `start()` has not been called

### getFuture

    public Future<T> getFuture()

  Returns 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

### getActiveExecutor

    protected final ExecutorService getActiveExecutor()

  Returns 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

### getTaskCount

    protected int getTaskCount()

  Returns 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

### initialize

    protected abstract T initialize()
                             throws Exception

  Performs the initialization. This method is called in a background task when this `BackgroundInitializer` is started. It must be implemented by a concrete subclass. An implementation is free to perform arbitrary initialization. The object returned by this method can be queried using the `get()` method.

  Returns:
    a result object
  Throws:
    `Exception` - if an error occurs

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2011 The Apache Software Foundation. All Rights Reserved.