/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.core.task;

import java.util.concurrent.Callable;
import java.util.concurrent.Future;

Extended interface for asynchronous TaskExecutor implementations, offering an overloaded execute(Runnable, long) variant with a start timeout parameter as well support for Callable. 
Note: The Executors class includes a set of methods that can convert some other common closure-like objects, for example, PrivilegedAction to Callable before executing them. 
Implementing this interface also indicates that the TaskExecutor.execute(Runnable) method will not execute its Runnable in the caller's thread but rather asynchronously in some other thread. 
Author:
Juergen Hoeller
See Also:
SimpleAsyncTaskExecutor
SchedulingTaskExecutor
Callable
Executors
Since:
2.0.3/**
 * Extended interface for asynchronous {@link TaskExecutor} implementations,
 * offering an overloaded {@link #execute(Runnable, long)} variant with a start
 * timeout parameter as well support for {@link java.util.concurrent.Callable}.
 *
 * <p>Note: The {@link java.util.concurrent.Executors} class includes a set of
 * methods that can convert some other common closure-like objects, for example,
 * {@link java.security.PrivilegedAction} to {@link Callable} before executing them.
 *
 * <p>Implementing this interface also indicates that the {@link #execute(Runnable)}
 * method will not execute its Runnable in the caller's thread but rather
 * asynchronously in some other thread.
 *
 * @author Juergen Hoeller
 * @since 2.0.3
 * @see SimpleAsyncTaskExecutor
 * @see org.springframework.scheduling.SchedulingTaskExecutor
 * @see java.util.concurrent.Callable
 * @see java.util.concurrent.Executors
 */
public interface AsyncTaskExecutor extends TaskExecutor {

	
Constant that indicates immediate execution. /** Constant that indicates immediate execution. */
	long TIMEOUT_IMMEDIATE = 0;

	
Constant that indicates no time limit. /** Constant that indicates no time limit. */
	long TIMEOUT_INDEFINITE = Long.MAX_VALUE;


	
Execute the given task. 
Params:
task – the Runnable to execute (never null)
startTimeout – the time duration (milliseconds) within which the task is supposed to start. This is intended as a hint to the executor, allowing for preferred handling of immediate tasks. Typical values are TIMEOUT_IMMEDIATE or TIMEOUT_INDEFINITE (the default as used by TaskExecutor.execute(Runnable)).
Throws:
TaskTimeoutException – in case of the task being rejected because
of the timeout (i.e. it cannot be started in time)
TaskRejectedException – if the given task was not accepted/**
	 * Execute the given {@code task}.
	 * @param task the {@code Runnable} to execute (never {@code null})
	 * @param startTimeout the time duration (milliseconds) within which the task is
	 * supposed to start. This is intended as a hint to the executor, allowing for
	 * preferred handling of immediate tasks. Typical values are {@link #TIMEOUT_IMMEDIATE}
	 * or {@link #TIMEOUT_INDEFINITE} (the default as used by {@link #execute(Runnable)}).
	 * @throws TaskTimeoutException in case of the task being rejected because
	 * of the timeout (i.e. it cannot be started in time)
	 * @throws TaskRejectedException if the given task was not accepted
	 */
	void execute(Runnable task, long startTimeout);

	
Submit a Runnable task for execution, receiving a Future representing that task. The Future will return a null result upon completion. 
Params:
task – the Runnable to execute (never null)
Throws:
TaskRejectedException – if the given task was not accepted
Returns:
a Future representing pending completion of the task
Since:
3.0/**
	 * Submit a Runnable task for execution, receiving a Future representing that task.
	 * The Future will return a {@code null} result upon completion.
	 * @param task the {@code Runnable} to execute (never {@code null})
	 * @return a Future representing pending completion of the task
	 * @throws TaskRejectedException if the given task was not accepted
	 * @since 3.0
	 */
	Future<?> submit(Runnable task);

	
Submit a Callable task for execution, receiving a Future representing that task.
The Future will return the Callable's result upon completion.
Params:
task – the Callable to execute (never null)
Throws:
TaskRejectedException – if the given task was not accepted
Returns:
a Future representing pending completion of the task
Since:
3.0/**
	 * Submit a Callable task for execution, receiving a Future representing that task.
	 * The Future will return the Callable's result upon completion.
	 * @param task the {@code Callable} to execute (never {@code null})
	 * @return a Future representing pending completion of the task
	 * @throws TaskRejectedException if the given task was not accepted
	 * @since 3.0
	 */
	<T> Future<T> submit(Callable<T> task);

}