Eclipse Platform
Release 3.7

org.eclipse.core.runtime.jobs
Class Job

java.lang.Object
  extended by org.eclipse.core.runtime.PlatformObject
      extended by org.eclipse.core.internal.jobs.InternalJob
          extended by org.eclipse.core.runtime.jobs.Job
All Implemented Interfaces:
Comparable, IAdaptable
Direct Known Subclasses:
org.eclipse.core.internal.resources.InternalWorkspaceJob, ProvisioningJob, 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 run.
 
Fields inherited from class org.eclipse.core.internal.jobs.InternalJob
manager
 
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.
protected  void canceling()
          A hook method indicating that this job is running and cancel() is being called for the first time.
 void done(IStatus result)
          Jobs that complete their execution asynchronously must indicate when they are finished by calling this method.
static IJobManager getJobManager()
          Returns the job manager.
 String getName()
          Returns the human readable name of this job.
 int getPriority()
          Returns the priority of this job.
 Object getProperty(QualifiedName key)
          Returns the value of the property of this job identified by the given key, or null if this job has no such property.
 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 isBlocking()
          Returns whether this job is blocking a higher priority non-system job from starting due to a conflicting scheduling rule.
 boolean isSystem()
          Returns whether this job is a system job.
 boolean isUser()
          Returns whether this job has been directly initiated by a UI end user.
 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 this 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 priority)
          Sets the priority of the job.
 void setProgressGroup(IProgressMonitor group, int ticks)
          Associates this job with a progress group.
 void setProperty(QualifiedName key, Object value)
          Sets the value of the property of this job identified by the given key.
 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.
 void setUser(boolean value)
          Sets whether or not this job has been directly initiated by a UI end user.
 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.
 String toString()
          Returns a string representation of this job to be used for debugging purposes only.
 void wakeUp()
          Puts this job immediately into the WAITING state so that it is eligible for immediate execution.
 void wakeUp(long delay)
          Puts this job back into the WAITING state after the specified delay.
 Job yieldRule(IProgressMonitor monitor)
          Temporarily puts this Job back into WAITING state and relinquishes the job's scheduling rule so that any WAITING jobs that conflict with this job's scheduling rule have an opportunity to start.
 
