Package org.osgi.util.promise

Class Deferred<T>

  • Type Parameters:
    T - The value type associated with the created Promise.
    @ProviderType
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 Description
      Deferred()
      Create a new Deferred.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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​(java.util.concurrent.CompletionStage<? extends T> with)
      Resolve the Promise associated with this Deferred with the specified CompletionStage.
      Promise<java.lang.Void> resolveWith​(Promise<? extends T> with)
      Resolve the Promise associated with this Deferred with the specified Promise.
      java.lang.String toString()
      Returns a string representation of the associated Promise.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Method Detail

      • getPromise

        public Promise<T> getPromise()
        Returns the Promise associated with this Deferred.

        All Promise objects created by the associated Promise will use the executors of the associated Promise.

        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. This may occur asynchronously to this method.

        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. This may occur asynchronously to this method.

        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. This may occur asynchronously to this method.

        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.

      • toString

        public java.lang.String toString()
        Returns a string representation of the associated Promise.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representation of the associated Promise.
        Since:
        1.1

      • resolveWith

        public Promise<java.lang.Void> resolveWith​(java.util.concurrent.CompletionStage<? extends T> with)
        Resolve the Promise associated with this Deferred with the specified CompletionStage.

        If the specified CompletionStage is completed normally, the associated Promise is resolved with the value of the specified CompletionStage. If the specified CompletionStage is completed exceptionally, the associated Promise is resolved with the failure of the specified CompletionStage.

        After the associated Promise is resolved with the specified CompletionStage, all registered callbacks are called and any chained Promises are resolved. This may occur asynchronously to this method.

        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 CompletionStage whose result 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 CompletionStage. The returned Promise must be successfully resolved with the value null, if the associated Promise was resolved by the specified CompletionStage. The returned Promise must be resolved with a failure of IllegalStateException, if the associated Promise was already resolved when the specified CompletionStage was completed.
        Since:
        1.2