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
|
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. |
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
|
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
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.
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:
-
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.
-
-
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()
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()
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.