Methods inherited from class org.eclipse.core.internal.jobs.InternalJob
compareTo
 
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(IProgressMonitor), done(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:
getPriority(), setPriority(int), run(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:
getPriority(), setPriority(int), run(IProgressMonitor), Constant Field Values

LONG

public static final int LONG
Job priority constant (value 30) for long-running background jobs.

See Also:
getPriority(), setPriority(int), run(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:
getPriority(), setPriority(int), run(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:
getPriority(), setPriority(int), run(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:
getState(), Constant Field Values

SLEEPING

public static final int SLEEPING
Job state code (value 1) indicating that a job is sleeping.

See Also:
run(IProgressMonitor), getState(), Constant Field Values

WAITING

public static final int WAITING
Job state code (value 2) indicating that a job is waiting to run.

See Also:
getState(), yieldRule(IProgressMonitor), Constant Field Values

RUNNING

public static final int RUNNING
Job state code (value 4) indicating that a job is currently running

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

getJobManager

public static final IJobManager getJobManager()
Returns the job manager.

Returns:
the job manager
Since:
org.eclipse.core.jobs 3.2

addJobChangeListener

public final void addJobChangeListener(IJobChangeListener listener)
Registers a job listener with this job Has no effect if an identical listener is already registered.

Overrides:
addJobChangeListener in class org.eclipse.core.internal.jobs.InternalJob
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.

Overrides:
belongsTo in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
family - the job family identifier
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.

Overrides:
cancel in class org.eclipse.core.internal.jobs.InternalJob
Returns:
false if the job is currently running (and thus may not respond to cancelation), and true in all other cases.

canceling

protected void canceling()
A hook method indicating that this job is running and cancel() is being called for the first time.

Subclasses may override this method to perform additional work when a cancelation request is made. This default implementation does nothing.

Overrides:
canceling in class org.eclipse.core.internal.jobs.InternalJob
Since:
3.3

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.

Overrides:
done in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
result - a status object indicating the result of the job's execution.
See Also:
ASYNC_FINISH, run(IProgressMonitor)

getName

public final String getName()
Returns the human readable name of this job. The name is never null.

Overrides:
getName in class org.eclipse.core.internal.jobs.InternalJob
Returns:
the name of this job

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.

Overrides:
getPriority in class org.eclipse.core.internal.jobs.InternalJob
Returns:
the priority of the job. One of INTERACTIVE, SHORT, LONG, BUILD, or DECORATE.

getProperty

public final Object getProperty(QualifiedName key)
Returns the value of the property of this job identified by the given key, or null if this job has no such property.

Overrides:
getProperty in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
key - the name of the property
Returns:
the value of the property, or null if this job has no such property
See Also:
setProperty(QualifiedName, Object)

getResult

public final IStatus getResult()
Returns the result of this job's last run.

Overrides:
getResult in class org.eclipse.core.internal.jobs.InternalJob
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.

Overrides:
getRule in class org.eclipse.core.internal.jobs.InternalJob
Returns:
the scheduling rule for this job, or null.
See Also:
ISchedulingRule, setRule(ISchedulingRule)

getState

public final int getState()
Returns the state of the job. Result will be one of:

Note that job state is inherently volatile, and in most cases clients cannot rely on the result of this method being valid by the time the result is obtained. For example, if getState returns RUNNING, the job may have actually completed by the time the getState method returns. All clients can infer from invoking this method is that the job was recently in the returned state.

Overrides:
getState in class org.eclipse.core.internal.jobs.InternalJob
Returns:
the job state

getThread

public final Thread getThread()
Returns the thread that this job is currently running in.

Overrides:
getThread in class org.eclipse.core.internal.jobs.InternalJob
Returns:
the thread this job is running in, or null if this job is not running or the thread is unknown.

isBlocking

public final boolean isBlocking()
Returns whether this job is blocking a higher priority non-system job from starting due to a conflicting scheduling rule. Returns false if this job is not running, or is not blocking a higher priority non-system job.

Overrides:
isBlocking in class org.eclipse.core.internal.jobs.InternalJob
Returns:
true if this job is blocking a higher priority non-system job, and false otherwise.
See Also:
getRule(), isSystem()

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. The default value is false.

Overrides:
isSystem in class org.eclipse.core.internal.jobs.InternalJob
Returns:
true if this job is a system job, and false otherwise.
See Also:
setSystem(boolean)

isUser

public final boolean isUser()
Returns whether this job has been directly initiated by a UI end user. These jobs may be presented differently in the UI. The default value is false.

Overrides:
isUser in class org.eclipse.core.internal.jobs.InternalJob
Returns:
true if this job is a user-initiated job, and false otherwise.
See Also:
setUser(boolean)

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. A job must not be joined from within the scope of its run method.

If this method is called on a job that reschedules itself from within the run method, the join will return at the end of the first execution. In other words, join will return the first time this job exits the RUNNING state, or as soon as this job enters the NONE state.

If this method is called while the job manager is suspended, this job will only be joined if it is already running; if this job is waiting or sleeping, 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.

Overrides:
join in class org.eclipse.core.internal.jobs.InternalJob
Throws:
InterruptedException - if this thread is interrupted while waiting
See Also:
ILock, IJobManager.suspend()

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.

Overrides:
removeJobChangeListener in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
listener - the listener to be removed

run

protected abstract IStatus run(IProgressMonitor monitor)
Executes this 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 canceled, the job should finish its execution at the earliest convenience and return a result status of severity IStatus.CANCEL. The singleton cancel status Status.CANCEL_STATUS can be used for this purpose. The monitor is only valid for the duration of the invocation of this method.

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 ASYNC_FINISH. Jobs that finish asynchronously must specify the execution thread by calling setThread, and must indicate when they are finished by calling the method done.

Specified by:
run in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
monitor - the monitor to be used for reporting progress and responding to cancelation. The monitor is never null
Returns:
resulting status of the run. The result must not be null
See Also:
ASYNC_FINISH, done(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).

See Also:
schedule(long)

schedule

public final void schedule(long delay)
Schedules this job to be run after a specified delay. The job is put in the SLEEPING state until the specified delay has elapsed, after which the job is added to a queue of WAITING jobs. Once the job arrives at the beginning of the queue, it will be run at the first available opportunity.

Jobs of equal priority and delay with conflicting scheduling rules are guaranteed to run in the order they are scheduled. No guarantees are made about the relative execution order of jobs with unrelated or null scheduling rules, or different priorities.

If this job is currently running, it will be rescheduled with the specified delay as soon as it finishes. If this method is called multiple times while the job is running, the job will still only be rescheduled once, with the most recent delay value that was provided.

Scheduling a job that is waiting or sleeping has no effect.

Overrides:
schedule in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
delay - a time delay in milliseconds before the job should run
See Also:
ISchedulingRule

setName

public final void setName(String name)
Changes the name of this job. If the job is currently running, waiting, or sleeping, the new job name may not take effect until the next time the job is scheduled.

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.

Overrides:
setName in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
name - the name of the job.

setPriority

public final void setPriority(int priority)
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.

Overrides:
setPriority in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
priority - the new job priority. One of INTERACTIVE, SHORT, LONG, BUILD, or DECORATE.

setProgressGroup

public final void setProgressGroup(IProgressMonitor group,
                                   int ticks)
Associates this job with a progress group. Progress feedback on this job's next execution will be displayed together with other jobs in that group. The provided monitor must be a monitor created by the method IJobManager.createProgressGroup and must have at least ticks units of available work.

The progress group must be set before the job is scheduled. The group will be used only for a single invocation of the job's run method, after which any association of this job to the group will be lost.

Overrides:
setProgressGroup in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
group - The progress group to use for this job
ticks - the number of work ticks allocated from the parent monitor, or IProgressMonitor.UNKNOWN
See Also:
IJobManager.createProgressGroup()

setProperty

public void setProperty(QualifiedName key,
                        Object value)
Sets the value of the property of this job identified by the given key. If the supplied value is null, the property is removed from this resource.

Properties are intended to be used as a caching mechanism by ISV plug-ins. They allow key-object associations to be stored with a job instance. These key-value associations are maintained in memory (at all times), and the information is never discarded automatically.

The qualifier part of the property name must be the unique identifier of the declaring plug-in (e.g. "com.example.plugin").

Overrides:
setProperty in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
key - the qualified name of the property
value - the value of the property, or null if the property is to be removed
See Also:
getProperty(QualifiedName)

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.

Overrides:
setRule in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
rule - the new scheduling rule, or null if the job should have no scheduling rule
See Also:
getRule()

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. This method must be called before the job is scheduled.

Overrides:
setSystem in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
value - true if this job should be a system job, and false otherwise.
See Also:
isSystem()

setUser

public final void setUser(boolean value)
Sets whether or not this job has been directly initiated by a UI end user. These jobs may be presented differently in the UI. This method must be called before the job is scheduled.

Overrides:
setUser in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
value - true if this job is a user-initiated job, and false otherwise.
See Also:
isUser()

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 ASYNC_FINISH return code should tell the job what thread it is running in. This is used to prevent deadlocks.

Overrides:
setThread in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
thread - the thread that this job is running in.
See Also:
ASYNC_FINISH, run(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 precondition 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.

Returns:
true if this job should be run and false otherwise

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 precondition checking before a job is scheduled.

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

Overrides:
shouldSchedule in class org.eclipse.core.internal.jobs.InternalJob
Returns:
true if the job manager should schedule this job and false otherwise

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.

Overrides:
sleep in class org.eclipse.core.internal.jobs.InternalJob
Returns:
false if the job is currently running (and thus cannot be put to sleep), and true in all other cases
See Also:
wakeUp()

toString

public String toString()
Returns a string representation of this job to be used for debugging purposes only.

Overrides:
toString in class org.eclipse.core.internal.jobs.InternalJob
Since:
org.eclipse.core.jobs 3.5

wakeUp

public final void wakeUp()
Puts this job immediately into the WAITING state so that it is eligible for immediate execution. If this job is not currently sleeping, the request is ignored.

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

See Also:
sleep()

wakeUp

public final void wakeUp(long delay)
Puts this job back into the WAITING state after the specified delay. This is equivalent to canceling the sleeping job and rescheduling with the given delay. If this job is not currently sleeping, the request is ignored.

Overrides:
wakeUp in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
delay - the number of milliseconds to delay
See Also:
sleep()

yieldRule

public Job yieldRule(IProgressMonitor monitor)
Temporarily puts this Job back into WAITING state and relinquishes the job's scheduling rule so that any WAITING jobs that conflict with this job's scheduling rule have an opportunity to start. This method will wait until the rule this job held prior to invoking this method is re-acquired. This method has no effect and returns null if there are no WAITING jobs that conflict with this job's scheduling rule.

Note: If this job has acquired any other locks, implicit or explicit, they will not be released. This may increase the risk of deadlock, so this method should only be used when it is known that the environment is safe.

This method must be invoked by this job's Thread, and only when it is RUNNING state.

Overrides:
yieldRule in class org.eclipse.core.internal.jobs.InternalJob
Parameters:
monitor - a progress monitor, or null if progress reporting is not desired. Cancellation attempts will be ignored.
Returns:
The Job that was WAITING, and blocked by this Job (at the time this method was invoked) that was unblocked and allowed a chance to run, or null if no jobs were unblocked. Note: it is not guaranteed that this Job resume immediately if other conflicting jobs are also waiting after the unblocked job ends.
Since:
org.eclipse.core.jobs 3.5
See Also:
getRule(), isBlocking()

Eclipse Platform
Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.