WindowFuture (ch-commons-util 6.0.2 API)

All Known Implementing Classes:: DefaultWindowFuture

public interface WindowFuture<K,R,P>

A WindowFuture is either uncompleted or completed. When an operation begins, a new future object is created. The new future is uncompleted initially - it is neither succeeded, failed, nor cancelled because the operation is not finished yet. If the operation is finished either successfully, with failure, or by cancellation, the future is marked as completed with more specific information, such as the cause of the failure. Please note that even failure and cancellation belong to the completed state.

                                      +---------------------------+
                                      | Completed successfully    |
                                      +---------------------------+
                                 +---->      isDone() = true      |
 +--------------------------+    |    |   isSuccess() = true      |
 |        Uncompleted       |    |    +===========================+
 +--------------------------+    |    | Completed with failure    |
 |      isDone() = false    |    |    +---------------------------+
 |   isSuccess() = false    |----+---->   isDone() = true         |
 | isCancelled() = false    |    |    | getCause() = non-null     |
 |    getCause() = null     |    |    +===========================+
 +--------------------------+    |    | Completed by cancellation |
                                 |    +---------------------------+
                                 +---->      isDone() = true      |
                                      | isCancelled() = true      |
                                      +---------------------------+

Author:: joelauer (twitter: @jjlauer or http://twitter.com/jjlauer)

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CALLER_NOT_WAITING` The caller is not waiting on this entry
`static int`	`CALLER_WAITING` The caller is waiting on this entry
`static int`	`CALLER_WAITING_TIMEOUT` The caller was waiting, but gave up (timeout)

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`await()` Waits for this future to be completed within the amount of time remaining from the original offerTimeoutMillis minus the amount of time it took for the Window to accept the offer.
`boolean`	`await(long timeoutMillis)` Waits for this future to be completed within the specified time limit.
`void`	`cancel()` Completes (as a cancel) a request.
`void`	`cancel(long doneTimestamp)` Completes (as a cancel) a request.
`void`	`complete(P response)` Completes (as a success) a request by setting the response.
`void`	`complete(P response, long doneTimestamp)` Completes (as a success) a request by setting the response.
`void`	`fail(Throwable t)` Completes (as a failure) a request by setting a throwable as the cause of failure.
`void`	`fail(Throwable t, long doneTimestamp)` Completes (as a failure) a request by setting a throwable as the cause of failure.
`long`	`getAcceptTimestamp()` Gets the accept timestamp in milliseconds.
`long`	`getAcceptToDoneTime()` Gets the amount of time (in ms) from accept to done or -1 if a done timestamp does not yet exist.
`int`	`getCallerStateHint()` Gets a hint of the caller state such as whether the caller is waiting, not waiting, or timed out while waiting for completion.
`Throwable`	`getCause()` Returns the cause of the failed operation if the operation has failed.
`long`	`getDoneTimestamp()` Gets the done timestamp in milliseconds.
`long`	`getExpireTimestamp()` Gets the expire timestamp in milliseconds.
`K`	`getKey()` Gets the key of the window entry.
`long`	`getOfferTimestamp()` Gets the offer timestamp in milliseconds.
`long`	`getOfferToAcceptTime()` Gets the amount of time (in ms) from offer to accept.
`long`	`getOfferToDoneTime()` Gets the amount of time (in ms) from offer to done or -1 if a done timestamp does not yet exist.
`R`	`getRequest()` Gets the request contained in the window entry.
`P`	`getResponse()` Gets the response associated with the window entry.
`int`	`getWindowSize()` Returns the size of the window (number of requests in it) after this request was added.
`boolean`	`hasDoneTimestamp()` Returns true if a done timestamp value exists (> 0).
`boolean`	`hasExpireTimestamp()` Returns true if an expire timestamp value exists (> 0).
`boolean`	`isCallerWaiting()` Returns `true` if and only if the caller hinted at "WAITING" for completion.
`boolean`	`isCancelled()` Returns `true` if and only if this future was cancelled by a cancel() method.
`boolean`	`isDone()` Returns `true` if and only if this future is complete, regardless of whether the operation was successful, failed, or cancelled.
`boolean`	`isSuccess()` Returns `true` if and only if the operation was completed successfully.

- Field Detail
  - CALLER_NOT_WAITING
```
static final int CALLER_NOT_WAITING
```
    The caller is not waiting on this entry
    
    See Also:
    Constant Field Values
  - CALLER_WAITING
```
static final int CALLER_WAITING
```
    The caller is waiting on this entry
    
    See Also:
    Constant Field Values
  - CALLER_WAITING_TIMEOUT
```
static final int CALLER_WAITING_TIMEOUT
```
    The caller was waiting, but gave up (timeout)
    
    See Also:
    Constant Field Values
- Method Detail
  - getKey
```
K getKey()
```
    Gets the key of the window entry.
    
    Returns:
    The key of the window entry.
  - getRequest
```
R getRequest()
```
    Gets the request contained in the window entry.
    
    Returns:
    The request contained in the window entry.
  - getResponse
```
P getResponse()
```
    Gets the response associated with the window entry.
    
    Returns:
    The response associated with he request or null if no response has been received.
  - isDone
```
boolean isDone()
```
    Returns true if and only if this future is complete, regardless of whether the operation was successful, failed, or cancelled.
  - isSuccess
```
boolean isSuccess()
```
    Returns true if and only if the operation was completed successfully.
  - getCause
```
Throwable getCause()
```
    Returns the cause of the failed operation if the operation has failed.
    
    Returns:
    the cause of the failure. null if succeeded or this future is not completed yet.
  - isCancelled
```
boolean isCancelled()
```
    Returns true if and only if this future was cancelled by a cancel() method.
  - getCallerStateHint
```
int getCallerStateHint()
```
    Gets a hint of the caller state such as whether the caller is waiting, not waiting, or timed out while waiting for completion.
    
    Returns:
    The hint of the state of the caller
  - isCallerWaiting
```
boolean isCallerWaiting()
```
    Returns true if and only if the caller hinted at "WAITING" for completion. Returns false if the caller either did not hint at planning on "WAITING" or did wait but timed out and gave up. Please note that even if this returns true, it does not mean the caller is actively waiting since this merely represents a hint.
  - getWindowSize
```
int getWindowSize()
```
    Returns the size of the window (number of requests in it) after this request was added. Useful for calculating an estimated response time just for this request.
    
    Returns:
    The size of the window after this request was added.
  - hasExpireTimestamp
```
boolean hasExpireTimestamp()
```
    Returns true if an expire timestamp value exists (> 0).
    
    Returns:
    True if an expire timestamp exists
  - getExpireTimestamp
```
long getExpireTimestamp()
```
    Gets the expire timestamp in milliseconds. The expire timestamp is when the request expires unless this optional field was not set.
    
    Returns:
    The expire timestamp or <= 0 if it doesn't exist.
    See Also:
    hasExpireTimestamp()
  - getOfferTimestamp
```
long getOfferTimestamp()
```
    Gets the offer timestamp in milliseconds. The offer timestamp is when the request was offered for acceptance to the window.
    
    Returns:
    The offer timestamp
  - getAcceptTimestamp
```
long getAcceptTimestamp()
```
    Gets the accept timestamp in milliseconds. The accept timestamp is when the request was accepted by the window.
    
    Returns:
    The accept timestamp
  - getOfferToAcceptTime
```
long getOfferToAcceptTime()
```
    Gets the amount of time (in ms) from offer to accept.
    
    Returns:
    The amount of time from offer to accept
  - hasDoneTimestamp
```
boolean hasDoneTimestamp()
```
    Returns true if a done timestamp value exists (> 0).
    
    Returns:
    True if a done timestamp exists
  - getDoneTimestamp
```
long getDoneTimestamp()
```
    Gets the done timestamp in milliseconds. The done timestamp is when the request has been completed.
    
    Returns:
    The done timestamp
  - getOfferToDoneTime
```
long getOfferToDoneTime()
```
    Gets the amount of time (in ms) from offer to done or -1 if a done timestamp does not yet exist.
    
    Returns:
    The amount of time from offer to done
  - getAcceptToDoneTime
```
long getAcceptToDoneTime()
```
    Gets the amount of time (in ms) from accept to done or -1 if a done timestamp does not yet exist.
    
    Returns:
    The amount of time from accept to done
  - complete
```
void complete(P response)
```
    Completes (as a success) a request by setting the response. This method will set the done timestamp to System.currentTimeMillis().
    
    Parameters:
    response - The response for the associated request
  - complete
```
void complete(P response,
            long doneTimestamp)
```
    Completes (as a success) a request by setting the response.
    
    Parameters:
    response - The response for the associated request
    doneTimestamp - The timestamp when the request completed
  - fail
```
void fail(Throwable t)
```
    Completes (as a failure) a request by setting a throwable as the cause of failure. This method will set the done timestamp to System.currentTimeMillis()
    
    Parameters:
    t - The throwable as the cause of failure
  - fail
```
void fail(Throwable t,
        long doneTimestamp)
```
    Completes (as a failure) a request by setting a throwable as the cause of failure.
    
    Parameters:
    t - The throwable as the cause of failure
    doneTimestamp - The timestamp when the request failed
  - cancel
```
void cancel()
```
    Completes (as a cancel) a request. This method will set the done timestamp to System.currentTimeMillis().
  - cancel
```
void cancel(long doneTimestamp)
```
    Completes (as a cancel) a request.
    
    Parameters:
    doneTimestamp - The timestamp when the request was cancelled
  - await
```
boolean await()
              throws InterruptedException
```
    Waits for this future to be completed within the amount of time remaining from the original offerTimeoutMillis minus the amount of time it took for the Window to accept the offer. For example, if Window.offer was called with an offerTimeoutMillis of 5000 milliseconds and it took 1000 milliseconds for the Window to accept the offer, then this method would wait for 4000 milliseconds.
    
    Returns:
    True if and only if the future was completed within the specified time limit
    
    Throws:
    
    InterruptedException - Thrown if the current thread was interrupted
  - await
```
boolean await(long timeoutMillis)
              throws InterruptedException
```
    Waits for this future to be completed within the specified time limit.
    
    Parameters:
    timeoutMillis - The amount of milliseconds to wait
    
    Returns:
    True if and only if the future was completed within the specified time limit
    
    Throws:
    
    InterruptedException - Thrown if the current thread was interrupted

Interface WindowFuture<K,R,P>

Field Summary

Method Summary

Field Detail

CALLER_NOT_WAITING

CALLER_WAITING

CALLER_WAITING_TIMEOUT

Method Detail

getKey

getRequest

getResponse

isDone

isSuccess

getCause

isCancelled

getCallerStateHint

isCallerWaiting

getWindowSize

hasExpireTimestamp

getExpireTimestamp

getOfferTimestamp

getAcceptTimestamp

getOfferToAcceptTime

hasDoneTimestamp

getDoneTimestamp

getOfferToDoneTime

getAcceptToDoneTime

complete

complete

fail

fail

cancel

cancel

await

await