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 and Inner Type Summary

Modifier and Type	Class and Description
public abstract static class	IoFuture.HandlingNotifier< the type of result that the associated future operation produces T, the attachment type A> A base notifier class that calls the designated handler method on notification.
public static interface	IoFuture.Notifier< the type of result that the associated future operation produces T, the attachment type A> A notifier that handles changes in the status of an `IoFuture`.
public static enum	IoFuture.Status The current status of an asynchronous operation.

Method Summary

Modifier and Type	Method and Description
public < the attachment type A> IoFuture<T>	Returns: this instance addNotifier(IoFuture.Notifier<? super T, A> the notifier to be called notifier, A the attachment to pass in to the notifier attachment) Add a notifier to be called when this operation is complete.
public IoFuture.Status	Returns: the new status await() Wait for the operation to complete.
public IoFuture.Status	Returns: the new status, or `Status#WAITING` if the timeout expired await(long the amount of time to wait time, TimeUnit the time unit timeUnit) Wait for the operation to complete, with a timeout.
public IoFuture.Status	Returns: the new status awaitInterruptibly() Wait for the operation to complete.
public IoFuture.Status	Returns: the new status, or `Status#WAITING` if the timeout expired awaitInterruptibly(long the amount of time to wait time, TimeUnit the time unit timeUnit) Wait for the operation to complete, with a timeout.
public IoFuture<T>	cancel() Redeclares org.xnio.Cancellable.cancel. Cancel an operation.
public T	Returns: the result of the operation get() Get the result of the operation.
public IOException	Returns: the failure reason getException() Get the failure reason.
public T	Returns: the result of the operation getInterruptibly() Get the result of the operation.
public IoFuture.Status	Returns: the current status getStatus() Get the current status.

Method Detail

addNotifier	back to summary
public <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. Parameters <A> the attachment type notifier:IoFuture.Notifier<? super T, A> the notifier to be called attachment:A the attachment to pass in to the notifier Returns:IoFuture<T> this instance

addNotifier

back to summary

public <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.

Parameters

<A>: the attachment type
notifier:IoFuture.Notifier<? super T, A>: the notifier to be called
attachment:A: the attachment to pass in to the notifier

Returns:IoFuture<T>

this instance

await back to summary

await	back to summary
public IoFuture.Status await() Wait for the operation to complete. This method will block until the status changes from `Status#WAITING`. Returns:IoFuture.Status the new status

public IoFuture.Status await()

Wait for the operation to complete. This method will block until the status changes from Status#WAITING.

Returns:IoFuture.Status: the new status

await back to summary

await	back to summary
public 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 `Status#WAITING`, or the given time elapses. If the time elapses before the operation is complete, `Status#WAITING` is returned. Parameters time:long the amount of time to wait timeUnit:TimeUnit the time unit Returns:IoFuture.Status the new status, or `Status#WAITING` if the timeout expired

public 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 Status#WAITING, or the given time elapses. If the time elapses before the operation is complete, Status#WAITING is returned.

Parameters

time:long: the amount of time to wait
timeUnit:TimeUnit: the time unit

Returns:IoFuture.Status

the new status, or Status#WAITING if the timeout expired

awaitInterruptibly back to summary

awaitInterruptibly	back to summary
public IoFuture.Status awaitInterruptibly() throws InterruptedException Wait for the operation to complete. This method will block until the status changes from `Status#WAITING`, or the current thread is interrupted. Returns:IoFuture.Status the new status Exceptions InterruptedException: if the operation is interrupted

public IoFuture.Status awaitInterruptibly() throws InterruptedException

Wait for the operation to complete. This method will block until the status changes from Status#WAITING, or the current thread is interrupted.

Returns:IoFuture.Status

the new status

Exceptions

InterruptedException:: if the operation is interrupted

awaitInterruptibly back to summary

awaitInterruptibly	back to summary
public 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 `Status#WAITING`, the given time elapses, or the current thread is interrupted. If the time elapses before the operation is complete, `Status#WAITING` is returned. Parameters time:long the amount of time to wait timeUnit:TimeUnit the time unit Returns:IoFuture.Status the new status, or `Status#WAITING` if the timeout expired Exceptions InterruptedException: if the operation is interrupted

