io.vertx.core

## Interface Future<T>

- All Superinterfaces:
    AsyncResult<T>, Handler<AsyncResult<T>>
  All Known Subinterfaces:
    BridgeEvent, CompositeFuture

      public interface Future<T>
      extends AsyncResult<T>, Handler<AsyncResult<T>>

  Represents the result of an action that may, or may not, have occurred yet.

  Author:
    Tim Fox

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static FutureFactory` | `factory`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `Throwable` | `cause()` A Throwable describing failure.
    `void` | `complete()` Set a null result.
    `void` | `complete(T result)` Set the result.
    `default Handler<AsyncResult<T>>` | `completer()`
    `default <U> Future<U>` | `compose(java.util.function.Function<T,Future<U>> mapper)` Compose this future with a `mapper` function.
    `default <U> Future<U>` | `compose(Handler<T> handler, Future<U> next)` Compose this future with a provided `next` future.
    `void` | `fail(String failureMessage)` Try to set the failure.
    `void` | `fail(Throwable cause)` Set the failure.
    `boolean` | `failed()` Did it fail?
    `static <T> Future<T>` | `failedFuture(String failureMessage)` Create a failed future with the specified failure message.
    `static <T> Future<T>` | `failedFuture(Throwable t)` Create a failed future with the specified failure cause.
    `static <T> Future<T>` | `future()` Create a future that hasn't completed yet
    `static <T> Future<T>` | `future(Handler<Future<T>> handler)` Create a future that hasn't completed yet and that is passed to the `handler` before it is returned.
    `void` | `handle(AsyncResult<T> asyncResult)` Succeed or fail this future with the `AsyncResult` event.
    `boolean` | `isComplete()` Has the future completed?
    `default <U> Future<U>` | `map(java.util.function.Function<T,U> mapper)` Apply a `mapper` function on this future.
    `default <V> Future<V>` | `map(V value)` Map the result of a future to a specific `value`.
    `default <V> Future<V>` | `mapEmpty()` Map the result of a future to `null`.
    `default Future<T>` | `otherwise(java.util.function.Function<Throwable,T> mapper)` Apply a `mapper` function on this future.
    `default Future<T>` | `otherwise(T value)` Map the failure of a future to a specific `value`.
    `default Future<T>` | `otherwiseEmpty()` Map the failure of a future to `null`.
    `default Future<T>` | `recover(java.util.function.Function<Throwable,Future<T>> mapper)` Handles a failure of this Future by returning the result of another Future.
    `T` | `result()` The result of the operation.
    `Future<T>` | `setHandler(Handler<AsyncResult<T>> handler)` Set a handler for the result.
    `boolean` | `succeeded()` Did it succeed?
    `static <T> Future<T>` | `succeededFuture()` Create a succeeded future with a null result
    `static <T> Future<T>` | `succeededFuture(T result)` Created a succeeded future with the specified result.
    `boolean` | `tryComplete()` Try to set the result.
    `boolean` | `tryComplete(T result)` Set the failure.
    `boolean` | `tryFail(String failureMessage)` Try to set the failure.
    `boolean` | `tryFail(Throwable cause)` Try to set the failure.

- - ### Field Detail

    - #### factory

          static final FutureFactory factory

  - ### Method Detail

    - #### future

          static <T> Future<T> future(Handler<Future<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.

    - #### future

          static <T> Future<T> future()

      Create a future that hasn't completed yet
      Type Parameters:
        `T` - the result type
      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

    - #### setHandler

          Future<T> setHandler(Handler<AsyncResult<T>> handler)

      Set a handler for the result.

      If the future has already been completed it will be called immediately. Otherwise it will be called when the future is completed.

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

    - #### complete

          void complete(T result)

      Set the result. Any handler will be called, if there is one, and the future will be marked as completed.
      Parameters:
        `result` - the result

    - #### complete

          void complete()

      Set a null result. Any handler will be called, if there is one, and the future will be marked as completed.

    - #### fail

          void fail(Throwable cause)

      Set the failure. Any handler will be called, if there is one, and the future will be marked as completed.
      Parameters:
        `cause` - the failure cause

    - #### fail

          void fail(String failureMessage)

      Try to set the failure. When it happens, any handler will be called, if there is one, and the future will be marked as completed.
      Parameters:
        `failureMessage` - the failure message

    - #### tryComplete

          boolean tryComplete(T result)

      Set the failure. Any handler will be called, if there is one, and the future will be marked as completed.
      Parameters:
        `result` - the result
      Returns:
        false when the future is already completed

    - #### tryComplete

          boolean tryComplete()

      Try to set the result. When it happens, any handler will be called, if there is one, and the future will be marked as completed.
      Returns:
        false when the future is already completed

    - #### tryFail

          boolean tryFail(Throwable cause)

      Try to set the failure. When it happens, any handler will be called, if there is one, and the future will be marked as completed.
      Parameters:
        `cause` - the failure cause
      Returns:
        false when the future is already completed

    - #### tryFail

          boolean tryFail(String failureMessage)

      Try to set the failure. When it happens, any handler will be called, if there is one, and the future will be marked as completed.
      Parameters:
        `failureMessage` - the failure message
      Returns:
        false when the future is already completed

    - #### 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

    - #### compose

          default <U> Future<U> compose(Handler<T> handler,
                                        Future<U> next)

      Compose this future with a provided `next` future.

      When this (the one on which `compose` is called) future succeeds, the `handler` will be called with the completed value, this handler should complete the next future.

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

      When this future fails, the failure will be propagated to the `next` future and the `handler` will not be called.

      Parameters:
        `handler` - the handler
        `next` - the next future
      Returns:
        the next future, used for chaining

    - #### compose

          default <U> Future<U> compose(java.util.function.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

    - #### map

          default <U> Future<U> map(java.util.function.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

          default <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

    - #### handle

          void handle(AsyncResult<T> asyncResult)

      Succeed or fail this future with the `AsyncResult` event.
      Specified by:
        `handle` in interface `Handler<AsyncResult<T>>`
      Parameters:
        `asyncResult` - the async result to handle

    - #### completer

          default Handler<AsyncResult<T>> completer()

      Returns:
        an handler completing this future

    - #### recover

          default Future<T> recover(java.util.function.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

    - #### otherwise

          default Future<T> otherwise(java.util.function.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

          default 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

Copyright © 2017. All rights reserved.