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
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<InputStream>
everywhere, which cannot be assigned to or from
an IoFuture<DataInputStream>
.
On the other hand, if you declare it like this:
IoFuture<? extends InputStream> getFutureInputStream();Now you can change it at any time to
IoFuture<? extends DataInputStream>
without breaking the contract, since
it will be assignable to variables of type IoFuture<? extends InputStream>
.-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic class
A base notifier class that calls the designated handler method on notification.static interface
A notifier that handles changes in the status of anIoFuture
.static enum
The current status of an asynchronous operation. -
Method Summary
Modifier and TypeMethodDescriptionaddNotifier
(IoFuture.Notifier<? super T, A> notifier, A attachment) Add a notifier to be called when this operation is complete.await()
Wait for the operation to complete.Wait for the operation to complete, with a timeout.Wait for the operation to complete.awaitInterruptibly
(long time, TimeUnit timeUnit) Wait for the operation to complete, with a timeout.cancel()
Cancel an operation.get()
Get the result of the operation.Get the failure reason.Get the result of the operation.Get the current status.
-
Method Details
-
cancel
Cancel an operation. The actual cancel may be synchronous or asynchronous.- Specified by:
cancel
in interfaceCancellable
- 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 fromIoFuture.Status.WAITING
.- Returns:
- the new status
-
await
Wait for the operation to complete, with a timeout. This method will block until the status changes fromIoFuture.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 waittimeUnit
- the time unit- Returns:
- the new status, or
IoFuture.Status.WAITING
if the timeout expired
-
awaitInterruptibly
Wait for the operation to complete. This method will block until the status changes fromIoFuture.Status.WAITING
, or the current thread is interrupted.- Returns:
- the new status
- Throws:
InterruptedException
- if the operation is interrupted
-
awaitInterruptibly
Wait for the operation to complete, with a timeout. This method will block until the status changes fromIoFuture.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 waittimeUnit
- the time unit- Returns:
- the new status, or
IoFuture.Status.WAITING
if the timeout expired - Throws:
InterruptedException
- if the operation is interrupted
-
get
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 failedCancellationException
- if the operation was cancelled
-
getInterruptibly
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 failedInterruptedException
- if the operation is interruptedCancellationException
- if the operation was cancelled
-
getException
Get the failure reason.- Returns:
- the failure reason
- Throws:
IllegalStateException
- if the operation did not fail
-
addNotifier
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 calledattachment
- the attachment to pass in to the notifier- Returns:
- this instance
-