org.jboss.threads.AsyncFuture Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jboss-threads Show documentation
There is a newer version: 3.8.0.Final
/*
 * JBoss, Home of Professional Open Source.
 * Copyright 2010, Red Hat, Inc., and individual contributors
 * as indicated by the @author tags. See the copyright.txt file in the
 * distribution for a full listing of individual contributors.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */

package org.jboss.threads;

import java.util.concurrent.CancellationException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

/**
 * This interface represents the result of an asynchronous future task, which provides all the features
 * of {@link Future} while also adding several additional convenience methods and the ability to add asynchronous
 * callbacks.
 * 
 * @author David M. Lloyd
 */
public interface AsyncFuture extends Future, AsyncCancellable {

    /**
     * Wait if necessary for this operation to complete, returning the outcome.  The outcome will be one of
     * {@link Status#COMPLETE}, {@link Status#CANCELLED}, or {@link Status#FAILED}.
     *
     * @return the outcome
     * @throws InterruptedException if execution was interrupted while waiting
     */
    Status await() throws InterruptedException;

    /**
     * Wait if necessary for this operation to complete, returning the outcome, which may include {@link Status#WAITING} if
     * the timeout expires before the operation completes.
     *
     * @param timeout the maximum time to wait
     * @param unit the time unit of the timeout argument
     * @return the outcome
     * @throws InterruptedException if execution was interrupted while waiting
     */
    Status await(long timeout, TimeUnit unit) throws InterruptedException;

    /**
     * Waits (uninterruptibly) if necessary for the computation to complete, and then retrieves the result.
     *
     * @return the computed result
     * @throws CancellationException if the computation was cancelled
     * @throws ExecutionException if the computation threw an exception
     */
    T getUninterruptibly() throws CancellationException, ExecutionException;

    /**
     * Waits (uninterruptibly) if necessary for at most the given time for the computation to complete, and then
     * retrieves the result, if available.
     *
     * @param timeout the maximum time to wait
     * @param unit the time unit of the timeout argument
     * @return the computed result
     * @throws CancellationException if the computation was cancelled
     * @throws ExecutionException if the computation threw an exception
     * @throws TimeoutException if the wait timed out
     */
    T getUninterruptibly(long timeout, TimeUnit unit) throws CancellationException, ExecutionException, TimeoutException;

    /**
     * Wait (uninterruptibly) if necessary for this operation to complete, returning the outcome.  The outcome will be one of
     * {@link Status#COMPLETE}, {@link Status#CANCELLED}, or {@link Status#FAILED}.
     *
     * @return the outcome
     */
    Status awaitUninterruptibly();

    /**
     * Wait if necessary for this operation to complete, returning the outcome, which may include {@link Status#WAITING} if
     * the timeout expires before the operation completes.
     *
     * @param timeout the maximum time to wait
     * @param unit the time unit of the timeout argument
     * @return the outcome
     */
    Status awaitUninterruptibly(long timeout, TimeUnit unit);

    /**
     * Get (poll) the current status of the asynchronous operation.
     *
     * @return the current status
     */
    Status getStatus();

    /**
     * Add an asynchronous listener to be called when this operation completes.
     *
     * @param listener the listener to add
     * @param attachment the attachment to pass in
     * @param  the attachment type
     */
     void addListener(Listener listener, A attachment);

    /**
     * Synchronously cancel a task, blocking uninterruptibly until it is known whether such cancellation was
     * successful.  Note that the {@link Future#cancel(boolean)} is somewhat unclear about blocking semantics.
     * It is recommended to use {@link #asyncCancel(boolean)} instead.
     *
     * @param interruptionDesired if interruption is desired (if available)
     * @return {@code true} if cancel succeeded, {@code false} otherwise
     */
    boolean cancel(boolean interruptionDesired);

    /** {@inheritDoc} */
    void asyncCancel(boolean interruptionDesired);

    /**
     * The possible statuses of an {@link AsyncFuture}.
     */
    enum Status {

        /**
         * The operation is still in progress.
         */
        WAITING,
        /**
         * The operation has completed successfully.
         */
        COMPLETE,
        /**
         * The operation was cancelled before it completed.
         */
        CANCELLED,
        /**
         * The operation has failed with some exception.
         */
        FAILED,
        ;
    }

    /**
     * A listener for an asynchronous future computation result.  Each listener method is passed the
     * {@link AsyncFuture} which it was added to, as well as the {@code attachment} which was passed in to
     * {@link AsyncFuture#addListener(Listener, Object)}.
     *
     * @param  the future type
     * @param  the attachment type
     */
    interface Listener extends java.util.EventListener {

        /**
         * Handle a successful computation result.
         *
         * @param future the future
         * @param attachment the attachment
         */
        void handleComplete(AsyncFuture future, A attachment);

        /**
         * Handle a failure result.
         *
         * @param future the future
         * @param cause the reason for the failure
         * @param attachment the attachment
         */
        void handleFailed(AsyncFuture future, Throwable cause, A attachment);

        /**
         * Handle a cancellation result.
         *
         * @param future the future
         * @param attachment the attachment
         */
        void handleCancelled(AsyncFuture future, A attachment);
    }

    /**
     * An abstract base class for an implementation of the {@code Listener} interface.  The implementation
     * methods do nothing unless overridden.
     *
     * @param  the future type
     * @param  the attachment type
     */
    abstract class AbstractListener implements Listener {

        /** {@inheritDoc} */
        public void handleComplete(final AsyncFuture future, final A attachment) {
        }

        /** {@inheritDoc} */
        public void handleFailed(final AsyncFuture future, final Throwable cause, final A attachment) {
        }

        /** {@inheritDoc} */
        public void handleCancelled(final AsyncFuture future, final A attachment) {
        }
    }
}