Window (ch-commons-util 6.0.2 API)

java.lang.Object
- com.cloudhopper.commons.util.windowing.Window<K,R,P>

```
public class Window<K,R,P>
extends Object
```
A utility class to support "windowed" protocols that permit requests to be sent asynchronously and the responses to be processed at a later time. Responses may be returned in a different order than requests were sent.

Windowed protocols generally provide high throughput over high latency links such as TCP/IP connections since they allow requests one after the other without waiting for a response before sending the next request. This allows the underlying TCP/IP socket to potentially buffer multiple requests in one packet.

The "window" is the amount of unacknowledged requests that are permitted to be outstanding/unacknowledged at any given time. This implementation allows a max window size to be defined during construction. This represents the number of open "slots". When a response is received, it's up to the user of this class to make sure that response is added so that any threads waiting for a response are properly signaled.

The life cycle of a request in a Window has 3 steps:
1. Request offered
  - If free slot exists then goto 2
  - If no free slot exists, offer now "pending" and block for specified time. May either timeout or if free slot opens, then goto 2
2. Request accepted (caller may optionally await() on returned future till completion)
3. Request completed/done (either success, failure, or cancelled)
If monitoring is enabled, it's very important to call "freeExternalResources()" if a Window will no longer be used.
Author:

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

Constructor Summary

Constructors
Constructor and Description
`Window(int size)` Creates a new window with the specified max window size.
`Window(int size, ScheduledExecutorService executor, long monitorInterval, WindowListener<K,R,P> listener)` Creates a new window with the specified max window size.
`Window(int size, ScheduledExecutorService executor, long monitorInterval, WindowListener<K,R,P> listener, String monitorThreadName)` Creates a new window with the specified max window size.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`abortPendingOffers()` Aborts all current callers/threads waiting for a pending offer to be accepted by the window.
`void`	`addListener(WindowListener<K,R,P> listener)` Adds a new WindowListener if and only if it isn't already present.
`WindowFuture<K,R,P>`	`cancel(K key)` Cancels (completes) a request.
`List<WindowFuture<K,R,P>>`	`cancelAll()` Cancels (completes) all requests.
`List<WindowFuture<K,R,P>>`	`cancelAllExpired()` Cancels (completes) all expired requests.
`WindowFuture<K,R,P>`	`complete(K key, P response)` Successfully completes a request by setting the response on the associated future.
`boolean`	`containsKey(K key)` Returns true if and only if a future with this key exists in this window.
`Map<K,WindowFuture<K,R,P>>`	`createSortedSnapshot()` Creates an ordered snapshot of the requests in this window.
`void`	`destroy()` Destroy this window by freeing all resources associated with it.
`WindowFuture<K,R,P>`	`fail(K key, Throwable t)` Fails (completes) a request by setting the cause of the failure on the associated future.
`List<WindowFuture<K,R,P>>`	`failAll(Throwable t)` Fails (completes) all requests by setting the same cause of the failure on all associated futures.
`WindowFuture<K,R,P>`	`get(K key)` Gets the a future by its key.
`int`	`getFreeSize()` Gets the current number of request that would be accepted by this window without blocking.
`int`	`getMaxSize()` Gets the max size of the window.
`int`	`getPendingOfferCount()` Gets the current number of callers/threads that are waiting for a pending offer to be accepted.
`int`	`getSize()` Gets the current number of requests in the window.
`WindowFuture`	`offer(K key, R request, long offerTimeoutMillis)` Offers a request for acceptance, waiting for the specified amount of time in case it could not immediately accepted.
`WindowFuture`	`offer(K key, R request, long offerTimeoutMillis, long expireTimeoutMillis)` Offers a request for acceptance, waiting for the specified amount of time in case it could not immediately accepted.
`WindowFuture`	`offer(K key, R request, long offerTimeoutMillis, long expireTimeoutMillis, boolean callerWaitingHint)` Offers a request for acceptance, waiting for the specified amount of time in case it could not immediately accepted.
`void`	`removeListener(WindowListener<K,R,P> listener)` Removes a WindowListener if it is present.
`boolean`	`startMonitor()` Starts the monitor if this Window has an executor.
`void`	`stopMonitor()` Stops the monitor if its running.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Window
```
public Window(int size)
```
    Creates a new window with the specified max window size. This constructor does not enable any automatic recurring tasks from being executed (such as expiration of requests).
    
    Parameters:
    size - The maximum number of requests permitted to be outstanding (unacknowledged) at a given time. Must be > 0.
  - Window
```
public Window(int size,
      ScheduledExecutorService executor,
      long monitorInterval,
      WindowListener<K,R,P> listener)
```
    Creates a new window with the specified max window size. This constructor enables automatic recurring tasks to be executed (such as expiration of requests).
    
    Parameters:
    size - The maximum number of requests permitted to be outstanding (unacknowledged) at a given time. Must be > 0.
    executor - The scheduled executor service to execute recurring tasks (such as expiration of requests).
    monitorInterval - The number of milliseconds between executions of monitoring tasks.
    listener - A listener to send window events to
  - Window
```
public Window(int size,
      ScheduledExecutorService executor,
      long monitorInterval,
      WindowListener<K,R,P> listener,
      String monitorThreadName)
```
    Creates a new window with the specified max window size. This constructor enables automatic recurring tasks to be executed (such as expiration of requests).
    
    Parameters:
    size - The maximum number of requests permitted to be outstanding (unacknowledged) at a given time. Must be > 0.
    executor - The scheduled executor service to execute recurring tasks (such as expiration of requests).
    monitorInterval - The number of milliseconds between executions of monitoring tasks.
    listener - A listener to send window events to
    monitorThreadName - The thread name we'll change to when a monitor run is executed. Null if no name change is required.
- Method Detail
  - getMaxSize
```
public int getMaxSize()
```
    Gets the max size of the window. This is the max number of requests that can be outstanding (unresponded to) in this window.
    
    Returns:
    The max size of the window
  - getSize
```
public int getSize()
```
    Gets the current number of requests in the window.
    
    Returns:
    The current number of pending requests
  - getFreeSize
```
public int getFreeSize()
```
    Gets the current number of request that would be accepted by this window without blocking. In order words, the number of free slots.
    
    Returns:
    The free size of this window
  - containsKey
```
public boolean containsKey(K key)
```
    Returns true if and only if a future with this key exists in this window.
    
    Parameters:
    key - The key for the future
    
    Returns:
    True if the request exists, otherwise false.
  - get
```
public WindowFuture<K,R,P> get(K key)
```
    Gets the a future by its key.
    
    Parameters:
    key - The key for the request
    
    Returns:
    The future or null if it doesn't exist.
  - addListener
```
public void addListener(WindowListener<K,R,P> listener)
```
    Adds a new WindowListener if and only if it isn't already present.
    
    Parameters:
    listener - The listener to add
  - removeListener
```
public void removeListener(WindowListener<K,R,P> listener)
```
    Removes a WindowListener if it is present.
    
    Parameters:
    listener - The listener to remove
  - destroy
```
public void destroy()
```
    Destroy this window by freeing all resources associated with it. All pending offers are cancelled, followed by all outstanding futures, then all listeners are removed, and monitoring is cancelled.
  - startMonitor
```
public boolean startMonitor()
```
    Starts the monitor if this Window has an executor. Safe to call multiple times.
    
    Returns:
    True if the monitor was started (true will be returned if it was already previously started).
  - stopMonitor
```
public void stopMonitor()
```
    Stops the monitor if its running. Safe to call multiple times.
  - createSortedSnapshot
```
public Map<K,WindowFuture<K,R,P>> createSortedSnapshot()
```
    Creates an ordered snapshot of the requests in this window. The entries will be sorted by the natural ascending order of the key. A new map is allocated when calling this method, so be careful about calling it once.
    
    Returns:
    A new map instance representing all requests sorted by the natural ascending order of its key.
  - offer
