|
Eclipse Platform Release 3.7 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectorg.eclipse.core.runtime.PlatformObject
org.eclipse.core.internal.jobs.InternalJob
org.eclipse.core.runtime.jobs.Job
public abstract class Job
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.
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 |
|---|
public static final IStatus ASYNC_FINISH
run(IProgressMonitor),
done(IStatus)public static final int INTERACTIVE
getPriority(),
setPriority(int),
run(IProgressMonitor),
Constant Field Valuespublic static final int SHORT
getPriority(),
setPriority(int),
run(IProgressMonitor),
Constant Field Valuespublic static final int LONG
getPriority(),
setPriority(int),
run(IProgressMonitor),
Constant Field Valuespublic static final int BUILD
getPriority(),
setPriority(int),
run(IProgressMonitor),
Constant Field Valuespublic static final int DECORATE
getPriority(),
setPriority(int),
run(IProgressMonitor),
Constant Field Valuespublic static final int NONE
getState(),
Constant Field Valuespublic static final int SLEEPING
run(IProgressMonitor),
getState(),
Constant Field Valuespublic static final int WAITING
getState(),
yieldRule(IProgressMonitor),
Constant Field Valuespublic static final int RUNNING
getState(),
Constant Field Values| Constructor Detail |
|---|
public Job(String name)
null.
name - the name of the job.| Method Detail |
|---|
public static final IJobManager getJobManager()
public final void addJobChangeListener(IJobChangeListener listener)
addJobChangeListener in class org.eclipse.core.internal.jobs.InternalJoblistener - the listener to be added.public boolean belongsTo(Object family)
Clients may override this method. This default implementation always returns
false. Overriding implementations must return false
for families they do not recognize.
belongsTo in class org.eclipse.core.internal.jobs.InternalJobfamily - the job family identifier
true if this job belongs to the given family, and
false otherwise.public final boolean cancel()
cancel in class org.eclipse.core.internal.jobs.InternalJobfalse if the job is currently running (and thus may not
respond to cancelation), and true in all other cases.protected void canceling()
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.
canceling in class org.eclipse.core.internal.jobs.InternalJobpublic final void done(IStatus result)
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.
done in class org.eclipse.core.internal.jobs.InternalJobresult - a status object indicating the result of the job's execution.ASYNC_FINISH,
run(IProgressMonitor)public final String getName()
null.
getName in class org.eclipse.core.internal.jobs.InternalJobpublic final int getPriority()
getPriority in class org.eclipse.core.internal.jobs.InternalJobpublic final Object getProperty(QualifiedName key)
null if this job has no such property.
getProperty in class org.eclipse.core.internal.jobs.InternalJobkey - the name of the property
null if this job has no such propertysetProperty(QualifiedName, Object)public final IStatus getResult()
getResult in class org.eclipse.core.internal.jobs.InternalJobnull if this
job has never finished running.public final ISchedulingRule getRule()
null if this job has no
scheduling rule.
getRule in class org.eclipse.core.internal.jobs.InternalJobnull.ISchedulingRule,
setRule(ISchedulingRule)public final int getState()
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.
getState in class org.eclipse.core.internal.jobs.InternalJobpublic final Thread getThread()
getThread in class org.eclipse.core.internal.jobs.InternalJobnull
if this job is not running or the thread is unknown.public final boolean isBlocking()
false
if this job is not running, or is not blocking a higher priority non-system job.
isBlocking in class org.eclipse.core.internal.jobs.InternalJobtrue if this job is blocking a higher priority non-system
job, and false otherwise.getRule(),
isSystem()public final boolean isSystem()
false.
isSystem in class org.eclipse.core.internal.jobs.InternalJobtrue if this job is a system job, and
false otherwise.setSystem(boolean)public final boolean isUser()
false.
isUser in class org.eclipse.core.internal.jobs.InternalJobtrue if this job is a user-initiated job, and
false otherwise.setUser(boolean)
public final void join()
throws InterruptedException
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.
join in class org.eclipse.core.internal.jobs.InternalJobInterruptedException - if this thread is interrupted while waitingILock,
IJobManager.suspend()public final void removeJobChangeListener(IJobChangeListener listener)
removeJobChangeListener in class org.eclipse.core.internal.jobs.InternalJoblistener - the listener to be removedprotected abstract IStatus run(IProgressMonitor monitor)
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.
run in class org.eclipse.core.internal.jobs.InternalJobmonitor - the monitor to be used for reporting progress and
responding to cancelation. The monitor is never null
nullASYNC_FINISH,
done(IStatus)public final void schedule()
This is a convenience method, fully equivalent to
schedule(0L).
schedule(long)public final void schedule(long delay)
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.
schedule in class org.eclipse.core.internal.jobs.InternalJobdelay - a time delay in milliseconds before the job should runISchedulingRulepublic final void setName(String 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.
setName in class org.eclipse.core.internal.jobs.InternalJobname - the name of the job.public final void setPriority(int priority)
setPriority in class org.eclipse.core.internal.jobs.InternalJobpriority - the new job priority. One of
INTERACTIVE, SHORT, LONG, BUILD, or DECORATE.
public final void setProgressGroup(IProgressMonitor group,
int ticks)
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.
setProgressGroup in class org.eclipse.core.internal.jobs.InternalJobgroup - The progress group to use for this jobticks - the number of work ticks allocated from the
parent monitor, or IProgressMonitor.UNKNOWNIJobManager.createProgressGroup()
public void setProperty(QualifiedName key,
Object value)
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").
setProperty in class org.eclipse.core.internal.jobs.InternalJobkey - the qualified name of the propertyvalue - the value of the property,
or null if the property is to be removedgetProperty(QualifiedName)public final void setRule(ISchedulingRule rule)
setRule in class org.eclipse.core.internal.jobs.InternalJobrule - the new scheduling rule, or null if the job
should have no scheduling rulegetRule()public final void setSystem(boolean value)
setSystem in class org.eclipse.core.internal.jobs.InternalJobvalue - true if this job should be a system job, and
false otherwise.isSystem()public final void setUser(boolean value)
setUser in class org.eclipse.core.internal.jobs.InternalJobvalue - true if this job is a user-initiated job, and
false otherwise.isUser()public final void setThread(Thread thread)
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.
setThread in class org.eclipse.core.internal.jobs.InternalJobthread - the thread that this job is running in.ASYNC_FINISH,
run(IProgressMonitor)public boolean shouldRun()
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.
true if this job should be run
and false otherwisepublic boolean shouldSchedule()
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.
shouldSchedule in class org.eclipse.core.internal.jobs.InternalJobtrue if the job manager should schedule this job
and false otherwisepublic final boolean sleep()
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.
sleep in class org.eclipse.core.internal.jobs.InternalJobfalse if the job is currently running (and thus cannot
be put to sleep), and true in all other caseswakeUp()public String toString()
toString in class org.eclipse.core.internal.jobs.InternalJobpublic final void wakeUp()
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).
sleep()public final void wakeUp(long delay)
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.
wakeUp in class org.eclipse.core.internal.jobs.InternalJobdelay - the number of milliseconds to delaysleep()public Job yieldRule(IProgressMonitor monitor)
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.
yieldRule in class org.eclipse.core.internal.jobs.InternalJobmonitor - a progress monitor, or null if progress
reporting is not desired. Cancellation attempts will be ignored.
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.getRule(),
isBlocking()
|
Eclipse Platform Release 3.7 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.