Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

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.
`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 another 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.
`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.

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(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 be run.

  See Also:
    `getState()`, 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

### 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.

  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.

  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(IProgressMonitor)`

### getName

    public final String getName()

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

  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.

  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.

  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.

  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`, `setRule(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.

  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.

  Returns:
    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.

### isBlocking

    public final boolean isBlocking()

  Returns whether this job is blocking another non-system job from starting due to a conflicting scheduling rule. Returns `false` if this job is not running, or is not blocking any other job.

  Returns:
    `true` if this job is blocking a waiting 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`.

  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`.

  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.

  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.

  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 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.

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

  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)`.

### 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.

  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

  Parameters:
    `delay` - a time delay in milliseconds before the job should run

### 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 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.

  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.

  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"`).

  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.

  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.

  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.

  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 `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(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`.

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

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

  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`.

  Returns:
    `false` if the job is currently running (and thus cannot be put to sleep), and `true` in all other cases
  See Also:
    `wakeUp()`

### 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.

  Parameters:
    `delay` - the number of milliseconds to delay
  See Also:
    `sleep()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.