Package dev.webfx.platform.async

Interface Future<T>

All Superinterfaces:
AsyncResult<T>
All Known Subinterfaces:
CompositeFuture, FutureInternal<T>, PromiseInternal<T>
All Known Implementing Classes:
CompositeFutureImpl, FailedFuture, FutureImpl, PromiseImpl, SucceededFuture
public interface Future<T> extends AsyncResult<T>
Represents the result of an action that may, or may not, have occurred yet.

Author:
Tim Fox

  • Method Details

    • all

      static CompositeFuture all(Future<?> f1, Future<?> f2)
      Return a composite future, succeeded when all futures are succeeded, failed when any future is failed.

      The returned future fails as soon as one of f1 or f2 fails.

      Parameters:
      f1 - future
      f2 - future
      Returns:
      the composite future

    • all

      static CompositeFuture all(Future<?> f1, Future<?> f2, Future<?> f3)
      Like all(Future, Future) but with 3 futures.

    • all

      static CompositeFuture all(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4)
      Like all(Future, Future) but with 4 futures.

    • all

      static CompositeFuture all(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5)
      Like all(Future, Future) but with 5 futures.

    • all

      static CompositeFuture all(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5, Future<?> f6)
      Like all(Future, Future) but with 6 futures.

    • all

      static CompositeFuture all(List<? extends Future<?>> futures)
      Like all(Future, Future) but with a list of futures.

      When the list is empty, the returned future will be already completed.

    • any

      static CompositeFuture any(Future<?> f1, Future<?> f2)
      Return a composite future, succeeded when any futures is succeeded, failed when all futures are failed.

      The returned future succeeds as soon as one of f1 or f2 succeeds.

      Parameters:
      f1 - future
      f2 - future
      Returns:
      the composite future

    • any

      static CompositeFuture any(Future<?> f1, Future<?> f2, Future<?> f3)
      Like any(Future, Future) but with 3 futures.

    • any

      static CompositeFuture any(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4)
      Like any(Future, Future) but with 4 futures.

    • any

      static CompositeFuture any(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5)
      Like any(Future, Future) but with 5 futures.

    • any

      static CompositeFuture any(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5, Future<?> f6)
      Like any(Future, Future) but with 6 futures.

    • any

      static CompositeFuture any(List<? extends Future<?>> futures)
      Like any(Future, Future) but with a list of futures.

      When the list is empty, the returned future will be already completed.

    • join

      static CompositeFuture join(Future<?> f1, Future<?> f2)
      Return a composite future, succeeded when all futures are succeeded, failed when any future is failed.

      It always wait until all its futures are completed and will not fail as soon as one of f1 or f2 fails.

      Parameters:
      f1 - future
      f2 - future
      Returns:
      the composite future

    • join

      static CompositeFuture join(Future<?> f1, Future<?> f2, Future<?> f3)
      Like join(Future, Future) but with 3 futures.

    • join

      static CompositeFuture join(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4)
      Like join(Future, Future) but with 4 futures.

    • join

      static CompositeFuture join(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5)
      Like join(Future, Future) but with 5 futures.

    • join

      static CompositeFuture join(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5, Future<?> f6)
      Like join(Future, Future) but with 6 futures.

    • join

      static CompositeFuture join(List<? extends Future<?>> futures)
      Like join(Future, Future) but with a list of futures.

      When the list is empty, the returned future will be already completed.

    • future

      static <T> Future<T> future(Handler<Promise<T>> handler)
      Create a future that hasn't completed yet and that is passed to the handler before it is returned.
      Type Parameters:
      T - the result type
      Parameters:
      handler - the handler
      Returns:
      the future.

    • succeededFuture

      static <T> Future<T> succeededFuture()
      Create a succeeded future with a null result
      Type Parameters:
      T - the result type
      Returns:
      the future

    • succeededFuture

      static <T> Future<T> succeededFuture(T result)
      Created a succeeded future with the specified result.
      Type Parameters:
      T - the result type
      Parameters:
      result - the result
      Returns:
      the future

    • failedFuture

      static <T> Future<T> failedFuture(Throwable t)
      Create a failed future with the specified failure cause.
      Type Parameters:
      T - the result type
      Parameters:
      t - the failure cause as a Throwable
      Returns:
      the future

    • failedFuture

      static <T> Future<T> failedFuture(String failureMessage)
      Create a failed future with the specified failure message.
      Type Parameters:
      T - the result type
      Parameters:
      failureMessage - the failure message
      Returns:
      the future

    • isComplete

      boolean isComplete()
      Has the future completed?

      It's completed if it's either succeeded or failed.

      Returns:
      true if completed, false if not

    • onComplete

      Future<T> onComplete(Handler<AsyncResult<T>> handler)
      Add a handler to be notified of the result.

      WARNING: this is a terminal operation. If several handlers are registered, there is no guarantee that they will be invoked in order of registration.

      Parameters:
      handler - the handler that will be called with the result
      Returns:
      a reference to this, so it can be used fluently

    • onComplete

      default Future<T> onComplete(Handler<T> successHandler, Handler<Throwable> failureHandler)
      Add handlers to be notified on succeeded result and failed result.

      WARNING: this is a terminal operation. If several handlers are registered, there is no guarantee that they will be invoked in order of registration.

      Parameters:
      successHandler - the handler that will be called with the succeeded result
      failureHandler - the handler that will be called with the failed result
      Returns:
      a reference to this, so it can be used fluently

    • onSuccess

      default Future<T> onSuccess(Handler<T> handler)
      Add a handler to be notified of the succeeded result.

      WARNING: this is a terminal operation. If several handlers are registered, there is no guarantee that they will be invoked in order of registration.

      Parameters:
      handler - the handler that will be called with the succeeded result
      Returns:
      a reference to this, so it can be used fluently

    • onFailure

      default Future<T> onFailure(Handler<Throwable> handler)
      Add a handler to be notified of the failed result.

      WARNING: this is a terminal operation. If several handlers are registered, there is no guarantee that they will be invoked in order of registration.

      Parameters:
      handler - the handler that will be called with the failed result
      Returns:
      a reference to this, so it can be used fluently

    • result

      T result()
      The result of the operation. This will be null if the operation failed.
      Specified by:
      result in interface AsyncResult<T>
      Returns:
      the result or null if the operation failed.

    • cause

      Throwable cause()
      A Throwable describing failure. This will be null if the operation succeeded.
      Specified by:
      cause in interface AsyncResult<T>
      Returns:
      the cause or null if the operation succeeded.

    • succeeded

      boolean succeeded()
      Did it succeed?
      Specified by:
      succeeded in interface AsyncResult<T>
      Returns:
      true if it succeded or false otherwise

    • failed

      boolean failed()
      Did it fail?
      Specified by:
      failed in interface AsyncResult<T>
      Returns:
      true if it failed or false otherwise

    • flatMap

      default <U> Future<U> flatMap(Function<T,Future<U>> mapper)
      Alias for compose(Function).

    • compose

      default <U> Future<U> compose(Function<T,Future<U>> mapper)
      Compose this future with a mapper function.

      When this future (the one on which compose is called) succeeds, the mapper will be called with the completed value and this mapper returns another future object. This returned future completion will complete the future returned by this method call.

      If the mapper throws an exception, the returned future will be failed with this exception.

      When this future fails, the failure will be propagated to the returned future and the mapper will not be called.

      Parameters:
      mapper - the mapper function
      Returns:
      the composed future

    • recover

      default Future<T> recover(Function<Throwable,Future<T>> mapper)
      Handles a failure of this Future by returning the result of another Future. If the mapper fails, then the returned future will be failed with this failure.
      Parameters:
      mapper - A function which takes the exception of a failure and returns a new future.
      Returns:
      A recovered future

    • compose

      <U> Future<U> compose(Function<T,Future<U>> successMapper, Function<Throwable,Future<U>> failureMapper)
      Compose this future with a successMapper and failureMapper functions.

      When this future (the one on which compose is called) succeeds, the successMapper will be called with the completed value and this mapper returns another future object. This returned future completion will complete the future returned by this method call.

      When this future (the one on which compose is called) fails, the failureMapper will be called with the failure and this mapper returns another future object. This returned future completion will complete the future returned by this method call.

      If any mapper function throws an exception, the returned future will be failed with this exception.

      Parameters:
      successMapper - the function mapping the success
      failureMapper - the function mapping the failure
      Returns:
      the composed future

    • transform

      <U> Future<U> transform(Function<AsyncResult<T>,Future<U>> mapper)
      Transform this future with a mapper functions.

      When this future (the one on which transform is called) completes, the mapper will be called with the async result and this mapper returns another future object. This returned future completion will complete the future returned by this method call.

      If any mapper function throws an exception, the returned future will be failed with this exception.

      Parameters:
      mapper - the function mapping the future
      Returns:
      the transformed future

    • eventually

      @Deprecated <U> Future<T> eventually(Function<Void,Future<U>> function)
      Deprecated.
      instead use eventually(Supplier), this method will be removed in Vert.x 5
      Compose this future with a function that will be always be called.

      When this future (the one on which eventually is called) completes, the function will be called and this mapper returns another future object. This returned future completion will complete the future returned by this method call with the original result of the future.

      The outcome of the future returned by the function will not influence the nature of the returned future.

      Parameters:
      function - the function returning the future.
      Returns:
      the composed future

    • eventually

      default <U> Future<T> eventually(Supplier<Future<U>> supplier)
      Compose this future with a supplier that will be always be called.

      When this future (the one on which eventually is called) completes, the supplier will be called and this mapper returns another future object. This returned future completion will complete the future returned by this method call with the original result of the future.

      The outcome of the future returned by the supplier will not influence the nature of the returned future.

      Parameters:
      supplier - the function returning the future.
      Returns:
      the composed future

    • map

      <U> Future<U> map(Function<T,U> mapper)
      Apply a mapper function on this future.

      When this future succeeds, the mapper will be called with the completed value and this mapper returns a value. This value will complete the future returned by this method call.

      If the mapper throws an exception, the returned future will be failed with this exception.

      When this future fails, the failure will be propagated to the returned future and the mapper will not be called.

      Specified by:
      map in interface AsyncResult<T>
      Parameters:
      mapper - the mapper function
      Returns:
      the mapped future

    • map

      <V> Future<V> map(V value)
      Map the result of a future to a specific value.

      When this future succeeds, this value will complete the future returned by this method call.

      When this future fails, the failure will be propagated to the returned future.

      Specified by:
      map in interface AsyncResult<T>
      Parameters:
      value - the value that eventually completes the mapped future
      Returns:
      the mapped future

    • mapEmpty

      default <V> Future<V> mapEmpty()
      Map the result of a future to null.

      This is a conveniency for future.map((T) null) or future.map((Void) null).

      When this future succeeds, null will complete the future returned by this method call.

      When this future fails, the failure will be propagated to the returned future.

      Specified by:
      mapEmpty in interface AsyncResult<T>
      Returns:
      the mapped future

    • otherwise

      Future<T> otherwise(Function<Throwable,T> mapper)
      Apply a mapper function on this future.

      When this future fails, the mapper will be called with the completed value and this mapper returns a value. This value will complete the future returned by this method call.

      If the mapper throws an exception, the returned future will be failed with this exception.

      When this future succeeds, the result will be propagated to the returned future and the mapper will not be called.

      Specified by:
      otherwise in interface AsyncResult<T>
      Parameters:
      mapper - the mapper function
      Returns:
      the mapped future

    • otherwise

      Future<T> otherwise(T value)
      Map the failure of a future to a specific value.

      When this future fails, this value will complete the future returned by this method call.

      When this future succeeds, the result will be propagated to the returned future.

      Specified by:
      otherwise in interface AsyncResult<T>
      Parameters:
      value - the value that eventually completes the mapped future
      Returns:
      the mapped future

    • otherwiseEmpty

      default Future<T> otherwiseEmpty()
      Map the failure of a future to null.

      This is a convenience for future.otherwise((T) null).

      When this future fails, the null value will complete the future returned by this method call.

      When this future succeeds, the result will be propagated to the returned future.

      Specified by:
      otherwiseEmpty in interface AsyncResult<T>
      Returns:
      the mapped future

    • andThen

      default Future<T> andThen(Handler<AsyncResult<T>> handler)
      Invokes the given handler upon completion.

      If the handler throws an exception, the returned future will be failed with this exception.

      Parameters:
      handler - invoked upon completion of this future
      Returns:
      a future completed after the handler has been invoked