DeferredResult (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.web.context.request.async

## Class DeferredResult<T>

- java.lang.Object
- - org.springframework.web.context.request.async.DeferredResult<T>

-     public class DeferredResult<T>
      extends Object

  `DeferredResult` provides an alternative to using a `Callable` for asynchronous request processing. While a `Callable` is executed concurrently on behalf of the application, with a `DeferredResult` the application can produce the result from a thread of its choice.

  Subclasses can extend this class to easily associate additional data or behavior with the `DeferredResult`. For example, one might want to associate the user used to create the `DeferredResult` by extending the class and adding an additional property for the user. In this way, the user could easily be accessed later without the need to use a data structure to do the mapping.

  An example of associating additional behavior to this class might be realized by extending the class to implement an additional interface. For example, one might want to implement `Comparable` so that when the `DeferredResult` is added to a `PriorityQueue` it is handled in the correct order.

  Since:
    3.2
  Author:
    Rossen Stoyanchev, Rob Winch

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `DeferredResult.DeferredResultHandler` Handles a DeferredResult value when set.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DeferredResult()` Create a DeferredResult.
    `DeferredResult(long timeout)` Create a DeferredResult with a timeout value.
    `DeferredResult(Long timeout, Object timeoutResult)` Create a DeferredResult with a timeout value and a default result to use in case of timeout.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isSetOrExpired()` Return `true` if this DeferredResult is no longer usable either because it was previously set or because the underlying request expired.
    `void` | `onCompletion(Runnable callback)` Register code to invoke when the async request completes.
    `void` | `onTimeout(Runnable callback)` Register code to invoke when the async request times out.
    `boolean` | `setErrorResult(Object result)` Set an error value for the `DeferredResult` and handle it.
    `boolean` | `setResult(T result)` Set the value for the DeferredResult and handle it.
    `void` | `setResultHandler(DeferredResult.DeferredResultHandler resultHandler)` Provide a handler to use to handle the result value.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DeferredResult

          public DeferredResult()

      Create a DeferredResult.

    - #### DeferredResult

          public DeferredResult(long timeout)

      Create a DeferredResult with a timeout value.
      Parameters:
        `timeout` - timeout value in milliseconds

    - #### DeferredResult

          public DeferredResult(Long timeout,
                        Object timeoutResult)

      Create a DeferredResult with a timeout value and a default result to use in case of timeout.
      Parameters:
        `timeout` - timeout value in milliseconds; ignored if `null`
        `timeoutResult` - the result to use

  - ### Method Detail

    - #### isSetOrExpired

          public final boolean isSetOrExpired()

      Return `true` if this DeferredResult is no longer usable either because it was previously set or because the underlying request expired.

      The result may have been set with a call to `setResult(Object)`, or `setErrorResult(Object)`, or as a result of a timeout, if a timeout result was provided to the constructor. The request may also expire due to a timeout or network error.

    - #### onTimeout

          public void onTimeout(Runnable callback)

      Register code to invoke when the async request times out. This method is called from a container thread when an async request times out before the `DeferredResult` has been set. It may invoke `setResult` or `setErrorResult` to resume processing.

    - #### onCompletion

          public void onCompletion(Runnable callback)

      Register code to invoke when the async request completes. This method is called from a container thread when an async request completed for any reason including timeout and network error. This method is useful for detecting that a `DeferredResult` instance is no longer usable.

    - #### setResultHandler

          public final void setResultHandler(DeferredResult.DeferredResultHandler resultHandler)

      Provide a handler to use to handle the result value.
      Parameters:
        `resultHandler` - the handler
      See Also:
        `DeferredResultProcessingInterceptor`

    - #### setResult

          public boolean setResult(T result)

      Set the value for the DeferredResult and handle it.
      Parameters:
        `result` - the value to set
      Returns:
        "true" if the result was set and passed on for handling; "false" if the result was already set or the async request expired.
      See Also:
        `isSetOrExpired()`

    - #### setErrorResult

          public boolean setErrorResult(Object result)

      Set an error value for the `DeferredResult` and handle it. The value may be an `Exception` or `Throwable` in which case it will be processed as if a handler raised the exception.
      Parameters:
        `result` - the error result value
      Returns:
        "true" if the result was set to the error value and passed on for handling; "false" if the result was already set or the async request expired.
      See Also:
        `isSetOrExpired()`