org.eclipse.core.runtime.jobs
Class Job

java.lang.Object
  org.eclipse.core.runtime.PlatformObject
      org.eclipse.core.internal.jobs.InternalJob
          org.eclipse.core.runtime.jobs.Job

All Implemented Interfaces:

Comparable, IAdaptable

Direct Known Subclasses:

org.eclipse.core.internal.resources.InternalWorkspaceJob, UIJob

public abstract class Job

extends org.eclipse.core.internal.jobs.InternalJob

implements IAdaptable

Jobs are units of runnable work that can be scheduled to be run with the job manager. Once a job has completed, it can be scheduled to run again (jobs are reusable). Jobs have a state that indicates what they are currently doing. When constructed, jobs start with a state value of NONE. When a job is scheduled to be run, it moves into the WAITING state. When a job starts running, it moves into the RUNNING state. When execution finishes (either normally or through cancelation), the state changes back to NONE. A job can also be in the SLEEPING state. This happens if a user calls Job.sleep() on a waiting job, or if a job is scheduled to run after a specified delay. Only jobs in the WAITING state can be put to sleep. Sleeping jobs can be woken at any time using Job.wakeUp(), which will put the job back into the WAITING state. Jobs can be assigned a priority that is used as a hint about how the job should be scheduled. There is no guarantee that jobs of one priority will be run before all jobs of lower priority. The javadoc for the various priority constants provide more detail about what each priority means. By default, jobs start in the LONG priority class.

Since:

3.0

See Also:

IJobManager

Field Summary

