com.almworks.jira.structure.api.job.StructureJobManager Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of structure-api Show documentation
Public API for the Structure Plugin for JIRA
There is a newer version: 17.25.3
package com.almworks.jira.structure.api.job;

import com.almworks.jira.structure.api.util.CallableE;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.concurrent.Future;

/**
 * StructureJobManager allows running and scheduling background jobs.
 *
 * The jobs are run in a separate special thread, maintained by the job manager.
 * There may be one thread or several threads that run the jobs.
 *
 * Each time the job is run, the manager sets up the thread environment and thread locals
 * so that the job may use all standard JIRA services. The current user is set to
 * {@link StructureJob#getUser()}.
 *
 * The finished jobs and job feedback are kept in memory.
 *
 * todo describe it is not JDC-aware
 *
 * @author Igor Sereda
 */
public interface StructureJobManager {
  /**
   * A constant representing the user executor.
   * @see #execute(StructureJob, String)
   */
  String USER_EXECUTOR_ID = "user";

  /**
   * A constant representing the system executor.
   * @see #execute(StructureJob, String)
   */
  String SYSTEM_EXECUTOR_ID = "system";

  String GENERATOR_EXECUTOR_ID = "generator";

  String ATTRIBUTE_EXECUTOR_ID = "attribute";

  String EFFECTOR_EXECUTOR_ID = "effector";

  /**
   * Schedule the job and run it as soon as possible.
   *
   * The job is added to the end of the queue.
   *
   * @param job the job to run
   * @return the ID of the job
   * @throws StructureJobException when the job cannot be scheduled - for example if the component is
   * shut down or if the job has incorrect status
   */
  long enqueue(@NotNull StructureJob job) throws StructureJobException;

  /**
   * Schedule the job and run it as soon as possible.
   *
   * The job bypasses the queue and is executed by the "user" executor.
   *
   * @param job the job to run
   * @return the ID of the job
   * @throws StructureJobException when the job cannot be scheduled - for example if the component is
   * shut down or if the job has incorrect status
   * @since 7.2.0 (Structure 2.0)
   * @see #execute(StructureJob, String)
   * @see #USER_EXECUTOR_ID
   */
  long execute(@NotNull StructureJob job) throws StructureJobException;

  /**
   * Schedule the job and run it as soon as possible.
   *
   * The job bypasses the queue and is executed by a separate executor identified by {@code executorId}.
   *
   * @param job the job to run
   * @param executorId the executor ID
   * @return the ID of the job
   * @throws StructureJobException when the job cannot be scheduled - for example if the component is
   * shut down or if the job has incorrect status; when the executor ID is invalid
   * @since 7.4.0 (Structure 2.3)
   * @see #SYSTEM_EXECUTOR_ID
   * @see #USER_EXECUTOR_ID
   */
  long execute(@NotNull StructureJob job, String executorId) throws StructureJobException;

  /**
   * Schedule the job to run periodically, or once after delay.
   *
   * This method allows to run periodic jobs. Due to the nature of the manager, the intervals
   * are not precise, the job is actually run as soon as possible after the time to run has come.
   *
   * @param initial the initial delay before running the job for the first time, in milliseconds; 0 means run now
   * @param interval the interval between subsequent runnings of the job, in milliseconds; if 0, don't run the job more than once
   * @param job the job to run
   * @return the ID of the job
   * @throws StructureJobException when the job cannot be scheduled - for example if the component is
   * shut down or if the job has incorrect status
   */
  long schedule(long initial, long interval, @NotNull StructureJob job) throws StructureJobException;

  /**
   * Retrieves the job by its ID.
   *
   * @param jobId the id of the job
   * @return the job with the specified ID, or null if no such job exists
   */
  @Nullable
  StructureJob getJob(Long jobId);

  /**
   * Cancels the execution of the job, if possible.
   *
   * @param jobId the ID of the job
   */
  void cancel(Long jobId);

  long execute(@NotNull CallableE callable, @NotNull String executorId) throws StructureJobException;

  @Nullable
   Future getFuture(@Nullable Long jobId);
}