Package org.xnio

# Interface IoFuture<T>

Type Parameters:
  `T` - the type of result that this operation produces

All Superinterfaces:
  `Cancellable`

All Known Implementing Classes:
  `AbstractConvertingIoFuture`, `AbstractIoFuture`, `FailedIoFuture`, `FinishedIoFuture`

public interface IoFuture<T> extends Cancellable
The future result of an asynchronous request. Use instances of this interface to retrieve the final status of an asynchronous operation.

It is recommended, due to the vagaries of the way generics work, that when you use `IoFuture` instances, you use a wildcard to express the return type. This enables you to take advantage of covariance to retrofit more specific types later on without breaking anything.

For example, if you have a method which returns a future `InputStream`, you might be tempted to declare it like this: `

     IoFuture<InputStream> getFutureInputStream();

` Now if you later decide that what you really need is a `DataInputStream` (which extends `InputStream`), you're in trouble because you have written `IoFuture&lt;InputStream&gt;` everywhere, which cannot be assigned to or from an `IoFuture&lt;DataInputStream&gt;`.

On the other hand, if you declare it like this: `

     IoFuture<? extends InputStream> getFutureInputStream();

` Now you can change it at any time to `IoFuture&lt;? extends DataInputStream&gt;` without breaking the contract, since it will be assignable to variables of type `IoFuture&lt;? extends InputStream&gt;`.

## Nested Class Summary

Nested Classes
Modifier and Type
Interface
Description
`static class`
`IoFuture.HandlingNotifier<T,A>`
A base notifier class that calls the designated handler method on notification.
`static interface`
`IoFuture.Notifier<T,A>`
A notifier that handles changes in the status of an `IoFuture`.
`static enum`
`IoFuture.Status`
The current status of an asynchronous operation.

## Method Summary

Modifier and Type
Method
Description
`<A> IoFuture<T>`
`addNotifier(IoFuture.Notifier<? super T,A> notifier, A attachment)`
Add a notifier to be called when this operation is complete.
`IoFuture.Status`
`await()`
Wait for the operation to complete.
`IoFuture.Status`
`await(long time, TimeUnit timeUnit)`
Wait for the operation to complete, with a timeout.
`IoFuture.Status`
`awaitInterruptibly()`
Wait for the operation to complete.
`IoFuture.Status`
`awaitInterruptibly(long time, TimeUnit timeUnit)`
Wait for the operation to complete, with a timeout.
`IoFuture<T>`
`cancel()`
Cancel an operation.
`T`
`get()`
Get the result of the operation.
`IOException`
`getException()`
Get the failure reason.
`T`
`getInterruptibly()`
Get the result of the operation.
`IoFuture.Status`
`getStatus()`
Get the current status.

## Method Details

### cancel

IoFuture<T> cancel()
Cancel an operation. The actual cancel may be synchronous or asynchronous.

Specified by:
  `cancel` in interface `Cancellable`
Returns:
  this instance

### getStatus

IoFuture.Status getStatus()
Get the current status.

Returns:
  the current status

### await

IoFuture.Status await()
Wait for the operation to complete. This method will block until the status changes from `IoFuture.Status.WAITING`.

Returns:
  the new status

### await

IoFuture.Status await(long time, TimeUnit timeUnit)
Wait for the operation to complete, with a timeout. This method will block until the status changes from `IoFuture.Status.WAITING`, or the given time elapses. If the time elapses before the operation is complete, `IoFuture.Status.WAITING` is returned.

Parameters:
  `time` - the amount of time to wait
  `timeUnit` - the time unit
Returns:
  the new status, or `IoFuture.Status.WAITING` if the timeout expired

### awaitInterruptibly

IoFuture.Status awaitInterruptibly() throws InterruptedException
Wait for the operation to complete. This method will block until the status changes from `IoFuture.Status.WAITING`, or the current thread is interrupted.

Returns:
  the new status
Throws:
  `InterruptedException` - if the operation is interrupted

### awaitInterruptibly

IoFuture.Status awaitInterruptibly(long time, TimeUnit timeUnit) throws InterruptedException
Wait for the operation to complete, with a timeout. This method will block until the status changes from `IoFuture.Status.WAITING`, the given time elapses, or the current thread is interrupted. If the time elapses before the operation is complete, `IoFuture.Status.WAITING` is returned.

Parameters:
  `time` - the amount of time to wait
  `timeUnit` - the time unit
Returns:
  the new status, or `IoFuture.Status.WAITING` if the timeout expired
Throws:
  `InterruptedException` - if the operation is interrupted

### get

T get() throws IOException, CancellationException
Get the result of the operation. If the operation is not complete, blocks until the operation completes. If the operation fails, or has already failed at the time this method is called, the failure reason is thrown.

Returns:
  the result of the operation
Throws:
  `IOException` - if the operation failed
  `CancellationException` - if the operation was cancelled

### getInterruptibly

T getInterruptibly() throws IOException, InterruptedException, CancellationException
Get the result of the operation. If the operation is not complete, blocks until the operation completes. If the operation fails, or has already failed at the time this method is called, the failure reason is thrown. If the current thread is interrupted while waiting, an exception is thrown.

Returns:
  the result of the operation
Throws:
  `IOException` - if the operation failed
  `InterruptedException` - if the operation is interrupted
  `CancellationException` - if the operation was cancelled

### getException

IOException getException() throws IllegalStateException
Get the failure reason.

Returns:
  the failure reason
Throws:
  `IllegalStateException` - if the operation did not fail

### addNotifier

<A> IoFuture<T> addNotifier(IoFuture.Notifier<? super T,A> notifier, A attachment)
Add a notifier to be called when this operation is complete. If the operation is already complete, the notifier is called immediately, possibly in the caller's thread. The given attachment is provided to the notifier.

Type Parameters:
  `A` - the attachment type
Parameters:
  `notifier` - the notifier to be called
  `attachment` - the attachment to pass in to the notifier
Returns:
  this instance