/*
 * The contents of this file are subject to the Mozilla Public License Version 1.1
 * (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.mozilla.org/MPL/>.
 * 
 * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT
 * WARRANTY OF ANY KIND, either express or implied. See the License for the specific
 * language governing rights and limitations under the License.
 * 
 * The Original Code is the Venice Web Communities System.
 * 
 * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
 * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
 * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
 * 
 * Contributor(s): 
 */
package com.silverwrist.dynamo.iface;

import java.util.Date;

/**
 * A service interface which allows {@link com.silverwrist.dynamo.iface.BackgroundTask BackgroundTask}s to
 * be scheduled for later execution by the Dynamo engine.  When background tasks are executed, they are provided
 * with a {@link com.silverwrist.dynamo.iface.ServiceProvider ServiceProvider} that provides access to all the
 * Dynamo services that are "safe" for a background task to use.
 *
 * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
 * @version X
 */
public interface BackgroundScheduler
{
  /**
   * Schedule a task to be run "later," i.e., at any time after the present time, without interrupting the
   * current thread's processing.  Background processing of tasks submitted by this method are handled by a
   * pool of threads.
   *
   * @param task The task to be scheduled to run later.
   * @param low_priority If this is <CODE>true</CODE>, the task is handled by a pool of low-priority threads
   *                     instead of by a pool of normal-priority threads.  Low-priority threads will generally
   *                     execute only after normal-priority threads, but are not guaranteed to.
   */
  public void runTaskLater(BackgroundTask task, boolean low_priority);

  /**
   * Schedule a task to be run on a one-shot basis after a delay.
   *
   * @param task The task to be scheduled to run.
   * @param delay The delay, in milliseconds, before this task is to be run.  The actual delay may be longer
   *              than this.
   * @return An instance of a {@link com.silverwrist.dynamo.iface.ComponentShutdown ComponentShutdown} object,
   *         whose {@link com.silverwrist.dynamo.iface.ComponentShutdown#shutdown() shutdown()} method may be
   *         called to abort the execution of this task at any time before it is actually run.  If this is called
   *         after the task is run, it has no effect.
   */
  public ComponentShutdown runTaskAfter(BackgroundTask task, long delay);

  /**
   * Schedule a task to be run on a one-shot basis at a certain time.
   *
   * @param task The task to be scheduled to run.
   * @param when The date/time at which the task is to be run.  The actual task start time may be any time
   *             after this.
   * @return An instance of a {@link com.silverwrist.dynamo.iface.ComponentShutdown ComponentShutdown} object,
   *         whose {@link com.silverwrist.dynamo.iface.ComponentShutdown#shutdown() shutdown()} method may be
   *         called to abort the execution of this task at any time before it is actually run.  If this is called
   *         after the task is run, it has no effect.
   */
  public ComponentShutdown runTaskAt(BackgroundTask task, Date when);

  /**
   * Schedule a task to be run periodically, after a delay.
   *
   * @param task The task to be scheduled to run.
   * @param delay The delay, in milliseconds, before this task is to be run for the first time.  The actual
   *              delay may be longer than this.
   * @param period The time, in milliseconds, between successive executions of the task.  The task will be
   *               scheduled for repeated execution, delaying at least this long between executions.
   * @return An instance of a {@link com.silverwrist.dynamo.iface.ComponentShutdown ComponentShutdown} object,
   *         whose {@link com.silverwrist.dynamo.iface.ComponentShutdown#shutdown() shutdown()} method may be
   *         called to abort the periodic execution of this task at any time.
   */
  public ComponentShutdown runTaskPeriodic(BackgroundTask task, long delay, long period);

  /**
   * Schedule a task to be run periodically, beginning at a specified time.
   *
   * @param task The task to be scheduled to run.
   * @param when The date/time at which the task is to be run for the first time.  The actual task start time
   *             may be any time after this.
   * @param period The time, in milliseconds, between successive executions of the task.  The task will be
   *               scheduled for repeated execution, delaying at least this long between executions.
   * @return An instance of a {@link com.silverwrist.dynamo.iface.ComponentShutdown ComponentShutdown} object,
   *         whose {@link com.silverwrist.dynamo.iface.ComponentShutdown#shutdown() shutdown()} method may be
   *         called to abort the periodic execution of this task at any time.
   */
  public ComponentShutdown runTaskPeriodic(BackgroundTask task, Date start, long period);

  /**
   * Schedule a task to be run periodically, after a delay.
   *
   * @param task The task to be scheduled to run.
   * @param delay The delay, in milliseconds, before this task is to be run for the first time.  The actual
   *              delay may be longer than this.
   * @param period The time, in milliseconds, between successive executions of the task.  The task will be
   *               scheduled for repeated execution, with the task being started with roughly this many
   *               milliseconds between each start attempt.  If execution is delayed, this task will try to
   *               "catch up" by scheduling executions more frequently.
   * @return An instance of a {@link com.silverwrist.dynamo.iface.ComponentShutdown ComponentShutdown} object,
   *         whose {@link com.silverwrist.dynamo.iface.ComponentShutdown#shutdown() shutdown()} method may be
   *         called to abort the periodic execution of this task at any time.
   */
  public ComponentShutdown runTaskFixedRate(BackgroundTask task, long delay, long period);

  /**
   * Schedule a task to be run periodically, beginning at a specified time.
   *
   * @param task The task to be scheduled to run.
   * @param when The date/time at which the task is to be run for the first time.  The actual task start time
   *             may be any time after this.
   * @param period The time, in milliseconds, between successive executions of the task.  The task will be
   *               scheduled for repeated execution, with the task being started with roughly this many
   *               milliseconds between each start attempt.  If execution is delayed, this task will try to
   *               "catch up" by scheduling executions more frequently.
   * @return An instance of a {@link com.silverwrist.dynamo.iface.ComponentShutdown ComponentShutdown} object,
   *         whose {@link com.silverwrist.dynamo.iface.ComponentShutdown#shutdown() shutdown()} method may be
   *         called to abort the periodic execution of this task at any time.
   */
  public ComponentShutdown runTaskFixedRate(BackgroundTask task, Date start, long period);

} // end interface BackgroundScheduler

