bundles/org.eclipse.platform.doc.isv/guide/runtime_jobs_progress.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html lang="en">
 <head>

 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

   <meta content="text/html; charset=ISO-8859-1"
  http-equiv="Content-Type">
   <meta content="text/css" http-equiv="Content-Style-Type">
   <link type="text/css" charset="ISO-8859-1" href="../book.css"
  rel="STYLESHEET">
   <title>Reporting progress</title>
   <link href="../book.css" type="text/css" rel="stylesheet">
 </head>
 <body bgcolor="#ffffff">
 <h3>
 Reporting progress</h3>
 <p>
 Long running jobs (those lasting more than a second) should report
 progress to the
 <b><a
  href="../reference/api/org/eclipse/core/runtime/IProgressMonitor.html">IProgressMonitor</a></b>
 that is passed to the job's <b>run</b> method. The workbench progress
 view will
 show all progress messages and units of completed work given to this
 monitor. </p>
 <p>The supplied progress monitor should also be used to check for
 cancellation requests made from the progress view. When a user (or
 plug-in using job API) attempts to cancel a job, the <b><a
  href="../reference/api/org/eclipse/core/runtime/IProgressMonitor.html">IProgressMonitor</a></b>
 method <b>isCanceled()</b> will return <tt>true</tt>. It is the job's
 responsibility to frequently
 check the cancellation status of a job and respond to a cancellation by
 exiting the <b>run</b> method as soon as possible once it detects a
 cancellation. The following <b>run</b> method reports progress
 and responds to job cancellation:
 </p>
 <pre>   public IStatus run(IProgressMonitor monitor) {
       final int ticks = 6000;
       monitor.<b>beginTask</b>("Doing some work", ticks);
       try {
          for (int i = 0; i &lt; ticks; i++) {
             if (monitor.<b>isCanceled</b>())
                return Status.CANCEL_STATUS;
             monitor.<b>subTask</b>("Processing tick #" + i);
             //... do some work ...
             monitor.<b>worked</b>(1);
          }
       } finally {
          monitor.<b>done</b>();
       }
       return Status.OK_STATUS;<br>   }
 </pre>
 <p>The <b>beginTask</b> method is used to name the task in the
 corresponding progress view and to
 establish the total amount of work to be done so that the view can
 compute progress. The
 <b>subTask</b> messages will appear as a child in the progress tree as
 work is done. The progress view will calculate and display a percent
 completion based on the amount of work
 reported in the <b>worked</b> calls.
 </p>
 <h3>Progress monitors and the UI</h3>
 <p>
 As you can see, the <b><a
  href="../reference/api/org/eclipse/core/runtime/IProgressMonitor.html">IProgressMonitor</a></b>
 class is designed with corresponding UI support in mind. The platform's
 UI plug-in provides support so that
 the workbench can show progress for jobs that are running. You can set
 up your jobs with this in mind, so that
 you can control how they are presented.<br>
 </p>
 <p>See <a href="workbench_jobs.htm">Workbench Concurrency Support</a>
 for a detailed look at the APIs available for showing progress for jobs.<br>
 </p>
 <h4>System jobs</h4>

 <p>What if your job is a low-level implementation detail that you don't
 want to show to users? You can flag your job as a <i>system job</i>. A
 system job is just like any other job, except the corresponding UI
 support will not set up a progress view or show any other UI
 affordances associated with running a job. If your job is not either
 directly initiated by a user, or a periodic task that can be configured
 by a user, then your job should be a system job. The protocol for
 setting a system job is simple:
 </p>
 <pre>   class TrivialJob extends Job {
       public TrivialJob() {
          super("Trivial Job");
          <b>setSystem(true)</b>;
       }
       ...
    }
 </pre>
 <p>The <b>setSystem</b> call must be made before the job is
 scheduled. An exception will be triggered if you attempt this call on a
 job that is currently waiting, sleeping, or running.
 </p>
 <h4>User jobs</h4>

 <p>If your job is a long running operation that is initiated by a user,
 then you should flag your job as a <i>user job</i>. A user job will
 appear in a modal progress dialog that provides a button
 for moving the dialog into the background. The workbench defines a user
 preference that controls whether
 these dialogs are ever modal. By defining your job as a user job, your
 progress feedback will
 automatically conform with the user preference for progress viewing.
 The protocol for setting a user job
 is similar:
 </p>
 <pre>   class TrivialJob extends Job {
       public TrivialJob() {
          super("Trivial Job");
          <b>setUser(true)</b>;
       }
       ...
    }
 </pre>
 <p>The <b>setUser</b> call must also be made before the job is scheduled.
 </p>

 <h3>Progress groups</h3>

 <p><i>Progress groups</i> are another mechanism that can be used to
 influence the way that a job is shown in the UI. When it is more
 appropriate to show the aggregate progress of several related jobs in
 the UI, a special
 <b><a
  href="../reference/api/org/eclipse/core/runtime/IProgressMonitor.html">IProgressMonitor</a></b>
 that represents
 a group of related jobs can be created. This monitor is created using <b><a
  href="../reference/api/org/eclipse/core/runtime/jobs/IJobManager.html">IJobManager</a></b>
 protocol. The following snippet shows how to create a progress group
 and associate it with a job.
 </p>
 <pre>   ...
    IJobManager jobMan = Job.getJobManager();
    myGroup = jobMan.createProgressGroup();
    job.setProgressGroup(myGroup, 600);  // specify the units of work the job needs to show.
    job.schedule()
    ...
 </pre>
 <p>The group facility allows plug-ins to break tasks into multiple
 jobs if needed, but to report them to the user as if
 they are a single task. The progress group monitor will handle the
 details for computing the percentage completion
 relative to all of the jobs in the group.
 </p>
 <p>A job must be placed into the progress group before it is scheduled.
 After a job finishes running, its reference to the progress group is
 lost. If the job is to be scheduled again, it must be set into the
 group
 once again before it is scheduled.</p>

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html lang="en">
	<head>

	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

	<meta content="text/html; charset=ISO-8859-1"
	http-equiv="Content-Type">
	<meta content="text/css" http-equiv="Content-Style-Type">
	<link type="text/css" charset="ISO-8859-1" href="../book.css"
	rel="STYLESHEET">
	<title>Reporting progress</title>
	<link href="../book.css" type="text/css" rel="stylesheet">
	</head>
	<body bgcolor="#ffffff">
	<h3>
	Reporting progress</h3>
	<p>
	Long running jobs (those lasting more than a second) should report
	progress to the
	<b><a
	href="../reference/api/org/eclipse/core/runtime/IProgressMonitor.html">IProgressMonitor</a></b>
	that is passed to the job's <b>run</b> method. The workbench progress
	view will
	show all progress messages and units of completed work given to this
	monitor. </p>
	<p>The supplied progress monitor should also be used to check for
	cancellation requests made from the progress view. When a user (or
	plug-in using job API) attempts to cancel a job, the <b><a
	href="../reference/api/org/eclipse/core/runtime/IProgressMonitor.html">IProgressMonitor</a></b>
	method <b>isCanceled()</b> will return <tt>true</tt>. It is the job's
	responsibility to frequently
	check the cancellation status of a job and respond to a cancellation by
	exiting the <b>run</b> method as soon as possible once it detects a
	cancellation. The following <b>run</b> method reports progress
	and responds to job cancellation:
	</p>
	<pre> public IStatus run(IProgressMonitor monitor) {
	final int ticks = 6000;
	monitor.<b>beginTask</b>("Doing some work", ticks);
	try {
	for (int i = 0; i < ticks; i++) {
	if (monitor.<b>isCanceled</b>())
	return Status.CANCEL_STATUS;
	monitor.<b>subTask</b>("Processing tick #" + i);
	//... do some work ...
	monitor.<b>worked</b>(1);
	}
	} finally {
	monitor.<b>done</b>();
	}
	return Status.OK_STATUS;<br> }
	</pre>
	<p>The <b>beginTask</b> method is used to name the task in the
	corresponding progress view and to
	establish the total amount of work to be done so that the view can
	compute progress. The
	<b>subTask</b> messages will appear as a child in the progress tree as
	work is done. The progress view will calculate and display a percent
	completion based on the amount of work
	reported in the <b>worked</b> calls.
	</p>
	<h3>Progress monitors and the UI</h3>
	<p>
	As you can see, the <b><a
	href="../reference/api/org/eclipse/core/runtime/IProgressMonitor.html">IProgressMonitor</a></b>
	class is designed with corresponding UI support in mind. The platform's
	UI plug-in provides support so that
	the workbench can show progress for jobs that are running. You can set
	up your jobs with this in mind, so that
	you can control how they are presented.<br>
	</p>
	<p>See <a href="workbench_jobs.htm">Workbench Concurrency Support</a>
	for a detailed look at the APIs available for showing progress for jobs.<br>
	</p>
	<h4>System jobs</h4>

	<p>What if your job is a low-level implementation detail that you don't
	want to show to users? You can flag your job as a <i>system job</i>. A
	system job is just like any other job, except the corresponding UI
	support will not set up a progress view or show any other UI
	affordances associated with running a job. If your job is not either
	directly initiated by a user, or a periodic task that can be configured
	by a user, then your job should be a system job. The protocol for
	setting a system job is simple:
	</p>
	<pre> class TrivialJob extends Job {
	public TrivialJob() {
	super("Trivial Job");
	<b>setSystem(true)</b>;
	}
	...
	}
	</pre>
	<p>The <b>setSystem</b> call must be made before the job is
	scheduled. An exception will be triggered if you attempt this call on a
	job that is currently waiting, sleeping, or running.
	</p>
	<h4>User jobs</h4>

	<p>If your job is a long running operation that is initiated by a user,
	then you should flag your job as a <i>user job</i>. A user job will
	appear in a modal progress dialog that provides a button
	for moving the dialog into the background. The workbench defines a user
	preference that controls whether
	these dialogs are ever modal. By defining your job as a user job, your
	progress feedback will
	automatically conform with the user preference for progress viewing.
	The protocol for setting a user job
	is similar:
	</p>
	<pre> class TrivialJob extends Job {
	public TrivialJob() {
	super("Trivial Job");
	<b>setUser(true)</b>;
	}
	...
	}
	</pre>
	<p>The <b>setUser</b> call must also be made before the job is scheduled.
	</p>

	<h3>Progress groups</h3>

	<p><i>Progress groups</i> are another mechanism that can be used to
	influence the way that a job is shown in the UI. When it is more
	appropriate to show the aggregate progress of several related jobs in
	the UI, a special
	<b><a
	href="../reference/api/org/eclipse/core/runtime/IProgressMonitor.html">IProgressMonitor</a></b>
	that represents
	a group of related jobs can be created. This monitor is created using <b><a
	href="../reference/api/org/eclipse/core/runtime/jobs/IJobManager.html">IJobManager</a></b>
	protocol. The following snippet shows how to create a progress group
	and associate it with a job.
	</p>
	<pre> ...
	IJobManager jobMan = Job.getJobManager();
	myGroup = jobMan.createProgressGroup();
	job.setProgressGroup(myGroup, 600); // specify the units of work the job needs to show.
	job.schedule()
	...
	</pre>
	<p>The group facility allows plug-ins to break tasks into multiple
	jobs if needed, but to report them to the user as if
	they are a single task. The progress group monitor will handle the
	details for computing the percentage completion
	relative to all of the jobs in the group.
	</p>
	<p>A job must be placed into the progress group before it is scheduled.
	After a job finishes running, its reference to the progress group is
	lost. If the job is to be scheduled again, it must be set into the
	group
	once again before it is scheduled.</p>

	</body>
	</html>