public 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 Status#WAITING, the given time elapses, or the current thread is interrupted. If the time elapses before the operation is complete, Status#WAITING is returned.

Parameters

time:long: the amount of time to wait
timeUnit:TimeUnit: the time unit

Returns:IoFuture.Status

the new status, or Status#WAITING if the timeout expired

Exceptions

InterruptedException:: if the operation is interrupted

cancel	back to summary
public IoFuture<T> cancel() Redeclares org.xnio.Cancellable.cancel. Doc from org.xnio.Cancellable.cancel. Cancel an operation. The actual cancel may be synchronous or asynchronous. Returns:IoFuture<T> this instance

cancel

back to summary

public IoFuture<T> cancel()

Redeclares org.xnio.Cancellable.cancel.

Doc from org.xnio.Cancellable.cancel.

Cancel an operation. The actual cancel may be synchronous or asynchronous.

Returns:IoFuture<T>: this instance

get	back to summary
public 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:T the result of the operation Exceptions IOException: if the operation failed CancellationException: if the operation was cancelled

get

back to summary

public 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:T

the result of the operation

Exceptions

IOException:: if the operation failed
CancellationException:: if the operation was cancelled

getException	back to summary
public IOException getException() throws IllegalStateException Get the failure reason. Returns:IOException the failure reason Exceptions IllegalStateException: if the operation did not fail

getException

back to summary

public IOException getException() throws IllegalStateException

Get the failure reason.

Returns:IOException

the failure reason

Exceptions

IllegalStateException:: if the operation did not fail

getInterruptibly	back to summary
public 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:T the result of the operation Exceptions IOException: if the operation failed InterruptedException: if the operation is interrupted CancellationException: if the operation was cancelled

getInterruptibly

back to summary

public T getInterruptibly() throws IOException, InterruptedException, CancellationException

Returns:T

the result of the operation

Exceptions

IOException:: if the operation failed
InterruptedException:: if the operation is interrupted
CancellationException:: if the operation was cancelled

getStatus	back to summary
public IoFuture.Status getStatus() Get the current status. Returns:IoFuture.Status the current status

getStatus

back to summary

public IoFuture.Status getStatus()

Get the current status.

Returns:IoFuture.Status: the current status

org.xnio back to summary

public abstract Class IoFuture.HandlingNotifier<T, A>

Class Inheritance

extends Object
implements IoFuture.Notifier<T, A>

java.lang.Object
org.xnio.IoFuture.HandlingNotifier

All Implemented Interfaces

org.xnio.IoFuture.Notifier, java.util.EventListener

Known Direct Subclasses

org.xnio.IoUtils.ManagerNotifier, org.xnio.IoUtils.RetryingNotifier, org.xnio.IoUtils.ResultNotifier, org.xnio.http.HttpUpgrade.HttpUpgradeState.FailureNotifier

Type Parameters

<T>: the type of result that the associated future operation produces
<A>: the attachment type

A base notifier class that calls the designated handler method on notification. Use this class to reduce boilerplate for standard org.xnio.IoFuture.Notifier implementations.

Since: 1.1

Constructor Summary

Access	Constructor and Description
public	HandlingNotifier()

Method Summary

Modifier and Type	Method and Description
public void	handleCancelled(final A the attachment attachment) Handle cancellation.
public void	handleDone(final T the result data, final A the attachment attachment) Handle completion.
public void	handleFailed(final IOException the failure reason exception, final A the attachment attachment) Handle failure.
public void	notify(final IoFuture<? extends T> the future corresponding to this operation future, A the attachment attachment) Implements org.xnio.IoFuture.Notifier.notify. Receive notification of the completion of an outstanding operation.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

HandlingNotifier	back to summary
public HandlingNotifier()

Method Detail

handleCancelled	back to summary
public void handleCancelled(final A attachment) Handle cancellation. Parameters attachment:A the attachment

handleCancelled

back to summary

public void handleCancelled(final A attachment)

