Module 
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;.
    • Method Detail

      • 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​(long time,
                              java.util.concurrent.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 java.lang.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:
        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 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:
        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 failed
        java.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 failed
        java.lang.InterruptedException - if the operation is interrupted
        java.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 called
        attachment - the attachment to pass in to the notifier
        Returns:
        this instance