Package io.vertx.core

## Interface Promise<T>

- All Superinterfaces:
    `Completable<T>`
  All Known Subinterfaces:
    `BaseBridgeEvent`, `BridgeEvent`, `BridgeEvent`, `ConnectionInitEvent`

      public interface Promise<T>
      extends Completable<T>

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

  The `future()` method returns the `Future` associated with a promise, the future can be used for getting notified of the promise completion and retrieve its value.

  A promise extends `Handler<AsyncResult<T>>` so it can be used as a callback.

  Author:
    Julien Viet

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default void` | `complete()` | Calls `complete(null)`
    `default void` | `complete​(T result)` | Set the result.
    `default void` | `complete​(T result, Throwable failure)` | Complete this instance when `failure` is `null`, a success is signaled otherwise a failure is signaled
    `default void` | `fail​(String message)` | Calls `Completable.fail(Throwable)` with the `message`.
    `default void` | `fail​(Throwable failure)` | Set the failure.
    `Future<T>` | `future()` |
    `default void` | `handle​(AsyncResult<T> asyncResult)` | Succeed or fail this promise with the `AsyncResult` event.
    `static <T> Promise<T>` | `promise()` | Create a promise that hasn't completed yet
    `default void` | `succeed()` | Shortcut for `succeed(null)`
    `default void` | `succeed​(T result)` | Set the result.
    `default boolean` | `tryComplete()` | Calls `tryComplete(null)`.
    `boolean` | `tryComplete​(T result)` | Like `complete(Object)` but returns `false` when the promise is already completed instead of throwing an `IllegalStateException`, it returns `true` otherwise.
    `default boolean` | `tryFail​(String message)` | Calls `fail(Throwable)` with the `message`.
    `boolean` | `tryFail​(Throwable cause)` | Like `fail(Throwable)` but returns `false` when the promise is already completed instead of throwing an `IllegalStateException`, it returns `true` otherwise.

- - ### Method Detail

    - #### promise

          static <T> Promise<T> promise()

      Create a promise that hasn't completed yet
      Type Parameters:
        `T` - the result type
      Returns:
        the promise

    - #### handle

          default void handle​(AsyncResult<T> asyncResult)

      Succeed or fail this promise with the `AsyncResult` event.
      Parameters:
        `asyncResult` - the async result to handle

    - #### complete

          default void complete​(T result,
                                Throwable failure)

      Description copied from interface: `Completable`
      Complete this instance
      - when `failure` is `null`, a success is signaled
      - otherwise a failure is signaled
      Specified by:
        `complete` in interface `Completable<T>`
      Parameters:
        `result` - the result
        `failure` - the failure

    - #### complete

          default void complete​(T result)

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

      Any handler set on the associated promise will be called.
      Parameters:
        `result` - the result
      Throws:
        `IllegalStateException` - when the promise is already completed

    - #### complete

          default void complete()

      Calls `complete(null)`
      Throws:
        `IllegalStateException` - when the promise is already completed

    - #### succeed

          default void succeed​(T result)

      Description copied from interface: `Completable`
      Set the result. The instance will be marked as succeeded and completed.

      Specified by:
        `succeed` in interface `Completable<T>`
      Parameters:
        `result` - the result

    - #### succeed

          default void succeed()

      Description copied from interface: `Completable`
      Shortcut for `succeed(null)`
      Specified by:
        `succeed` in interface `Completable<T>`

    - #### fail

          default void fail​(Throwable failure)

      Description copied from interface: `Completable`
      Set the failure. This instance will be marked as failed and completed.
      Specified by:
        `fail` in interface `Completable<T>`
      Parameters:
        `failure` - the failure

    - #### fail

          default void fail​(String message)

      Description copied from interface: `Completable`
      Calls `Completable.fail(Throwable)` with the `message`.
      Specified by:
        `fail` in interface `Completable<T>`
      Parameters:
        `message` - the failure message

    - #### tryComplete

          boolean tryComplete​(T result)

      Like `complete(Object)` but returns `false` when the promise is already completed instead of throwing an `IllegalStateException`, it returns `true` otherwise.
      Parameters:
        `result` - the result
      Returns:
        `false` when the future is already completed

    - #### tryComplete

          default boolean tryComplete()

      Calls `tryComplete(null)`.
      Returns:
        `false` when the future is already completed

    - #### tryFail

          boolean tryFail​(Throwable cause)

      Like `fail(Throwable)` but returns `false` when the promise is already completed instead of throwing an `IllegalStateException`, it returns `true` otherwise.
      Parameters:
        `cause` - the failure cause
      Returns:
        `false` when the future is already completed

    - #### tryFail

          default boolean tryFail​(String message)

      Calls `fail(Throwable)` with the `message`.
      Parameters:
        `message` - the failure message
      Returns:
        false when the future is already completed

    - #### future

          Future<T> future()

      Returns:
        the `Future` associated with this promise, it can be used to be aware of the promise completion