com.almworks.jira.structure.api.job

Interface StructureJobManager

public interface StructureJobManager

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 StructureJob.getUser().

The finished jobs and job feedback are kept in memory.

todo describe it is not JDC-aware

Author:

Igor Sereda

Field Summary

Fields

Modifier and Type	Field and Description
static String	ATTRIBUTE_EXECUTOR_ID
static String	GENERATOR_EXECUTOR_ID
static String	SYSTEM_EXECUTOR_ID A constant representing the system executor.
static String	USER_EXECUTOR_ID A constant representing the user executor.

Method Summary

Modifier and Type	Method and Description
void	cancel(Long jobId) Cancels the execution of the job, if possible.
long	enqueue(StructureJob job) Schedule the job and run it as soon as possible.
long	execute(CallableE<?,?> callable, String executorId)
long	execute(StructureJob job) Schedule the job and run it as soon as possible.
long	execute(StructureJob job, String executorId) Schedule the job and run it as soon as possible.
<T> Future<T>	getFuture(Long jobId)
StructureJob	getJob(Long jobId) Retrieves the job by its ID.
long	schedule(long initial, long interval, StructureJob job) Schedule the job to run periodically, or once after delay.

Field Detail

USER_EXECUTOR_ID

static final String USER_EXECUTOR_ID

A constant representing the user executor.

See Also:

execute(StructureJob, String), Constant Field Values

SYSTEM_EXECUTOR_ID

static final String SYSTEM_EXECUTOR_ID

A constant representing the system executor.

See Also:

execute(StructureJob, String), Constant Field Values

GENERATOR_EXECUTOR_ID

static final String GENERATOR_EXECUTOR_ID

See Also:

Constant Field Values

ATTRIBUTE_EXECUTOR_ID

static final String ATTRIBUTE_EXECUTOR_ID

See Also:

Constant Field Values

Method Detail

enqueue

long enqueue(@NotNull
             StructureJob job)
      throws StructureJobException

Schedule the job and run it as soon as possible.

The job is added to the end of the queue.

Parameters:

job - the job to run

Returns:

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

execute

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 the "user" executor.

Parameters:

job - the job to run

Returns:

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 Also:

execute(StructureJob, String), USER_EXECUTOR_ID

execute

long execute(@NotNull
             StructureJob job,
             String executorId)
      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 executorId.

Parameters:

job - the job to run

executorId - the executor ID

Returns:

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 Also:

SYSTEM_EXECUTOR_ID, USER_EXECUTOR_ID

schedule

long schedule(long initial,
              long interval,
              @NotNull
              StructureJob job)
       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.

Parameters:

initial - the initial delay before running the job for the first time, in milliseconds; 0 means run now

interval - the interval between subsequent runnings of the job, in milliseconds; if 0, don't run the job more than once

job - the job to run

Returns:

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

getJob

@Nullable
StructureJob getJob(Long jobId)

Retrieves the job by its ID.

Parameters:

jobId - the id of the job

Returns:

the job with the specified ID, or null if no such job exists

cancel

void cancel(Long jobId)

Cancels the execution of the job, if possible.

Parameters:

jobId - the ID of the job

execute

long execute(@NotNull
             CallableE<?,?> callable,
             @NotNull
             String executorId)
      throws StructureJobException

Throws:

StructureJobException

getFuture

@Nullable
<T> Future<T> getFuture(@Nullable
                                   Long jobId)