001    /*
002     * Copyright (C) 2010 The Guava Authors
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     * http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    
017    package com.google.common.util.concurrent;
018    
019    import java.util.Collection;
020    import java.util.List;
021    import java.util.concurrent.Callable;
022    import java.util.concurrent.ExecutorService;
023    import java.util.concurrent.Future;
024    import java.util.concurrent.RejectedExecutionException;
025    import java.util.concurrent.TimeUnit;
026    
027    /**
028     * An {@link ExecutorService} that returns {@link ListenableFuture} instances. To create an instance
029     * from an existing {@link ExecutorService}, call
030     * {@link MoreExecutors#listeningDecorator(ExecutorService)}.
031     *
032     * @author Chris Povirk
033     * @since 10.0
034     */
035    public interface ListeningExecutorService extends ExecutorService {
036      /**
037       * @return a {@code ListenableFuture} representing pending completion of the task
038       * @throws RejectedExecutionException {@inheritDoc}
039       */
040      @Override
041      <T> ListenableFuture<T> submit(Callable<T> task);
042    
043      /**
044       * @return a {@code ListenableFuture} representing pending completion of the task
045       * @throws RejectedExecutionException {@inheritDoc}
046       */
047      @Override
048      ListenableFuture<?> submit(Runnable task);
049    
050      /**
051       * @return a {@code ListenableFuture} representing pending completion of the task
052       * @throws RejectedExecutionException {@inheritDoc}
053       */
054      @Override
055      <T> ListenableFuture<T> submit(Runnable task, T result);
056    
057      /**
058       * {@inheritDoc}
059       *
060       * <p>All elements in the returned list must be {@link ListenableFuture} instances.
061       *
062       * @return A list of {@code ListenableFuture} instances representing the tasks, in the same
063       *         sequential order as produced by the iterator for the given task list, each of which has
064       *         completed.
065       * @throws RejectedExecutionException {@inheritDoc}
066       * @throws NullPointerException if any task is null
067       */
068      @Override
069      <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
070          throws InterruptedException;
071    
072      /**
073       * {@inheritDoc}
074       *
075       * <p>All elements in the returned list must be {@link ListenableFuture} instances.
076       *
077       * @return a list of {@code ListenableFuture} instances representing the tasks, in the same
078       *         sequential order as produced by the iterator for the given task list. If the operation
079       *         did not time out, each task will have completed. If it did time out, some of these
080       *         tasks will not have completed.
081       * @throws RejectedExecutionException {@inheritDoc}
082       * @throws NullPointerException if any task is null
083       */
084      @Override
085      <T> List<Future<T>> invokeAll(
086          Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)
087          throws InterruptedException;
088    }