Handle cancellation.

Parameters

attachment:A: the attachment

handleDone	back to summary
public void handleDone(final T data, final A attachment) Handle completion. Parameters data:T the result attachment:A the attachment

handleDone

back to summary

public void handleDone(final T data, final A attachment)

Handle completion.

Parameters

data:T: the result
attachment:A: the attachment

handleFailed	back to summary
public void handleFailed(final IOException exception, final A attachment) Handle failure. Parameters exception:IOException the failure reason attachment:A the attachment

handleFailed

back to summary

public void handleFailed(final IOException exception, final A attachment)

Handle failure.

Parameters

exception:IOException: the failure reason
attachment:A: the attachment

notify	back to summary
public void notify(final IoFuture<? extends T> future, A attachment) Implements org.xnio.IoFuture.Notifier.notify. Doc from org.xnio.IoFuture.Notifier.notify. Receive notification of the completion of an outstanding operation. Parameters future:IoFuture<? extends T> the future corresponding to this operation attachment:A the attachment

notify

back to summary

public void notify(final IoFuture<? extends T> future, A attachment)

Implements org.xnio.IoFuture.Notifier.notify.

Doc from org.xnio.IoFuture.Notifier.notify.

Receive notification of the completion of an outstanding operation.

Parameters

future:IoFuture<? extends T>: the future corresponding to this operation
attachment:A: the attachment

org.xnio back to summary

public Interface IoFuture.Notifier<T, A>

Known Direct Implementers

extends EventListenerorg.xnio.IoFuture.HandlingNotifier

Type Parameters

<T>: the type of result that the associated future operation produces
<A>: the attachment type

A notifier that handles changes in the status of an IoFuture.

Method Summary

Modifier and Type	Method and Description
public void	notify(IoFuture<? extends T> the future corresponding to this operation ioFuture, final A the attachment attachment) Receive notification of the completion of an outstanding operation.

Method Detail

notify	back to summary
public void notify(IoFuture<? extends T> ioFuture, final A attachment) Receive notification of the completion of an outstanding operation. Parameters ioFuture:IoFuture<? extends T> the future corresponding to this operation attachment:A the attachment

notify

back to summary

public void notify(IoFuture<? extends T> ioFuture, final A attachment)

Receive notification of the completion of an outstanding operation.

Parameters

ioFuture:IoFuture<? extends T>: the future corresponding to this operation
attachment:A: the attachment

org.xnio back to summary

public final Enum IoFuture.Status

Class Inheritance

extends Enum<IoFuture.Status>

java.lang.Object
java.lang.Enum
org.xnio.IoFuture.Status

The current status of an asynchronous operation.

Field Summary

Modifier and Type	Field and Description
public static final IoFuture.Status	CANCELLED The operation was cancelled.
public static final IoFuture.Status	DONE The operation has completed successfully.
public static final IoFuture.Status	FAILED The operation did not succeed.
public static final IoFuture.Status	WAITING The operation is still in progress.

Constructor Summary

Access	Constructor and Description
private	Status()

Method Summary

Modifier and Type	Method and Description
public static IoFuture.Status	valueOf(String name)
public static IoFuture.Status[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

CANCELLED	back to summary
public static final IoFuture.Status CANCELLED The operation was cancelled.

DONE	back to summary
public static final IoFuture.Status DONE The operation has completed successfully.

FAILED	back to summary
public static final IoFuture.Status FAILED The operation did not succeed.

WAITING	back to summary
public static final IoFuture.Status WAITING The operation is still in progress.

Constructor Detail

Status	back to summary
private Status()

Method Detail

valueOf	back to summary
public static IoFuture.Status valueOf(String name)

values	back to summary
public static IoFuture.Status[] values()

public Interface IoFuture<T>

Nested and Inner Type Summary

Method Summary

Method Detail

public abstract Class IoFuture.HandlingNotifier<T, A>

Constructor Summary

Method Summary

Constructor Detail

Method Detail

public Interface IoFuture.Notifier<T, A>

Method Summary

Method Detail

public final Enum IoFuture.Status

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail