com.h3c.of.lib.msg

## Interface MessageFuture

- All Known Implementing Classes:
    DataPathMessageFuture, DefaultMessageFuture

      public interface MessageFuture

  The result of an asynchronous OpenFlow message request/reply interaction.

  Services can choose to return pending OpenFlow message results in the form of message futures. Clients can use these to wait for the results using various forms of the `await` methods and then query the future to determine success or failure.

  TODO: elaborate, more docs: cf netty ChannelFuture

  See Also:
    `MessageFutureBag`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `MessageFuture.Result` Denotes the different states that a message future can be in.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `MessageFuture` | `await()` Waits for this future to be completed.
    `boolean` | `await(long timeoutMs)` Waits for this future to be completed within the specified time limit.
    `MessageFuture` | `awaitUninterruptibly()` Waits for this future to be completed without interruption.
    `boolean` | `awaitUninterruptibly(long timeoutMs)` Waits for this future to be completed within the specified time limit without interruption.
    `Throwable` | `cause()` Returns the cause of failure if an exception was thrown.
    `OpenflowMessage` | `reply()` Returns the reply resulting from the asynchronous request.
    `OpenflowMessage` | `request()` Returns the original request message.
    `MessageFuture.Result` | `result()` Returns the future's result.
    `boolean` | `setFailure(OfmError error)` Marks this future as a failure, attaching the specified error response message, and notifies all listeners.
    `boolean` | `setFailure(Throwable cause)` Marks this future as a failure, caused by the specified exception, and notifies all listeners.
    `boolean` | `setSuccess()` Marks this future as a success (with no expected reply) and notifies all listeners.
    `boolean` | `setSuccess(OpenflowMessage msg)` Marks this future as a success, attaching the specified reply message, and notifies all listeners.
    `long` | `xid()` Returns the xid (message sequence number) associated with this future.

- - ### Method Detail

    - #### xid

          long xid()

      Returns the xid (message sequence number) associated with this future.
      Returns:
        the transaction id

    - #### request

          OpenflowMessage request()

      Returns the original request message.
      Returns:
        the OpenFlow message

    - #### reply

          OpenflowMessage reply()

      Returns the reply resulting from the asynchronous request. If the request was successful, the message will be the corresponding reply. If the request was successful (but no reply was expected), this will be null. If the request failed, the message will be the corresponding `OfmError` message.

      This will be null if the future has not yet been satisfied.

      Returns:
        the OpenFlow message

    - #### cause

          Throwable cause()

      Returns the cause of failure if an exception was thrown.
      Returns:
        the cause of failure

    - #### result

          MessageFuture.Result result()

      Returns the future's result.
      Returns:
        the future's result

    - #### setSuccess

          boolean setSuccess()

      Marks this future as a success (with no expected reply) and notifies all listeners. `true` is returned if this future is successfully marked as a success; `false` is returned if this future was already marked as either success or failure.
      Returns:
        `true` if successfully marked as a success; `false` otherwise

    - #### setSuccess

          boolean setSuccess(OpenflowMessage msg)

      Marks this future as a success, attaching the specified reply message, and notifies all listeners. `true` is returned if this future is successfully marked as a success; `false` is returned if this future was already marked as either success or failure.
      Parameters:
        `msg` - the OpenFlow message reply to the original request
      Returns:
        `true` if successfully marked as a success; `false` otherwise
      Throws:
        `IllegalArgumentException` - if the message is mutable

    - #### setFailure

          boolean setFailure(OfmError error)

      Marks this future as a failure, attaching the specified error response message, and notifies all listeners. `true` is returned if this future is successfully marked as a success; `false` is returned if this future was already marked as either success or failure.
      Parameters:
        `error` - the OpenFlow error message resulting from the original request
      Returns:
        `true` if successfully marked as a success; `false` otherwise
      Throws:
        `IllegalArgumentException` - if the error message is mutable

    - #### setFailure

          boolean setFailure(Throwable cause)

      Marks this future as a failure, caused by the specified exception, and notifies all listeners. `true` is returned if this future is successfully marked as a success; `false` is returned if this future was already marked as either success or failure.
      Parameters:
        `cause` - the cause of the failure
      Returns:
        `true` if successfully marked as a success; `false` otherwise

    - #### await

          MessageFuture await()
                              throws InterruptedException

      Waits for this future to be completed. This call blocks until the future is marked as success or failure.
      Returns:
        self (for method chaining)
      Throws:
        `InterruptedException` - if the current thread was interrupted

    - #### awaitUninterruptibly

          MessageFuture awaitUninterruptibly()

      Waits for this future to be completed without interruption. This call blocks until the future is marked as success or failure. This method catches `InterruptedException`s and discards them silently.
      Returns:
        self (for method chaining)

    - #### await

          boolean await(long timeoutMs)
                        throws InterruptedException

      Waits for this future to be completed within the specified time limit. This call blocks until the future is marked as success or failure, or until the specified amount of time has elapsed. `true` is returned if the future was satisfied within the time limit; `false` is returned if the timeout expired.
      Parameters:
        `timeoutMs` - timeout expressed in milliseconds
      Returns:
        `true` if the future was completed within the specified time limit; `false` otherwise
      Throws:
        `InterruptedException` - if the current thread was interrupted

    - #### awaitUninterruptibly

          boolean awaitUninterruptibly(long timeoutMs)

      Waits for this future to be completed within the specified time limit without interruption. This call blocks until the future is marked as success or failure, or until the specified amount of time has elapsed. `true` is returned if the future was satisfied within the time limit; `false` is returned if the timeout expired. This method catches `InterruptedException`s and discards them silently.
      Parameters:
        `timeoutMs` - timeout expressed in milliseconds
      Returns:
        `true` if the future was completed within the specified time limit; `false` otherwise

Copyright © 2014. All Rights Reserved.