# Promise (sshj 0.7.0 API)
Date: 2012-01-08

## net.schmizz.concurrent
Class Promise<V,T extends Throwable>

    java.lang.Object
      net.schmizz.concurrent.Promise<V,T>

    public class Promise<V,T extends Throwable>

extends Object

Represents promised data of the parameterized type `V` and allows waiting on it. An exception may also be delivered to a waiter, and will be of the parameterized type `T`.

For atomic operations on a promise, e.g. checking if a value is delivered and if it is not then setting it, the associated lock for the promise should be acquired while doing so.

Constructor Summary
`Promise(String name, ExceptionChainer<T> chainer)` Creates this promise with given `name` and exception `chainer`.
`Promise(String name, ExceptionChainer<T> chainer, ReentrantLock lock)` Creates this promise with given `name`, exception `chainer`, and associated `lock`.

Method Summary
`void` `clear()` Clears this promise by setting its value and queued exception to `null`.
`void` `deliver(V val)` Set this promise's value to `val`.
`void` `deliverError(Throwable e)` Queues error that will be thrown in any waiting thread or any thread that attempts to wait on this promise hereafter.
`boolean` `hasWaiters()`
`boolean` `inError()`
`boolean` `isDelivered()`
`void` `lock()` Acquire the lock associated with this promise.
`V` `retrieve()` Wait indefinitely for this promise's value to be deliver.
`V` `retrieve(long timeout, TimeUnit unit)` Wait for `timeout` duration for this promise's value to be deliver.
`String` `toString()`
`V` `tryRetrieve(long timeout, TimeUnit unit)` Wait for `timeout` duration for this promise's value to be deliver.
`void` `unlock()` Release the lock associated with this promise.

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

Constructor Detail

### Promise

    public Promise(String name,
                   ExceptionChainer<T> chainer)

  Creates this promise with given `name` and exception `chainer`. Allocates a new `lock` object for this promise.

  Parameters:
    `name` - name of this promise
    `chainer` - `ExceptionChainer` that will be used for chaining exceptions

### Promise

    public Promise(String name,
                   ExceptionChainer<T> chainer,
                   ReentrantLock lock)

  Creates this promise with given `name`, exception `chainer`, and associated `lock`.

  Parameters:
    `name` - name of this promise
    `chainer` - `ExceptionChainer` that will be used for chaining exceptions
    `lock` - lock to use

Method Detail

### deliver

    public void deliver(V val)

  Set this promise's value to `val`. Any waiters will be delivered this value.

  Parameters:
    `val` - the value

### deliverError

    public void deliverError(Throwable e)

  Queues error that will be thrown in any waiting thread or any thread that attempts to wait on this promise hereafter.

  Parameters:
    `e` - the error

### clear

    public void clear()

  Clears this promise by setting its value and queued exception to `null`.

### retrieve

    public V retrieve()
               throws T extends Throwable

  Wait indefinitely for this promise's value to be deliver.

  Returns:
    the value
  Throws:
    `T` - in case another thread informs the promise of an error meanwhile
    `T extends Throwable`

### retrieve

    public V retrieve(long timeout,
                      TimeUnit unit)
               throws T extends Throwable

  Wait for `timeout` duration for this promise's value to be deliver.

  Parameters:
    `timeout` - the timeout
    `unit` - time unit for the timeout
  Returns:
    the value
  Throws:
    `T` - in case another thread informs the promise of an error meanwhile, or the timeout expires
    `T extends Throwable`

### tryRetrieve

    public V tryRetrieve(long timeout,
                         TimeUnit unit)
                  throws T extends Throwable

  Wait for `timeout` duration for this promise's value to be deliver.

  If the value is not deliver by the time the timeout expires, returns `null`.

  Parameters:
    `timeout` - the timeout
    `unit` - time unit for the timeout
  Returns:
    the value or `null`
  Throws:
    `T` - in case another thread informs the promise of an error meanwhile
    `T extends Throwable`

### isDelivered

    public boolean isDelivered()

  Returns:
    whether this promise has a value delivered, and no error waiting to pop.

### inError

    public boolean inError()

  Returns:
    whether this promise has been delivered an error.

### hasWaiters

    public boolean hasWaiters()

  Returns:
    whether this promise has threads waiting on it.

### lock

    public void lock()

  Acquire the lock associated with this promise.

### unlock

    public void unlock()

  Release the lock associated with this promise.

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

Copyright © 2009-2012. All Rights Reserved.