001package io.ebean;
002
003import java.util.concurrent.Callable;
004import java.util.concurrent.Future;
005import java.util.concurrent.ScheduledExecutorService;
006import java.util.concurrent.ScheduledFuture;
007import java.util.concurrent.TimeUnit;
008
009/**
010 * Background executor service for executing of tasks asynchronously.
011 * <p>
012 * This service can be used to execute tasks in the background.
013 * <p>
014 * This service is managed by Ebean and will perform a clean shutdown
015 * waiting for background tasks to complete with a default 30 second
016 * timeout. Shutdown occurs prior to DataSource shutdown.
017 * <p>
018 * This also propagates MDC context from the current thread to the
019 * background task if defined.
020 */
021public interface BackgroundExecutor {
022
023  /**
024   * Execute a callable task in the background returning the Future.
025   */
026  <T> Future<T> submit(Callable<T> task);
027
028  /**
029   * Execute a runnable task in the background returning the Future.
030   */
031  Future<?> submit(Runnable task);
032
033  /**
034   * Execute a task in the background. Effectively the same as
035   * {@link BackgroundExecutor#submit(Runnable)} but returns void.
036   */
037  void execute(Runnable task);
038
039  /**
040   * Deprecated - migrate to scheduleWithFixedDelay().
041   * Execute a task periodically with a fixed delay between each execution.
042   * <p>
043   * For example, execute a runnable every minute.
044   * <p>
045   * The delay is the time between executions no matter how long the task took.
046   * That is, this method has the same behaviour characteristics as
047   * {@link ScheduledExecutorService#scheduleWithFixedDelay(Runnable, long, long, TimeUnit)}
048   */
049  @Deprecated
050  void executePeriodically(Runnable task, long delay, TimeUnit unit);
051
052  /**
053   * Deprecated - migrate to scheduleWithFixedDelay().
054   * Execute a task periodically additionally with an initial delay different from delay.
055   */
056  @Deprecated
057  void executePeriodically(Runnable task, long initialDelay, long delay, TimeUnit unit);
058
059  /**
060   * Execute a task periodically with a given delay.
061   *
062   * @param task         the task to execute
063   * @param initialDelay the time to delay first execution
064   * @param delay        the delay between the termination of one
065   *                     execution and the commencement of the next
066   * @param unit         the time unit of the initialDelay and delay parameters
067   * @return a ScheduledFuture representing pending completion of
068   * the series of repeated tasks.  The future's {@link
069   * Future#get() get()} method will never return normally,
070   * and will throw an exception upon task cancellation or
071   * abnormal termination of a task execution.
072   */
073  ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, long initialDelay, long delay, TimeUnit unit);
074
075  /**
076   * Execute a task periodically with a given period.
077   *
078   * <p>If any execution of this task takes longer than its period, then
079   * subsequent executions may start late, but will not concurrently
080   * execute.
081   *
082   * @param task         the task to execute
083   * @param initialDelay the time to delay first execution
084   * @param period       the period between successive executions
085   * @param unit         the time unit of the initialDelay and period parameters
086   * @return a ScheduledFuture representing pending completion of
087   * the series of repeated tasks.  The future's {@link
088   * Future#get() get()} method will never return normally,
089   * and will throw an exception upon task cancellation or
090   * abnormal termination of a task execution.
091   */
092  ScheduledFuture<?> scheduleAtFixedRate(Runnable task, long initialDelay, long period, TimeUnit unit);
093
094  /**
095   * Schedules a Runnable for one-shot action that becomes enabled after the given delay.
096   *
097   * @return a ScheduledFuture representing pending completion of the task and
098   * whose get() method will return null upon completion
099   */
100  ScheduledFuture<?> schedule(Runnable task, long delay, TimeUnit unit);
101
102  /**
103   * Schedules a Callable for one-shot action that becomes enabled after the given delay.
104   *
105   * @return a ScheduledFuture that can be used to extract result or cancel
106   */
107  <V> ScheduledFuture<V> schedule(Callable<V> task, long delay, TimeUnit unit);
108
109}