static IStatus	ASYNC_FINISH Job status return value that is used to indicate asynchronous job completion.
static int	BUILD Job priority constant (value 40) for build jobs.
static int	DECORATE Job priority constant (value 50) for decoration jobs.
static int	INTERACTIVE Job priority constant (value 10) for interactive jobs.
static int	LONG Job priority constant (value 30) for long-running background jobs.
static int	NONE Job state code (value 0) indicating that a job is not currently sleeping, waiting, or running (i.e., the job manager doesn't know anything about the job).
static int	RUNNING Job state code (value 4) indicating that a job is currently running
static int	SHORT Job priority constant (value 20) for short background jobs.
static int	SLEEPING Job state code (value 1) indicating that a job is sleeping.
static int	WAITING Job state code (value 2) indicating that a job is waiting to be run.

Fields inherited from class org.eclipse.core.internal.jobs.InternalJob

BLOCKED

Constructor Summary

Job(String name)
Creates a new job with the specified name.

Method Summary

void	addJobChangeListener(IJobChangeListener listener) Registers a job listener with this job Has no effect if an identical listener is already registered.
boolean	belongsTo(Object family) Returns whether this job belongs to the given family.
boolean	cancel() Stops the job.
void	done(IStatus result) Jobs that complete their execution asynchronously must indicate when they are finished by calling this method.
String	getName() Returns the human readable name of this job.
int	getPriority() Returns the priority of this job.
IStatus	getResult() Returns the result of this job's last run.
ISchedulingRule	getRule() Returns the scheduling rule for this job.
int	getState() Returns the state of the job.
Thread	getThread() Returns the thread that this job is currently running in.
boolean	isSystem() Returns whether this job is a system job.
void	join() Waits until this job is finished.
void	removeJobChangeListener(IJobChangeListener listener) Removes a job listener from this job.
protected abstract IStatus	run(IProgressMonitor monitor) Executes the current job.
void	schedule() Schedules this job to be run.
void	schedule(long delay) Schedules this job to be run after a specified delay.
void	setName(String name) Changes the name of this job.
void	setPriority(int i) Sets the priority of the job.
void	setRule(ISchedulingRule rule) Sets the scheduling rule to be used when scheduling this job.
void	setSystem(boolean value) Sets whether or not this job is a system job.
void	setThread(Thread thread) Sets the thread that this job is currently running in, or null if this job is not running or the thread is unknown.
boolean	shouldRun() Returns whether this job should be run.
boolean	shouldSchedule() Returns whether this job should be scheduled.
boolean	sleep() Requests that this job be suspended.
void	wakeUp() Resumes execution of the given job.

Methods inherited from class org.eclipse.core.internal.jobs.InternalJob

compareTo, toString

Methods inherited from class org.eclipse.core.runtime.PlatformObject

getAdapter

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Field Detail

ASYNC_FINISH

public static final IStatus ASYNC_FINISH

Job status return value that is used to indicate asynchronous job completion.

See Also:

run(org.eclipse.core.runtime.IProgressMonitor), done(org.eclipse.core.runtime.IStatus)

INTERACTIVE

public static final int INTERACTIVE

Job priority constant (value 10) for interactive jobs. Interactive jobs generally have priority over all other jobs. Interactive jobs should be either fast running or very low on CPU usage to avoid blocking other interactive jobs from running.

See Also:

IJobManager#getPriority, IJobManager#setPriority, run(org.eclipse.core.runtime.IProgressMonitor), Constant Field Values

SHORT

public static final int SHORT

Job priority constant (value 20) for short background jobs. Short background jobs are jobs that typically complete within a second, but may take longer in some cases. Short jobs are given priority over all other jobs except interactive jobs.

See Also:

IJobManager#getPriority, IJobManager#setPriority, run(org.eclipse.core.runtime.IProgressMonitor), Constant Field Values

LONG

public static final int LONG

Job priority constant (value 30) for long-running background jobs. see IJobManager#getPriority

See Also:

IJobManager#setPriority, run(org.eclipse.core.runtime.IProgressMonitor), Constant Field Values

BUILD

public static final int BUILD

Job priority constant (value 40) for build jobs. Build jobs are generally run after all other background jobs complete.

See Also:

IJobManager#getPriority, IJobManager#setPriority, run(org.eclipse.core.runtime.IProgressMonitor), Constant Field Values

DECORATE

public static final int DECORATE

Job priority constant (value 50) for decoration jobs. Decoration jobs have lowest priority. Decoration jobs generally compute extra information that the user may be interested in seeing but is generally not waiting for.

See Also:

IJobManager#getPriority, IJobManager#setPriority, run(org.eclipse.core.runtime.IProgressMonitor), Constant Field Values

NONE

public static final int NONE

Job state code (value 0) indicating that a job is not currently sleeping, waiting, or running (i.e., the job manager doesn't know anything about the job).

See Also:

IJobManager#getState, Constant Field Values

SLEEPING

public static final int SLEEPING

Job state code (value 1) indicating that a job is sleeping.

See Also:

run(org.eclipse.core.runtime.IProgressMonitor), IJobManager#getState, Constant Field Values

WAITING

public static final int WAITING

Job state code (value 2) indicating that a job is waiting to be run.

See Also:

IJobManager#getState, Constant Field Values

RUNNING

public static final int RUNNING

Job state code (value 4) indicating that a job is currently running

See Also:

IJobManager#getState, Constant Field Values

Constructor Detail

Job

public Job(String name)

Creates a new job with the specified name. The job name is a human-readable value that is displayed to users. The name does not need to be unique, but it must not be null.

Parameters:

name - the name of the job.

Method Detail

addJobChangeListener

public final void addJobChangeListener(IJobChangeListener listener)

Registers a job listener with this job Has no effect if an identical listener is already registered.

Parameters:

listener - the listener to be added.

belongsTo

public boolean belongsTo(Object family)

Returns whether this job belongs to the given family. Job families are represented as objects that are not interpreted or specified in any way by the job manager. Thus, a job can choose to belong to any number of families.

Clients may override this method. This default implementation always returns false. Overriding implementations must return false for families they do not recognize.

Returns:

true if this job belongs to the given family, and false otherwise.

cancel

public final boolean cancel()

Stops the job. If the job is currently waiting, it will be removed from the queue. If the job is sleeping, it will be discarded without having a chance to resume and its sleeping state will be cleared. If the job is currently executing, it will be asked to stop but there is no guarantee that it will do so.

Returns:

false if the job is currently running (and thus may not respond to cancelation), and true in all other cases.

done

public final void done(IStatus result)

Jobs that complete their execution asynchronously must indicate when they are finished by calling this method. This method must not be called by a job that has not indicated that it is executing asynchronously.

This method must not be called from within the scope of a job's run method. Jobs should normally indicate completion by returning an appropriate status from the run method. Jobs that return a status of ASYNC_FINISH from their run method must later call done to indicate completion.

Parameters:

result - a status object indicating the result of the job's execution.

See Also:

ASYNC_FINISH, run(org.eclipse.core.runtime.IProgressMonitor)

getName

public final String getName()

Returns the human readable name of this job. The name is never null.

getPriority

public final int getPriority()

Returns the priority of this job. The priority is used as a hint when the job is scheduled to be run.

Returns:

the priority of the job. One of INTERACTIVE, SHORT, LONG, BUILD, or DECORATE.

getResult

public final IStatus getResult()

Returns the result of this job's last run.

Returns:

the result of this job's last run, or null if this job has never finished running.

getRule

public final ISchedulingRule getRule()

Returns the scheduling rule for this job. Returns null if this job has no scheduling rule.

Returns:

the scheduling rule for this job, or null.

See Also:

ISchedulingRule

getState

public final int getState()

Returns the state of the job. Result will be one of:

• Job.RUNNING - if the job is currently running.
• Job.WAITING - if the job is waiting to be run.
• Job.SLEEPING - if the job is sleeping.
• Job.NONE - in all other cases.

Return the job state

getThread

public final Thread getThread()

Returns the thread that this job is currently running in.

Returns:

the thread this job is running in, or null if this job is not running or the thread is unknown.

isSystem

public final boolean isSystem()

Returns whether this job is a system job. System jobs are typically not revealed to users in any UI presentation of jobs. Other than their UI presentation, system jobs act exactly like other jobs. If this value is not explicitly set, jobs are treated as non-system jobs.

Returns:

true if this job is a system job, and false otherwise.

See Also:

setSystem

join

public final void join()
                throws InterruptedException

Waits until this job is finished. This method will block the calling thread until the job has finished executing, or until this thread has been interrupted. If the job has not been scheduled, this method returns immediately.

Note that there is a deadlock risk when using join. If the calling thread owns a lock or object monitor that the joined thread is waiting for, deadlock will occur.

Throws:

InterruptedException - if this thread is interrupted while waiting

See Also:

ILock

removeJobChangeListener

public final void removeJobChangeListener(IJobChangeListener listener)

Removes a job listener from this job. Has no effect if an identical listener is not already registered.

Parameters:

listener - the listener to be removed.

run

protected abstract IStatus run(IProgressMonitor monitor)

Executes the current job. Returns the result of the execution.

The provided monitor can be used to report progress and respond to cancellation. If the progress monitor has been cancelled, the job should finish its execution at the earliest convenience.

This method must not be called directly by clients. Clients should call schedule, which will in turn cause this method to be called.

Jobs can optionally finish their execution asynchronously (in another thread) by returning a result status of Job.ASYNC_FINISH. Jobs that finish asynchronously must indicate when they are finished by calling the method Job.done.

Parameters:

monitor - the monitor to be used for reporting progress, or null if progress monitoring is not required.

Returns:

the job result.

See Also:

ASYNC_FINISH, done(org.eclipse.core.runtime.IStatus)

schedule

public final void schedule()

Schedules this job to be run. The job is added to a queue of waiting jobs, and will be run when it arrives at the beginning of the queue.

This is a convenience method, fully equivalent to schedule(0L).

schedule

public final void schedule(long delay)

Schedules this job to be run after a specified delay. After the specified delay, the job is added to a queue of waiting jobs, and will be run when it arrives at the beginning of the queue.

Scheduling a job that is already waiting, sleeping, or running has no effect

setName

public final void setName(String name)

Changes the name of this job. The job name is a human-readable value that is displayed to users. The name does not need to be unique, but it must not be null.

Parameters:

name - the name of the job.

setPriority

public final void setPriority(int i)

Sets the priority of the job. This will not affect the execution of a running job, but it will affect how the job is scheduled while it is waiting to be run.

setRule

public final void setRule(ISchedulingRule rule)

Sets the scheduling rule to be used when scheduling this job. This method must be called before the job is scheduled.

Parameters:

rule - the new scheduling rule, or null if the job should have no scheduling rule

setSystem

public final void setSystem(boolean value)

Sets whether or not this job is a system job. System jobs are typically not revealed to users in any UI presentation of jobs. Other than their UI presentation, system jobs act exactly like other jobs. If this value is not explicitly set, jobs are treated as non-system jobs.

Parameters:

value - true if this job should be a system job, and false otherwise.

See Also:

isSystem

setThread

public final void setThread(Thread thread)

Sets the thread that this job is currently running in, or null if this job is not running or the thread is unknown.

Jobs that use the Job.ASYNC_FINISH return code should tell the job what thread it is running in. This is used to prevent deadlocks

Parameters:

thread - the thread that this job is running in.

See Also:

ASYNC_FINISH, run(org.eclipse.core.runtime.IProgressMonitor)

shouldRun

public boolean shouldRun()

Returns whether this job should be run. If false is returned, this job will be discarded by the job manager without running.

This method is called immediately prior to calling the job's run method, so it can be used for last minute pre-condition checking before a job is run. This method must not attempt to schedule or change the state of any other job.

Clients may override this method. This default implementation always returns true.

shouldSchedule

public boolean shouldSchedule()

Returns whether this job should be scheduled. If false is returned, this job will be discarded by the job manager without being added to the queue.

This method is called immediately prior to adding the job to the waiting job queue.,so it can be used for last minute pre-condition checking before a job is scheduled.

Clients may override this method. This default implementation always returns true.

sleep

public final boolean sleep()

Requests that this job be suspended. If the job is currently waiting to be run, it will be removed from the queue move into the SLEEPING state. The job will remain asleep until either resumed or canceled. If this job is not currently waiting to be run, this method has no effect. Sleeping jobs can be resumed using wakeUp.

Returns:

false if the job is currently running (and thus cannot be put to sleep), and true in all other cases.

wakeUp

public final void wakeUp()

Resumes execution of the given job. If the job is not currently sleeping, this request is ignored.