```
public WindowFuture offer(K key,
                 R request,
                 long offerTimeoutMillis)
                   throws DuplicateKeyException,
                          OfferTimeoutException,
                          InterruptedException
```
    Offers a request for acceptance, waiting for the specified amount of time in case it could not immediately accepted. The "caller state hint" of the returned future will be set to "NOT_WAITING". The expireTimestamp of the returned future will be set to -1 (infinity/never expires).
    
    Parameters:
    key - The key for the request. A protocol's sequence number is a good choice.
    request - The request to offer
    offerTimeoutMillis - The amount of time (in milliseconds) to wait for the offer to be accepted.
    
    Returns:
    A future representing pending completion of the request
    
    Throws:
    
    DuplicateKeyException - Thrown if the key already exists
    
    PendingOfferAbortedException - Thrown if the offer could not be immediately accepted and the caller/thread was waiting, but the abortPendingOffers() method was called in the meantime.
    
    OfferTimeoutException - Thrown if the offer could not be accepted within the specified amount of time.
    
    InterruptedException - Thrown if the calling thread is interrupted while waiting to acquire the internal lock.
  - offer
```
public WindowFuture offer(K key,
                 R request,
                 long offerTimeoutMillis,
                 long expireTimeoutMillis)
                   throws DuplicateKeyException,
                          OfferTimeoutException,
                          InterruptedException
```
    Offers a request for acceptance, waiting for the specified amount of time in case it could not immediately accepted. The "caller state hint" of the returned future will be set to "NOT_WAITING".
    
    Parameters:
    key - The key for the request. A protocol's sequence number is a good choice.
    request - The request to offer
    offerTimeoutMillis - The amount of time (in milliseconds) to wait for the offer to be accepted.
    expireTimeoutMillis - The amount of time (in milliseconds) that a request will be set to expire after acceptance. A value < 1 is assumed to be an infinite expiration (request never expires). Requests are not automatically expired unless monitoring was enabled during construction of this window.
    
    Returns:
    A future representing pending completion of the request
    
    Throws:
    
    DuplicateKeyException - Thrown if the key already exists
    
    PendingOfferAbortedException - Thrown if the offer could not be immediately accepted and the caller/thread was waiting, but the abortPendingOffers() method was called in the meantime.
    
    OfferTimeoutException - Thrown if the offer could not be accepted within the specified amount of time.
    
    InterruptedException - Thrown if the calling thread is interrupted while waiting to acquire the internal lock.
  - offer
```
public WindowFuture offer(K key,
                 R request,
                 long offerTimeoutMillis,
                 long expireTimeoutMillis,
                 boolean callerWaitingHint)
                   throws DuplicateKeyException,
                          OfferTimeoutException,
                          PendingOfferAbortedException,
                          InterruptedException
```
    Offers a request for acceptance, waiting for the specified amount of time in case it could not immediately accepted.
    
    Parameters:
    key - The key for the request. A protocol's sequence number is a good choice.
    request - The request to offer
    offerTimeoutMillis - The amount of time (in milliseconds) to wait for the offer to be accepted.
    expireTimeoutMillis - The amount of time (in milliseconds) that a request will be set to expire after acceptance. A value < 1 is assumed to be an infinite expiration (request never expires). Requests are not automatically expired unless monitoring was enabled during construction of this window.
    callerWaitingHint - If true the "caller state hint" of the future will be set to "WAITING" during construction. This generally does not affect any internal processing by this window, but allows callers to hint they plan on calling "await()" on the future.
    
    Returns:
    A future representing pending completion of the request
    
    Throws:
    
    DuplicateKeyException - Thrown if the key already exists
    
    PendingOfferAbortedException - Thrown if the offer could not be immediately accepted and the caller/thread was waiting, but the abortPendingOffers() method was called in the meantime.
    
    OfferTimeoutException - Thrown if the offer could not be accepted within the specified amount of time.
    
    InterruptedException - Thrown if the calling thread is interrupted while waiting to acquire the internal lock.
  - getPendingOfferCount
```
public int getPendingOfferCount()
```
    Gets the current number of callers/threads that are waiting for a pending offer to be accepted.
  - abortPendingOffers
```
public boolean abortPendingOffers()
                           throws InterruptedException
```
    Aborts all current callers/threads waiting for a pending offer to be accepted by the window.
    
    Returns:
    True if there were threads/callers that have a pending offer.
    
    Throws:
    
    InterruptedException - Thrown if the calling thread was interrupted while waiting to obtain the window lock.
  - complete
