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