KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > runtime > jobs > Job


1 /*******************************************************************************
2  * Copyright (c) 2003, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.core.runtime.jobs;
12
13 import org.eclipse.core.internal.jobs.InternalJob;
14 import org.eclipse.core.internal.jobs.JobManager;
15 import org.eclipse.core.runtime.*;
16
17 /**
18  * Jobs are units of runnable work that can be scheduled to be run with the job
19  * manager. Once a job has completed, it can be scheduled to run again (jobs are
20  * reusable).
21  * <p>
22  * Jobs have a state that indicates what they are currently doing. When constructed,
23  * jobs start with a state value of <code>NONE</code>. When a job is scheduled
24  * to be run, it moves into the <code>WAITING</code> state. When a job starts
25  * running, it moves into the <code>RUNNING</code> state. When execution finishes
26  * (either normally or through cancelation), the state changes back to
27  * <code>NONE</code>.
28  * </p><p>
29  * A job can also be in the <code>SLEEPING</code> state. This happens if a user
30  * calls Job.sleep() on a waiting job, or if a job is scheduled to run after a specified
31  * delay. Only jobs in the <code>WAITING</code> state can be put to sleep.
32  * Sleeping jobs can be woken at any time using Job.wakeUp(), which will put the
33  * job back into the <code>WAITING</code> state.
34  * </p><p>
35  * Jobs can be assigned a priority that is used as a hint about how the job should
36  * be scheduled. There is no guarantee that jobs of one priority will be run before
37  * all jobs of lower priority. The javadoc for the various priority constants provide
38  * more detail about what each priority means. By default, jobs start in the
39  * <code>LONG</code> priority class.
40  *
41  * @see IJobManager
42  * @since 3.0
43  */
44 public abstract class Job extends InternalJob implements IAdaptable {
45
46     /**
47      * Job status return value that is used to indicate asynchronous job completion.
48      * @see Job#run(IProgressMonitor)
49      * @see Job#done(IStatus)
50      */
51     public static final IStatus ASYNC_FINISH = new Status(IStatus.OK, JobManager.PI_JOBS, 1, "", null);//$NON-NLS-1$
52
53     /* Job priorities */
54     /**
55      * Job priority constant (value 10) for interactive jobs.
56      * Interactive jobs generally have priority over all other jobs.
57      * Interactive jobs should be either fast running or very low on CPU
58      * usage to avoid blocking other interactive jobs from running.
59      *
60      * @see #getPriority()
61      * @see #setPriority(int)
62      * @see #run(IProgressMonitor)
63      */
64     public static final int INTERACTIVE = 10;
65     /**
66      * Job priority constant (value 20) for short background jobs.
67      * Short background jobs are jobs that typically complete within a second,
68      * but may take longer in some cases. Short jobs are given priority
69      * over all other jobs except interactive jobs.
70      *
71      * @see #getPriority()
72      * @see #setPriority(int)
73      * @see #run(IProgressMonitor)
74      */
75     public static final int SHORT = 20;
76     /**
77      * Job priority constant (value 30) for long-running background jobs.
78      *
79      * @see #getPriority()
80      * @see #setPriority(int)
81      * @see #run(IProgressMonitor)
82      */
83     public static final int LONG = 30;
84     /**
85      * Job priority constant (value 40) for build jobs. Build jobs are
86      * generally run after all other background jobs complete.
87      *
88      * @see #getPriority()
89      * @see #setPriority(int)
90      * @see #run(IProgressMonitor)
91      */
92     public static final int BUILD = 40;
93
94     /**
95      * Job priority constant (value 50) for decoration jobs.
96      * Decoration jobs have lowest priority. Decoration jobs generally
97      * compute extra information that the user may be interested in seeing
98      * but is generally not waiting for.
99      *
100      * @see #getPriority()
101      * @see #setPriority(int)
102      * @see #run(IProgressMonitor)
103      */
104     public static final int DECORATE = 50;
105     /**
106      * Job state code (value 0) indicating that a job is not
107      * currently sleeping, waiting, or running (i.e., the job manager doesn't know
108      * anything about the job).
109      *
110      * @see #getState()
111      */
112     public static final int NONE = 0;
113     /**
114      * Job state code (value 1) indicating that a job is sleeping.
115      *
116      * @see #run(IProgressMonitor)
117      * @see #getState()
118      */
119     public static final int SLEEPING = 0x01;
120     /**
121      * Job state code (value 2) indicating that a job is waiting to be run.
122      *
123      * @see #getState()
124      */
125     public static final int WAITING = 0x02;
126     /**
127      * Job state code (value 4) indicating that a job is currently running
128      *
129      * @see #getState()
130      */
131     public static final int RUNNING = 0x04;
132
133     /**
134      * Returns the job manager.
135      *
136      * @return the job manager
137      * @since org.eclipse.core.jobs 3.2
138      */
139     public static final IJobManager getJobManager() {
140         return manager;
141     }
142
143     /**
144      * Creates a new job with the specified name. The job name is a human-readable
145      * value that is displayed to users. The name does not need to be unique, but it
146      * must not be <code>null</code>.
147      *
148      * @param name the name of the job.
149      */
150     public Job(String JavaDoc name) {
151         super(name);
152     }
153
154     /**
155      * Registers a job listener with this job
156      * Has no effect if an identical listener is already registered.
157      *
158      * @param listener the listener to be added.
159      */
160     public final void addJobChangeListener(IJobChangeListener listener) {
161         super.addJobChangeListener(listener);
162     }
163
164     /**
165      * Returns whether this job belongs to the given family. Job families are
166      * represented as objects that are not interpreted or specified in any way
167      * by the job manager. Thus, a job can choose to belong to any number of
168      * families.
169      * <p>
170      * Clients may override this method. This default implementation always returns
171      * <code>false</code>. Overriding implementations must return <code>false</code>
172      * for families they do not recognize.
173      * </p>
174      *
175      * @param family the job family identifier
176      * @return <code>true</code> if this job belongs to the given family, and
177      * <code>false</code> otherwise.
178      */
179     public boolean belongsTo(Object JavaDoc family) {
180         return false;
181     }
182
183     /**
184      * Stops the job. If the job is currently waiting,
185      * it will be removed from the queue. If the job is sleeping,
186      * it will be discarded without having a chance to resume and its sleeping state
187      * will be cleared. If the job is currently executing, it will be asked to
188      * stop but there is no guarantee that it will do so.
189      *
190      * @return <code>false</code> if the job is currently running (and thus may not
191      * respond to cancelation), and <code>true</code> in all other cases.
192      */
193     public final boolean cancel() {
194         return super.cancel();
195     }
196     
197     /**
198      * A hook method indicating that this job is running and {@link #cancel()}
199      * is being called for the first time.
200      * <p>
201      * Subclasses may override this method to perform additional work when
202      * a cancelation request is made. This default implementation does nothing
203      * @since 3.3
204      */
205     protected void canceling() {
206         //default implementation does nothing
207 }
208
209     /**
210      * Jobs that complete their execution asynchronously must indicate when they
211      * are finished by calling this method. This method must not be called by
212      * a job that has not indicated that it is executing asynchronously.
213      * <p>
214      * This method must not be called from within the scope of a job's <code>run</code>
215      * method. Jobs should normally indicate completion by returning an appropriate
216      * status from the <code>run</code> method. Jobs that return a status of
217      * <code>ASYNC_FINISH</code> from their run method must later call
218      * <code>done</code> to indicate completion.
219      *
220      * @param result a status object indicating the result of the job's execution.
221      * @see #ASYNC_FINISH
222      * @see #run(IProgressMonitor)
223      */
224     public final void done(IStatus result) {
225         super.done(result);
226     }
227
228     /**
229      * Returns the human readable name of this job. The name is never
230      * <code>null</code>.
231      *
232      * @return the name of this job
233      */
234     public final String JavaDoc getName() {
235         return super.getName();
236     }
237
238     /**
239      * Returns the priority of this job. The priority is used as a hint when the job
240      * is scheduled to be run.
241      *
242      * @return the priority of the job. One of INTERACTIVE, SHORT, LONG, BUILD,
243      * or DECORATE.
244      */
245     public final int getPriority() {
246         return super.getPriority();
247     }
248
249     /**
250      * Returns the value of the property of this job identified by the given key,
251      * or <code>null</code> if this job has no such property.
252      *
253      * @param key the name of the property
254      * @return the value of the property,
255      * or <code>null</code> if this job has no such property
256      * @see #setProperty(QualifiedName, Object)
257      */
258     public final Object JavaDoc getProperty(QualifiedName key) {
259         return super.getProperty(key);
260     }
261
262     /**
263      * Returns the result of this job's last run.
264      *
265      * @return the result of this job's last run, or <code>null</code> if this
266      * job has never finished running.
267      */
268     public final IStatus getResult() {
269         return super.getResult();
270     }
271
272     /**
273      * Returns the scheduling rule for this job. Returns <code>null</code> if this job has no
274      * scheduling rule.
275      *
276      * @return the scheduling rule for this job, or <code>null</code>.
277      * @see ISchedulingRule
278      * @see #setRule(ISchedulingRule)
279      */
280     public final ISchedulingRule getRule() {
281         return super.getRule();
282     }
283
284     /**
285      * Returns the state of the job. Result will be one of:
286      * <ul>
287      * <li><code>Job.RUNNING</code> - if the job is currently running.</li>
288      * <li><code>Job.WAITING</code> - if the job is waiting to be run.</li>
289      * <li><code>Job.SLEEPING</code> - if the job is sleeping.</li>
290      * <li><code>Job.NONE</code> - in all other cases.</li>
291      * </ul>
292      * <p>
293      * Note that job state is inherently volatile, and in most cases clients
294      * cannot rely on the result of this method being valid by the time the
295      * result is obtained. For example, if <tt>getState</tt> returns
296      * <tt>RUNNING</tt>, the job may have actually completed by the
297      * time the <tt>getState</tt> method returns. All clients can infer from
298      * invoking this method is that the job was recently in the returned state.
299      *
300      * @return the job state
301      */
302     public final int getState() {
303         return super.getState();
304     }
305
306     /**
307      * Returns the thread that this job is currently running in.
308      *
309      * @return the thread this job is running in, or <code>null</code>
310      * if this job is not running or the thread is unknown.
311      */
312     public final Thread JavaDoc getThread() {
313         return super.getThread();
314     }
315
316     /**
317      * Returns whether this job is blocking a higher priority non-system job from
318      * starting due to a conflicting scheduling rule. Returns <code>false</code>
319      * if this job is not running, or is not blocking a higher priority non-system job.
320      *
321      * @return <code>true</code> if this job is blocking a higher priority non-system
322      * job, and <code>false</code> otherwise.
323      * @see #getRule()
324      * @see #isSystem()
325      */
326     public final boolean isBlocking() {
327         return super.isBlocking();
328     }
329
330     /**
331      * Returns whether this job is a system job. System jobs are typically not
332      * revealed to users in any UI presentation of jobs. Other than their UI presentation,
333      * system jobs act exactly like other jobs. If this value is not explicitly set, jobs
334      * are treated as non-system jobs. The default value is <code>false</code>.
335      *
336      * @return <code>true</code> if this job is a system job, and
337      * <code>false</code> otherwise.
338      * @see #setSystem(boolean)
339      */
340     public final boolean isSystem() {
341         return super.isSystem();
342     }
343
344     /**
345      * Returns whether this job has been directly initiated by a UI end user.
346      * These jobs may be presented differently in the UI. The default value
347      * is <code>false</code>.
348      *
349      * @return <code>true</code> if this job is a user-initiated job, and
350      * <code>false</code> otherwise.
351      * @see #setUser(boolean)
352      */
353     public final boolean isUser() {
354         return super.isUser();
355     }
356
357     /**
358      * Waits until this job is finished. This method will block the calling thread until the
359      * job has finished executing, or until this thread has been interrupted. If the job
360      * has not been scheduled, this method returns immediately. A job must not
361      * be joined from within the scope of its run method.
362      * <p>
363      * If this method is called on a job that reschedules itself from within the
364      * <tt>run</tt> method, the join will return at the end of the first execution.
365      * In other words, join will return the first time this job exits the
366      * {@link #RUNNING} state, or as soon as this job enters the {@link #NONE} state.
367      * </p>
368      * <p>
369      * If this method is called while the job manager is suspended, this job
370      * will only be joined if it is already running; if this job is waiting or sleeping,
371      * this method returns immediately.
372      * </p>
373      * <p>
374      * Note that there is a deadlock risk when using join. If the calling thread owns
375      * a lock or object monitor that the joined thread is waiting for, deadlock
376      * will occur.
377      * </p>
378      *
379      * @exception InterruptedException if this thread is interrupted while waiting
380      * @see ILock
381      * @see IJobManager#suspend()
382      */
383     public final void join() throws InterruptedException JavaDoc {
384         super.join();
385     }
386
387     /**
388      * Removes a job listener from this job.
389      * Has no effect if an identical listener is not already registered.
390      *
391      * @param listener the listener to be removed
392      */
393     public final void removeJobChangeListener(IJobChangeListener listener) {
394         super.removeJobChangeListener(listener);
395     }
396
397     /**
398      * Executes this job. Returns the result of the execution.
399      * <p>
400      * The provided monitor can be used to report progress and respond to
401      * cancellation. If the progress monitor has been canceled, the job
402      * should finish its execution at the earliest convenience and return a result
403      * status of severity {@link IStatus#CANCEL}. The singleton
404      * cancel status {@link Status#CANCEL_STATUS} can be used for
405      * this purpose. The monitor is only valid for the duration of the invocation
406      * of this method.
407      * <p>
408      * This method must not be called directly by clients. Clients should call
409      * <code>schedule</code>, which will in turn cause this method to be called.
410      * <p>
411      * Jobs can optionally finish their execution asynchronously (in another thread) by
412      * returning a result status of {@link #ASYNC_FINISH}. Jobs that finish
413      * asynchronously <b>must</b> specify the execution thread by calling
414      * <code>setThread</code>, and must indicate when they are finished by calling
415      * the method <code>done</code>.
416      *
417      * @param monitor the monitor to be used for reporting progress and
418      * responding to cancelation. The monitor is never <code>null</code>
419      * @return resulting status of the run. The result must not be <code>null</code>
420      * @see #ASYNC_FINISH
421      * @see #done(IStatus)
422      */
423     protected abstract IStatus run(IProgressMonitor monitor);
424
425     /**
426      * Schedules this job to be run. The job is added to a queue of waiting
427      * jobs, and will be run when it arrives at the beginning of the queue.
428      * <p>
429      * This is a convenience method, fully equivalent to
430      * <code>schedule(0L)</code>.
431      * </p>
432      * @see #schedule(long)
433      */
434     public final void schedule() {
435         super.schedule(0L);
436     }
437
438     /**
439      * Schedules this job to be run after a specified delay. The job is put in the
440      * {@link #SLEEPING} state until the specified delay has elapsed, after which
441      * the job is added to a queue of {@link #WAITING} jobs. Once the job arrives
442      * at the beginning of the queue, it will be run at the first available opportunity.
443      * </p><p>
444      * Jobs of equal priority and <code>delay</code> with conflicting scheduling
445      * rules are guaranteed to run in the order they are scheduled. No guarantees
446      * are made about the relative execution order of jobs with unrelated or
447      * <code>null</code> scheduling rules, or different priorities.
448      * <p>
449      * If this job is currently running, it will be rescheduled with the specified
450      * delay as soon as it finishes. If this method is called multiple times
451      * while the job is running, the job will still only be rescheduled once,
452      * with the most recent delay value that was provided.
453      * </p><p>
454      * Scheduling a job that is waiting or sleeping has no effect.
455      * </p>
456      *
457      * @param delay a time delay in milliseconds before the job should run
458      * @see ISchedulingRule
459      */
460     public final void schedule(long delay) {
461         super.schedule(delay);
462     }
463
464     /**
465      * Changes the name of this job. If the job is currently running, waiting,
466      * or sleeping, the new job name may not take effect until the next time the
467      * job is scheduled.
468      * <p>
469      * The job name is a human-readable value that is displayed to users. The name
470      * does not need to be unique, but it must not be <code>null</code>.
471      *
472      * @param name the name of the job.
473      */
474     public final void setName(String JavaDoc name) {
475         super.setName(name);
476     }
477
478     /**
479      * Sets the priority of the job. This will not affect the execution of
480      * a running job, but it will affect how the job is scheduled while
481      * it is waiting to be run.
482      *
483      * @param priority the new job priority. One of
484      * INTERACTIVE, SHORT, LONG, BUILD, or DECORATE.
485      */
486     public final void setPriority(int priority) {
487         super.setPriority(priority);
488     }
489
490     /**
491      * Associates this job with a progress group. Progress feedback
492      * on this job's next execution will be displayed together with other
493      * jobs in that group. The provided monitor must be a monitor
494      * created by the method <tt>IJobManager.createProgressGroup</tt>
495      * and must have at least <code>ticks</code> units of available work.
496      * <p>
497      * The progress group must be set before the job is scheduled.
498      * The group will be used only for a single invocation of the job's
499      * <tt>run</tt> method, after which any association of this job to the
500      * group will be lost.
501      *
502      * @see IJobManager#createProgressGroup()
503      * @param group The progress group to use for this job
504      * @param ticks the number of work ticks allocated from the
505      * parent monitor, or {@link IProgressMonitor#UNKNOWN}
506      */
507     public final void setProgressGroup(IProgressMonitor group, int ticks) {
508         super.setProgressGroup(group, ticks);
509     }
510
511     /**
512      * Sets the value of the property of this job identified
513      * by the given key. If the supplied value is <code>null</code>,
514      * the property is removed from this resource.
515      * <p>
516      * Properties are intended to be used as a caching mechanism
517      * by ISV plug-ins. They allow key-object associations to be stored with
518      * a job instance. These key-value associations are maintained in
519      * memory (at all times), and the information is never discarded automatically.
520      * </p><p>
521      * The qualifier part of the property name must be the unique identifier
522      * of the declaring plug-in (e.g. <code>"com.example.plugin"</code>).
523      * </p>
524      *
525      * @param key the qualified name of the property
526      * @param value the value of the property,
527      * or <code>null</code> if the property is to be removed
528      * @see #getProperty(QualifiedName)
529      */
530     public void setProperty(QualifiedName key, Object JavaDoc value) {
531         super.setProperty(key, value);
532     }
533
534     /**
535      * Sets the scheduling rule to be used when scheduling this job. This method
536      * must be called before the job is scheduled.
537      *
538      * @param rule the new scheduling rule, or <code>null</code> if the job
539      * should have no scheduling rule
540      * @see #getRule()
541      */
542     public final void setRule(ISchedulingRule rule) {
543         super.setRule(rule);
544     }
545
546     /**
547      * Sets whether or not this job is a system job. System jobs are typically not
548      * revealed to users in any UI presentation of jobs. Other than their UI presentation,
549      * system jobs act exactly like other jobs. If this value is not explicitly set, jobs
550      * are treated as non-system jobs. This method must be called before the job
551      * is scheduled.
552      *
553      * @param value <code>true</code> if this job should be a system job, and
554      * <code>false</code> otherwise.
555      * @see #isSystem()
556      */
557     public final void setSystem(boolean value) {
558         super.setSystem(value);
559     }
560
561     /**
562      * Sets whether or not this job has been directly initiated by a UI end user.
563      * These jobs may be presented differently in the UI. This method must be
564      * called before the job is scheduled.
565      *
566      * @param value <code>true</code> if this job is a user-initiated job, and
567      * <code>false</code> otherwise.
568      * @see #isUser()
569      */
570     public final void setUser(boolean value) {
571         super.setUser(value);
572     }
573
574     /**
575      * Sets the thread that this job is currently running in, or <code>null</code>
576      * if this job is not running or the thread is unknown.
577      * <p>
578      * Jobs that use the {@link #ASYNC_FINISH} return code should tell
579      * the job what thread it is running in. This is used to prevent deadlocks.
580      *
581      * @param thread the thread that this job is running in.
582      *
583      * @see #ASYNC_FINISH
584      * @see #run(IProgressMonitor)
585      */
586     public final void setThread(Thread JavaDoc thread) {
587         super.setThread(thread);
588     }
589
590     /**
591      * Returns whether this job should be run.
592      * If <code>false</code> is returned, this job will be discarded by the job manager
593      * without running.
594      * <p>
595      * This method is called immediately prior to calling the job's
596      * run method, so it can be used for last minute pre-condition checking before
597      * a job is run. This method must not attempt to schedule or change the
598      * state of any other job.
599      * </p><p>
600      * Clients may override this method. This default implementation always returns
601      * <code>true</code>.
602      * </p>
603      *
604      * @return <code>true</code> if this job should be run
605      * and <code>false</code> otherwise
606      */
607     public boolean shouldRun() {
608         return true;
609     }
610
611     /**
612      * Returns whether this job should be scheduled.
613      * If <code>false</code> is returned, this job will be discarded by the job manager
614      * without being added to the queue.
615      * <p>
616      * This method is called immediately prior to adding the job to the waiting job
617      * queue.,so it can be used for last minute pre-condition checking before
618      * a job is scheduled.
619      * </p><p>
620      * Clients may override this method. This default implementation always returns
621      * <code>true</code>.
622      * </p>
623      *
624      * @return <code>true</code> if the job manager should schedule this job
625      * and <code>false</code> otherwise
626      */
627     public boolean shouldSchedule() {
628         return true;
629     }
630
631     /**
632      * Requests that this job be suspended. If the job is currently waiting to be run, it
633      * will be removed from the queue move into the {@link #SLEEPING} state.
634      * The job will remain asleep until either resumed or canceled. If this job is not
635      * currently waiting to be run, this method has no effect.
636      * <p>
637      * Sleeping jobs can be resumed using <code>wakeUp</code>.
638      *
639      * @return <code>false</code> if the job is currently running (and thus cannot
640      * be put to sleep), and <code>true</code> in all other cases
641      * @see #wakeUp()
642      */
643     public final boolean sleep() {
644         return super.sleep();
645     }
646
647     /**
648      * Puts this job immediately into the {@link #WAITING} state so that it is
649      * eligible for immediate execution. If this job is not currently sleeping,
650      * the request is ignored.
651      * <p>
652      * This is a convenience method, fully equivalent to
653      * <code>wakeUp(0L)</code>.
654      * </p>
655      * @see #sleep()
656      */
657     public final void wakeUp() {
658         super.wakeUp(0L);
659     }
660
661     /**
662      * Puts this job back into the {@link #WAITING} state after
663      * the specified delay. This is equivalent to canceling the sleeping job and
664      * rescheduling with the given delay. If this job is not currently sleeping,
665      * the request is ignored.
666      *
667      * @param delay the number of milliseconds to delay
668      * @see #sleep()
669      */
670     public final void wakeUp(long delay) {
671         super.wakeUp(delay);
672     }
673 }
674
Popular Tags