```
public WindowFuture<K,R,P> complete(K key,
                           P response)
                             throws InterruptedException
```
    Successfully completes a request by setting the response on the associated future. Any callers/threads waiting for completion will be signaled. Also, since this frees up a slot in the window, one caller/thread blocked with a pending offer will be signaled to continue.
    
    Parameters:
    key - The key for the original request
    response - The response to set on the associated future. Null responses are not accepted (use cancel()) instead.
    
    Returns:
    A future representing the entire operation. Since a response is set, the future.isSuccess() method will be true.
    
    Throws:
    
    InterruptedException - Thrown if the calling thread is interrupted and we're currently waiting to acquire the internal "windowLock".
  - fail
```
public WindowFuture<K,R,P> fail(K key,
                       Throwable t)
                         throws InterruptedException
```
    Fails (completes) a request by setting the cause of the failure on the associated future. Any callers/threads waiting for completion will be signaled. Also, since this frees up a slot in the window, one caller/thread blocked with a pending offer will be signaled to continue.
    
    Parameters:
    key - The key for the original request
    t - The throwable to set as the failure cause on the associated future. Null values are not accepted (use cancel()) instead.
    
    Returns:
    A future representing the entire operation. Since a cause is set, the future.isSuccess() method will be false.
    
    Throws:
    
    InterruptedException - Thrown if the calling thread is interrupted and we're currently waiting to acquire the internal "windowLock".
  - failAll
```
public List<WindowFuture<K,R,P>> failAll(Throwable t)
                                  throws InterruptedException
```
    Fails (completes) all requests by setting the same cause of the failure on all associated futures. Any callers/threads waiting for completion will be signaled. Also, since this frees up all slots in the window, all callers/threads blocked with pending offers will be signaled to continue.
    
    Parameters:
    t - The throwable to set as the failure cause on all associated futures. Null values are not accepted (use cancelAll()) instead.
    
    Returns:
    A list of all futures that were failed.
    
    Throws:
    
    InterruptedException - Thrown if the calling thread is interrupted and we're currently waiting to acquire the internal "windowLock".
  - cancel
```
public WindowFuture<K,R,P> cancel(K key)
                           throws InterruptedException
```
    Cancels (completes) a request. Any callers/threads waiting for completion will be signaled. Also, since this frees up a slot in the window, one caller/thread blocked with a pending offer will be signaled to continue.
    
    Parameters:
    key - The key for the original request
    
    Returns:
    A future representing the entire operation.
    
    Throws:
    
    InterruptedException - Thrown if the calling thread is interrupted and we're currently waiting to acquire the internal "windowLock".
  - cancelAll
```
public List<WindowFuture<K,R,P>> cancelAll()
```
    Cancels (completes) all requests. Any callers/threads waiting for completion will be signaled. Also, since this frees up all slots in the window, all callers/threads blocked with pending offers will be signaled to continue.
    
    Returns:
    A list of all futures that were cancelled.
    
    Throws:
    
    InterruptedException - Thrown if the calling thread is interrupted and we're currently waiting to acquire the internal "windowLock".
  - cancelAllExpired
```
public List<WindowFuture<K,R,P>> cancelAllExpired()
```
    Cancels (completes) all expired requests. A request is considered expired if it has an expireTimestamp set and the current time is >= the getExpireTimestamp() value. Any callers/threads waiting for completion will be signaled. Also, if more than one request was expired then all callers/threads blocked with pending offers will be signaled to continue.
    
    Returns:
    A list of all expired futures that were cancelled.
    
    Throws:
    
    InterruptedException - Thrown if the calling thread is interrupted and we're currently waiting to acquire the internal "windowLock".

Class Window<K,R,P>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Window

Window

Window

Method Detail

getMaxSize

getSize

getFreeSize

containsKey

get

addListener

removeListener

destroy

startMonitor

stopMonitor

createSortedSnapshot

offer

offer

offer

getPendingOfferCount

abortPendingOffers

complete

fail

failAll

cancel

cancelAll

cancelAllExpired