KickJava   Java API By Example, From Geeks To Geeks.

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


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.runtime.*;
14
15 /**
16  * The progress provider supplies the job manager with progress monitors for
17  * running jobs. There can only be one progress provider at any given time.
18  * <p>
19  * This class is intended for use by the currently executing Eclipse application.
20  * Plug-ins outside the currently running application should not reference or
21  * subclass this class.
22  * </p>
23  *
24  * @see IJobManager#setProgressProvider(ProgressProvider)
25  * @since 3.0
26  */
27 public abstract class ProgressProvider {
28     /**
29      * Provides a new progress monitor instance to be used by the given job.
30      * This method is called prior to running any job that does not belong to a
31      * progress group. The returned monitor will be supplied to the job's
32      * <code>run</code> method.
33      *
34      * @see #createProgressGroup()
35      * @see Job#setProgressGroup(IProgressMonitor, int)
36      * @param job the job to create a progress monitor for
37      * @return a progress monitor, or <code>null</code> if no progress monitoring
38      * is needed.
39      */
40     public abstract IProgressMonitor createMonitor(Job job);
41
42     /**
43      * Returns a progress monitor that can be used to provide
44      * aggregated progress feedback on a set of running jobs.
45      * This method implements <code>IJobManager.createProgressGroup</code>,
46      * and must obey all rules specified in that contract.
47      * <p>
48      * This default implementation returns a new
49      * <code>NullProgressMonitor</code> Subclasses may override.
50      *
51      * @see IJobManager#createProgressGroup()
52      * @return a progress monitor
53      */
54     public IProgressMonitor createProgressGroup() {
55         return new NullProgressMonitor();
56     }
57
58     /**
59      * Returns a progress monitor that can be used by a running job
60      * to report progress in the context of a progress group. This method
61      * implements <code>Job.setProgressGroup</code>. One of the
62      * two <code>createMonitor</code> methods will be invoked
63      * prior to each execution of a job, depending on whether a progress
64      * group was specified for the job.
65      * <p>
66      * The provided monitor must be a monitor returned by the method
67      * <code>createProgressGroup</code>. This method is responsible
68      * for asserting this and throwing an appropriate runtime exception
69      * if an invalid monitor is provided.
70      * <p>
71      * This default implementation returns a new
72      * <code>SubProgressMonitor</code>. Subclasses may override.
73      *
74      * @see IJobManager#createProgressGroup()
75      * @see Job#setProgressGroup(IProgressMonitor, int)
76      * @param job the job to create a progress monitor for
77      * @param group the progress monitor group that this job belongs to
78      * @param ticks the number of ticks of work for the progress monitor
79      * @return a progress monitor, or <code>null</code> if no progress monitoring
80      * is needed.
81      */
82     public IProgressMonitor createMonitor(Job job, IProgressMonitor group, int ticks) {
83         return new SubProgressMonitor(group, ticks);
84     }
85
86     /**
87      * Returns a progress monitor to use when none has been provided
88      * by the client running the job.
89      * <p>
90      * This default implementation returns a new
91      * <code>NullProgressMonitor</code> Subclasses may override.
92      *
93      * @return a progress monitor
94      */
95     public IProgressMonitor getDefaultMonitor() {
96         return new NullProgressMonitor();
97     }
98 }
99
Popular Tags