-
- 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 useIoFuture
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 futureInputStream
, you might be tempted to declare it like this:IoFuture<InputStream> getFutureInputStream();
Now if you later decide that what you really need is aDataInputStream
(which extendsInputStream
), you're in trouble because you have writtenIoFuture<InputStream>
everywhere, which cannot be assigned to or from anIoFuture<DataInputStream>
. On the other hand, if you declare it like this:IoFuture<? extends InputStream> getFutureInputStream();
Now you can change it at any time toIoFuture<? extends DataInputStream>
without breaking the contract, since it will be assignable to variables of typeIoFuture<? extends InputStream>
.
-
-
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 anIoFuture
.static class
IoFuture.Status
The current status of an asynchronous operation.
-
Method Summary
All Methods Instance Methods Abstract Methods 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, java.util.concurrent.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, java.util.concurrent.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.java.io.IOException
getException()
Get the failure reason.T
getInterruptibly()
Get the result of the operation.IoFuture.Status
getStatus()
Get the current status.
-
-
-
Method Detail
-
cancel
IoFuture<T> 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
IoFuture.Status await(long time, java.util.concurrent.TimeUnit timeUnit)
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
IoFuture.Status awaitInterruptibly() throws java.lang.InterruptedException
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:
java.lang.InterruptedException
- if the operation is interrupted
-
awaitInterruptibly
IoFuture.Status awaitInterruptibly(long time, java.util.concurrent.TimeUnit timeUnit) throws java.lang.InterruptedException
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:
java.lang.InterruptedException
- if the operation is interrupted
-
get
T get() throws java.io.IOException, java.util.concurrent.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:
java.io.IOException
- if the operation failedjava.util.concurrent.CancellationException
- if the operation was cancelled
-
getInterruptibly
T getInterruptibly() throws java.io.IOException, java.lang.InterruptedException, java.util.concurrent.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:
java.io.IOException
- if the operation failedjava.lang.InterruptedException
- if the operation is interruptedjava.util.concurrent.CancellationException
- if the operation was cancelled
-
getException
java.io.IOException getException() throws java.lang.IllegalStateException
Get the failure reason.- Returns:
- the failure reason
- Throws:
java.lang.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 calledattachment
- the attachment to pass in to the notifier- Returns:
- this instance
-
-