http://www.eclipse.org/platform: Eclipse Jobs Mechanism (Eclipse Foundation) 
Copyright (c) 2003, 2012 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation

/*******************************************************************************
 * Copyright (c) 2003, 2012 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.runtime.jobs;

import org.eclipse.core.runtime.*;


The progress provider supplies the job manager with progress monitors for
running jobs.  There can only be one progress provider at any given time.


This class is intended for use by the currently executing Eclipse application.
Plug-ins outside the currently running application should not reference or
subclass this class.



See Also:
  • setProgressProvider.setProgressProvider(ProgressProvider)
Since:3.0
/**
 * The progress provider supplies the job manager with progress monitors for
 * running jobs.  There can only be one progress provider at any given time.
 * <p>
 * This class is intended for use by the currently executing Eclipse application.
 * Plug-ins outside the currently running application should not reference or
 * subclass this class.
 * </p>
 *
 * @see IJobManager#setProgressProvider(ProgressProvider)
 * @since 3.0
 */
public abstract class ProgressProvider {
	
Provides a new progress monitor instance to be used by the given job.
This method is called prior to running any job that does not belong to a
progress group. The returned monitor will be supplied to the job's
run method.

Params:
  • job – the job to create a progress monitor for
See Also:
Returns:a progress monitor, or null if no progress monitoring
is needed.
/**
	 * Provides a new progress monitor instance to be used by the given job.
	 * This method is called prior to running any job that does not belong to a
	 * progress group. The returned monitor will be supplied to the job's
	 * <code>run</code> method.
	 *
	 * @see #createProgressGroup()
	 * @see Job#setProgressGroup(IProgressMonitor, int)
	 * @param job the job to create a progress monitor for
	 * @return a progress monitor, or <code>null</code> if no progress monitoring
	 * is needed.
	 */
	public abstract IProgressMonitor createMonitor(Job job);

	
Returns a progress monitor that can be used to provide aggregated progress
feedback on a set of running jobs. This method implements
IJobManager.createProgressGroup, and must obey all rules
specified in that contract.


This default implementation returns a new NullProgressMonitor.
Subclasses may override.

See Also:
  • createProgressGroup.createProgressGroup()
Returns:a progress monitor
/**
	 * Returns a progress monitor that can be used to provide aggregated progress
	 * feedback on a set of running jobs. This method implements
	 * <code>IJobManager.createProgressGroup</code>, and must obey all rules
	 * specified in that contract.
	 * <p>
	 * This default implementation returns a new <code>NullProgressMonitor</code>.
	 * Subclasses may override.
	 *
	 * @see IJobManager#createProgressGroup()
	 * @return a progress monitor
	 */
	public IProgressMonitor createProgressGroup() {
		return new NullProgressMonitor();
	}

	
Returns a progress monitor that can be used by a running job to report
progress in the context of a progress group. One of the two
createMonitor methods will be invoked prior to each execution of
a job, depending on whether a progress group was specified for the job.


The provided monitor must be a monitor returned by the method
createProgressGroup. This method is responsible for asserting
this and throwing an appropriate runtime exception if an invalid monitor is
provided.


This default implementation returns a new SubMonitor. Subclasses
may override.

Params:
  • job –   the job to create a progress monitor for
  • group – the progress monitor group that this job belongs to
  • ticks – the number of ticks of work for the progress monitor
See Also:
Returns:a progress monitor, or null if no progress monitoring is
        needed.
/**
	 * Returns a progress monitor that can be used by a running job to report
	 * progress in the context of a progress group. One of the two
	 * <code>createMonitor</code> methods will be invoked prior to each execution of
	 * a job, depending on whether a progress group was specified for the job.
	 * <p>
	 * The provided monitor must be a monitor returned by the method
	 * <code>createProgressGroup</code>. This method is responsible for asserting
	 * this and throwing an appropriate runtime exception if an invalid monitor is
	 * provided.
	 * <p>
	 * This default implementation returns a new <code>SubMonitor</code>. Subclasses
	 * may override.
	 *
	 * @see IJobManager#createProgressGroup()
	 * @see Job#setProgressGroup(IProgressMonitor, int)
	 * @param job   the job to create a progress monitor for
	 * @param group the progress monitor group that this job belongs to
	 * @param ticks the number of ticks of work for the progress monitor
	 * @return a progress monitor, or <code>null</code> if no progress monitoring is
	 *         needed.
	 */
	public IProgressMonitor createMonitor(Job job, IProgressMonitor group, int ticks) {
		return SubMonitor.convert(group, ticks);
	}

	
Returns a progress monitor to use when none has been provided
by the client running the job.


This default implementation returns a new
NullProgressMonitor  Subclasses may override.

Returns:a progress monitor
/**
	 * Returns a progress monitor to use when none has been provided
	 * by the client running the job.
	 * <p>
	 * This default implementation returns a new
	 * <code>NullProgressMonitor</code>  Subclasses may override.
	 *
	 * @return a progress monitor
	 */
	public IProgressMonitor getDefaultMonitor() {
		return new NullProgressMonitor();
	}
}