Deferred
Date: 2016-06-25

org.osgi.util.promise

## Class Deferred<T>

- java.lang.Object
- - org.osgi.util.promise.Deferred<T>

- Type Parameters:
    `T` - The value type associated with the created Promise.

      public class Deferred<T>
      extends java.lang.Object

  A Deferred Promise resolution.

  Instances of this class can be used to create a `Promise` that can be resolved in the future. The `associated` Promise can be successfully resolved with `resolve(Object)` or resolved with a failure with `fail(Throwable)`. It can also be resolved with the resolution of another promise using `resolveWith(Promise)`.

  The associated Promise can be provided to any one, but the Deferred object should be made available only to the party that will responsible for resolving the Promise.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Deferred()` Create a new Deferred with an associated Promise.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `fail(java.lang.Throwable failure)` Fail the Promise associated with this Deferred.
    `Promise<T>` | `getPromise()` Returns the Promise associated with this Deferred.
    `void` | `resolve(T value)` Successfully resolve the Promise associated with this Deferred.
    `Promise<java.lang.Void>` | `resolveWith(Promise<? extends T> with)` Resolve the Promise associated with this Deferred with the specified Promise.

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

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

- - ### Constructor Detail

    - #### Deferred

          public Deferred()

      Create a new Deferred with an associated Promise.

  - ### Method Detail

    - #### getPromise

          public Promise<T> getPromise()

      Returns the Promise associated with this Deferred.
      Returns:
        The Promise associated with this Deferred.

    - #### resolve

          public void resolve(T value)

      Successfully resolve the Promise associated with this Deferred.

      After the associated Promise is resolved with the specified value, all registered `callbacks` are called and any `chained` Promises are resolved.

      Resolving the associated Promise happens-before any registered callback is called. That is, in a registered callback, `Promise.isDone()` must return `true` and `Promise.getValue()` and `Promise.getFailure()` must not block.

      Parameters:
        `value` - The value of the resolved Promise.
      Throws:
        `java.lang.IllegalStateException` - If the associated Promise was already resolved.

    - #### fail

          public void fail(java.lang.Throwable failure)

      Fail the Promise associated with this Deferred.

      After the associated Promise is resolved with the specified failure, all registered `callbacks` are called and any `chained` Promises are resolved.

      Resolving the associated Promise happens-before any registered callback is called. That is, in a registered callback, `Promise.isDone()` must return `true` and `Promise.getValue()` and `Promise.getFailure()` must not block.

      Parameters:
        `failure` - The failure of the resolved Promise. Must not be `null`.
      Throws:
        `java.lang.IllegalStateException` - If the associated Promise was already resolved.

    - #### resolveWith

          public Promise<java.lang.Void> resolveWith(Promise<? extends T> with)

      Resolve the Promise associated with this Deferred with the specified Promise.

      If the specified Promise is successfully resolved, the associated Promise is resolved with the value of the specified Promise. If the specified Promise is resolved with a failure, the associated Promise is resolved with the failure of the specified Promise.

      After the associated Promise is resolved with the specified Promise, all registered `callbacks` are called and any `chained` Promises are resolved.

      Resolving the associated Promise happens-before any registered callback is called. That is, in a registered callback, `Promise.isDone()` must return `true` and `Promise.getValue()` and `Promise.getFailure()` must not block.

      Parameters:
        `with` - A Promise whose value or failure must be used to resolve the associated Promise. Must not be `null`.
      Returns:
        A Promise that is resolved only when the associated Promise is resolved by the specified Promise. The returned Promise must be successfully resolved with the value `null`, if the associated Promise was resolved by the specified Promise. The returned Promise must be resolved with a failure of `IllegalStateException`, if the associated Promise was already resolved when the specified Promise was resolved.