io.vertx.core

## Interface Promise<T>

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

      public interface Promise<T>
      extends Handler<AsyncResult<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 and Description
    --- | ---
    `void` | `complete()` Calls `complete(null)`
    `void` | `complete(T result)` Set the result.
    `void` | `fail(String message)` Calls `fail(Throwable)` with the `message`.
    `void` | `fail(Throwable cause)` Set the failure.
    `static <T> Promise<T>` | `failedPromise(String failureMessage)` Create a failed promise with the specified `failureMessage`.
    `static <T> Promise<T>` | `failedPromise(Throwable cause)` Create a failed promise with the specified failure `cause`.
    `Future<T>` | `future()`
    `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
    `static <T> Promise<T>` | `succeededPromise()` Create a succeeded promise with a `null` result
    `static <T> Promise<T>` | `succeededPromise(T result)` Created a succeeded promise with the specified `result`.
    `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.
    `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

    - #### succeededPromise

          static <T> Promise<T> succeededPromise()

      Create a succeeded promise with a `null` result
      Type Parameters:
        `T` - the result type
      Returns:
        the promise

    - #### succeededPromise

          static <T> Promise<T> succeededPromise(T result)

      Created a succeeded promise with the specified `result`.
      Type Parameters:
        `T` - the result type
      Parameters:
        `result` - the result
      Returns:
        the promise

    - #### failedPromise

          static <T> Promise<T> failedPromise(Throwable cause)

      Create a failed promise with the specified failure `cause`.
      Type Parameters:
        `T` - the result type
      Parameters:
        `cause` - the failure cause as a Throwable
      Returns:
        the promise

    - #### failedPromise

          static <T> Promise<T> failedPromise(String failureMessage)

      Create a failed promise with the specified `failureMessage`.
      Type Parameters:
        `T` - the result type
      Parameters:
        `failureMessage` - the failure message
      Returns:
        the promise

    - #### promise

          static <T> Promise<T> promise()

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

    - #### handle

          void handle(AsyncResult<T> asyncResult)

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

    - #### complete

          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

          void complete()

      Calls `complete(null)`
      Throws:
        `IllegalStateException` - when the promise is already 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
      Throws:
        `IllegalStateException` - when the promise is already completed

    - #### fail

          void fail(String message)

      Calls `fail(Throwable)` with the `message`.
      Parameters:
        `message` - the failure message
      Throws:
        `IllegalStateException` - when the promise is already completed

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

          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

          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

Copyright © 2019 Eclipse. All rights reserved.