blob: 9b0718427f8723fcc1adf909a6a54293fcbea4fd [file] [log] [blame]
<html>
<!--
NO NO NO NO NO!
==============> DO NOT EDIT ME! <==============
AUTOMATICALLY GENERATED FROM APICHANGES.XML, DO NOT EDIT
SEE CHANGEME/apichanges.xml
-->
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Change History for the Progress API</title>
<link rel="stylesheet" href="prose.css" type="text/css">
</head>
<body>
<p class="overviewlink">
<a href="overview-summary.html" shape="rect">Overview</a>
</p>
<h1>Introduction</h1>
<p>This document lists changes made to the Progress API/SPI.</p>
<!-- The actual lists of changes, as summaries and details: -->
<hr>
<h1>
<a name="list-all-apis">Index of APIs</a>
</h1>
<ul>
<li>
<a href="#progress_api">Progress API</a>
</li>
</ul>
<h1>
<a name="incompat-by-date">Incompatible changes by date</a>
</h1>
<p>Fuller descriptions of all changes can be found below (follow links).</p>
<p>Not all deprecations are listed here, assuming that the deprecated
APIs continue to essentially work. For a full deprecation list, please
consult the
<a href="deprecated-list.html">Javadoc</a>.</p>
<ul>
<li>(Sep 18 '14) <a href="#swingSplit">
Swing dependencies separated into a new module.
</a>
</li>
</ul>
<h1>
<a name="all-by-date">All changes by date</a>
</h1>
<ul>
<li>(Feb 4 '15) <a href="#progresshandle.time">
Allow tracking of stale handles
</a>
</li>
<li>(Dec 7 '14) <a href="#taskmodel.sync">
Allow to synchronize with Controller's event delivery.
</a>
</li>
<li>(Sep 18 '14) <a href="#swingSplit">
Swing dependencies separated into a new module.
</a>
</li>
<li>(Aug 28 '12) <a href="#customDialogs"><code>ProgressUtils</code> class with <code>runOffEventThreadWithCustomDialogContent</code> and <code>runOffEventThreadWithProgressDialog</code> methods were added.</a>
</li>
<li>(Feb 8 '10) <a href="#modalRunMethods">Modal progress dialogs</a>
</li>
<li>(Jan 8 '10) <a href="#spi">SPI added</a>
</li>
<li>(Nov 2 '09) <a href="#ProgressUtils"><code>ProgressUtils</code> class with <code>runOffEventDispatchThread</code> methods was added.</a>
</li>
<li>(Oct 23 '06) <a href="#suspend">Add <code>ProgressHandle.suspend(String)</code> method for visual suspend of a running task.</a>
</li>
<li>(Aug 3 '06) <a href="#issue-58889">Add methods to create main/detail labels for an custom placed progress component.</a>
</li>
<li>(Jul 24 '06) <a href="#issue-78605">Split API and implementation of progress component</a>
</li>
<li>(Nov 25 '05) <a href="#issue-68923">Allow to change display name of running progress task</a>
</li>
<li>(Oct 19 '05) <a href="#issue-66554">Adding <code>createProgressComponent(AggregateProgressHandle)</code> method to <code>AggregateProgressFactory</code></a>
</li>
<li>(Sep 26 '05) <a href="#issue-60966">Adding <code>setInitialDelay(int)</code> method to <code>ProgressHandle</code> and <code>AggregateProgressHandle</code></a>
</li>
<li>(May 4 '05) <a href="#version-1.0">Initial version released</a>
</li>
</ul>
<h1>
<a name="all-by-version">Changes by version</a>
</h1>
<p>
These API specification versions may be used to indicate that a module
requires a certain API feature in order to function. For example, if you
see here a feature you need which is labelled <samp>1.20</samp>, your
manifest should contain in its main attributes the line:
</p>
<pre>OpenIDE-Module-Module-Dependencies: org.netbeans.api.progress &gt; 1.20</pre>
<ul>
<li>
(1.45) <a href="#progresshandle.time">
Allow tracking of stale handles
</a>
</li>
<li>
(1.44) <a href="#taskmodel.sync">
Allow to synchronize with Controller's event delivery.
</a>
</li>
<li>
(1.40) <a href="#swingSplit">
Swing dependencies separated into a new module.
</a>
</li>
<li>
(1.30) <a href="#customDialogs"><code>ProgressUtils</code> class with <code>runOffEventThreadWithCustomDialogContent</code> and <code>runOffEventThreadWithProgressDialog</code> methods were added.</a>
</li>
<li>
(1.19) <a href="#modalRunMethods">Modal progress dialogs</a>
</li>
<li>
(1.18) <a href="#spi">SPI added</a>
</li>
<li>
(1.16) <a href="#ProgressUtils"><code>ProgressUtils</code> class with <code>runOffEventDispatchThread</code> methods was added.</a>
</li>
<li>
(1.9) <a href="#suspend">Add <code>ProgressHandle.suspend(String)</code> method for visual suspend of a running task.</a>
</li>
<li>
(1.8) <a href="#issue-58889">Add methods to create main/detail labels for an custom placed progress component.</a>
</li>
<li>
(1.7) <a href="#issue-78605">Split API and implementation of progress component</a>
</li>
<li>
(1.5) <a href="#issue-68923">Allow to change display name of running progress task</a>
</li>
<li>
(1.3) <a href="#issue-66554">Adding <code>createProgressComponent(AggregateProgressHandle)</code> method to <code>AggregateProgressFactory</code></a>
</li>
<li>
(1.2) <a href="#issue-60966">Adding <code>setInitialDelay(int)</code> method to <code>ProgressHandle</code> and <code>AggregateProgressHandle</code></a>
</li>
<li>
(1.0) <a href="#version-1.0">Initial version released</a>
</li>
</ul>
<h1>
<a name="all-by-class">Changes by affected class</a>
</h1>
<h2>
<a name="org.netbeans.api.progress.aggregate.AggregateProgressFactory"><code><span style="color:gray">org.netbeans.api.progress.aggregate.</span>AggregateProgressFactory</code></a>
</h2><ul><li>(Sep 18 '14) <a href="#swingSplit">
Swing dependencies separated into a new module.
</a>
</li>
<li>(Aug 3 '06) <a href="#issue-58889">Add methods to create main/detail labels for an custom placed progress component.</a>
</li>
<li>(Oct 19 '05) <a href="#issue-66554">Adding <code>createProgressComponent(AggregateProgressHandle)</code> method to <code>AggregateProgressFactory</code></a>
</li></ul><h2>
<a name="org.netbeans.api.progress.aggregate.AggregateProgressHandle"><code><span style="color:gray">org.netbeans.api.progress.aggregate.</span>AggregateProgressHandle</code></a>
</h2><ul><li>(Nov 25 '05) <a href="#issue-68923">Allow to change display name of running progress task</a>
</li>
<li>(Oct 19 '05) <a href="#issue-66554">Adding <code>createProgressComponent(AggregateProgressHandle)</code> method to <code>AggregateProgressFactory</code></a>
</li>
<li>(Sep 26 '05) <a href="#issue-60966">Adding <code>setInitialDelay(int)</code> method to <code>ProgressHandle</code> and <code>AggregateProgressHandle</code></a>
</li></ul><h2>
<a name="org.netbeans.modules.progress.spi.Controller"><code><span style="color:gray">org.netbeans.modules.progress.spi.</span>Controller</code></a>
</h2><ul><li>(Dec 7 '14) <a href="#taskmodel.sync">
Allow to synchronize with Controller's event delivery.
</a>
</li>
<li>(Sep 18 '14) <a href="#swingSplit">
Swing dependencies separated into a new module.
</a>
</li></ul><h2>
<a name="org.netbeans.modules.progress.spi.ExtractedProgressUIWorker"><code><span style="color:gray">org.netbeans.modules.progress.spi.</span>ExtractedProgressUIWorker</code></a>
</h2><ul><li>(Sep 18 '14) <a href="#swingSplit">
Swing dependencies separated into a new module.
</a>
</li></ul><h2>
<a name="org.netbeans.modules.progress.spi.InternalHandle"><code><span style="color:gray">org.netbeans.modules.progress.spi.</span>InternalHandle</code></a>
</h2><ul><li>(Feb 4 '15) <a href="#progresshandle.time">
Allow tracking of stale handles
</a>
</li>
<li>(Sep 18 '14) <a href="#swingSplit">
Swing dependencies separated into a new module.
</a>
</li></ul><h2>
<a name="org.netbeans.api.progress.ProgressHandle"><code><span style="color:gray">org.netbeans.api.progress.</span>ProgressHandle</code></a>
</h2><ul><li>(Oct 23 '06) <a href="#suspend">Add <code>ProgressHandle.suspend(String)</code> method for visual suspend of a running task.</a>
</li>
<li>(Nov 25 '05) <a href="#issue-68923">Allow to change display name of running progress task</a>
</li>
<li>(Sep 26 '05) <a href="#issue-60966">Adding <code>setInitialDelay(int)</code> method to <code>ProgressHandle</code> and <code>AggregateProgressHandle</code></a>
</li></ul><h2>
<a name="org.netbeans.api.progress.ProgressHandleFactory"><code><span style="color:gray">org.netbeans.api.progress.</span>ProgressHandleFactory</code></a>
</h2><ul><li>(Sep 18 '14) <a href="#swingSplit">
Swing dependencies separated into a new module.
</a>
</li>
<li>(Aug 3 '06) <a href="#issue-58889">Add methods to create main/detail labels for an custom placed progress component.</a>
</li></ul><h2>
<a name="org.netbeans.modules.progress.spi.ProgressUIWorkerProvider"><code><span style="color:gray">org.netbeans.modules.progress.spi.</span>ProgressUIWorkerProvider</code></a>
</h2><ul><li>(Sep 18 '14) <a href="#swingSplit">
Swing dependencies separated into a new module.
</a>
</li></ul><h2>
<a name="org.netbeans.api.progress.ProgressUtils"><code><span style="color:gray">org.netbeans.api.progress.</span>ProgressUtils</code></a>
</h2><ul><li>(Sep 18 '14) <a href="#swingSplit">
Swing dependencies separated into a new module.
</a>
</li>
<li>(Aug 28 '12) <a href="#customDialogs"><code>ProgressUtils</code> class with <code>runOffEventThreadWithCustomDialogContent</code> and <code>runOffEventThreadWithProgressDialog</code> methods were added.</a>
</li>
<li>(Nov 2 '09) <a href="#ProgressUtils"><code>ProgressUtils</code> class with <code>runOffEventDispatchThread</code> methods was added.</a>
</li></ul><h2>
<a name="org.netbeans.modules.progress.spi.TaskModel"><code><span style="color:gray">org.netbeans.modules.progress.spi.</span>TaskModel</code></a>
</h2><ul><li>(Dec 7 '14) <a href="#taskmodel.sync">
Allow to synchronize with Controller's event delivery.
</a>
</li></ul><hr>
<h1>
<a name="details-by-api">Details of all changes by API and date</a>
</h1>
<hr style="width:50%">
<h2>
<a name="progress_api">Progress API</a>
</h2>
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! -->
<h3>
<a name="progresshandle.time">
Allow tracking of stale handles
</a>
</h3>
<em>Feb 4 '15; API spec. version: 1.45; affected top-level classes: <a href="./org/netbeans/modules/progress/spi/InternalHandle.html"><code>InternalHandle</code></a>; made by: sdedic</em>
<br>
Internal handle allows to inspect the last time the handle was pinged by the
running process. This is needed to report stale processes and/or stop them.
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --><h3>
<a name="taskmodel.sync">
Allow to synchronize with Controller's event delivery.
</a>
</h3>
<em>Dec 7 '14; API spec. version: 1.44; affected top-level classes: <a href="./org/netbeans/modules/progress/spi/Controller.html"><code>Controller</code></a> <a href="./org/netbeans/modules/progress/spi/TaskModel.html"><code>TaskModel</code></a>; made by: sdedic</em>
<br>
Exposes Executor used by the <a href="org/netbeans/modules/progress/spi/Controller.html" shape="rect">Controller</a> to deliver progress events, so that
<a href="org/netbeans/modules/progress/spi/TaskModel.html" shape="rect">TaskModel</a> can synchronize its change events to the same event stream.
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --><h3>
<a name="swingSplit">
Swing dependencies separated into a new module.
</a>
</h3>
<em>Sep 18 '14; API spec. version: 1.40; affected top-level classes: <code>org.netbeans.api.progress.ProgressHandleFactory</code> <code>org.netbeans.api.progress.ProgressUtils</code> <code>org.netbeans.api.progress.aggregate.AggregateProgressFactory</code> <code>org.netbeans.modules.progress.spi.ExtractedProgressUIWorker</code> <code>org.netbeans.modules.progress.spi.ProgressUIWorkerProvider</code> <a href="./org/netbeans/modules/progress/spi/Controller.html"><code>Controller</code></a> <a href="./org/netbeans/modules/progress/spi/InternalHandle.html"><code>InternalHandle</code></a>; made by: sdedic; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=247111">
#247111</a></em>
<br>
<p>
Progress API was split so that parts that are directly connected to Swing types were migrated
to a separate module. Please see <a href="../org-netbeans-api-progress-nb/apichanges.html" shape="rect">it's API changes
document</a> for additional info. Affected classes:
</p>
<ul>
<li>
<a href="../org-netbeans-api-progress-nb/org/netbeans/api/progress/ProgressHandleFactory.html" shape="rect">ProgressHandleFactory</a>
</li>
<li>
<a href="../org-netbeans-api-progress-nb/org/netbeans/api/progress/ProgressUtils.html" shape="rect">ProgressUtils</a>
</li>
<li>
<a href="../org-netbeans-api-progress-nb/org/netbeans/api/progress/aggregate/AggregateProgressFactory.html" shape="rect">AggregateProgressFactory</a>
</li>
<li>
<a href="../org-netbeans-api-progress-nb/org/netbeans/modules/progress/spi/ExtractedProgressUIWorker.html" shape="rect">ExtractedProgressUIWorker</a>
</li>
<li>
<a href="../org-netbeans-api-progress-nb/org/netbeans/modules/progress/spi/ExtractedProgressUIWorker.html" shape="rect">ProressUIWorkerProvider</a>
</li>
<li>
<a href="../org-netbeans-api-progress-nb/org/netbeans/modules/progress/spi/SwingController.html" shape="rect">SwingController</a>
</li>
<li>
<a href="../org-netbeans-api-progress-nb/org/netbeans/modules/progress/spi/UIInternalHandle.html" shape="rect">UIInternalHandle</a>
</li>
</ul>
<br>
<em><a href="http://wiki.netbeans.org/VersioningPolicy#Compatible_change_on_the_trunk">Binary-compatible</a></em>
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! -->
<h3>
<a name="customDialogs"><code>ProgressUtils</code> class with <code>runOffEventThreadWithCustomDialogContent</code> and <code>runOffEventThreadWithProgressDialog</code> methods were added.</a>
</h3>
<em>Aug 28 '12; API spec. version: 1.30; affected top-level classes: <code>org.netbeans.api.progress.ProgressUtils</code>; made by: pflaska ; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=204553">
#204553</a></em>
<br>
<code>ProgressUtils</code> class with <code>runOffEventThreadWithCustomDialogContent</code> and <code>runOffEventThreadWithProgressDialog</code> methods were added. These methods allow movement of operations out of AWT thread, showing the waint cursor after one second and a dialog when task is not finished in a three seconds.
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --><h3>
<a name="modalRunMethods">Modal progress dialogs</a>
</h3>
<em>Feb 8 '10; API spec. version: 1.19; made by: tboudreau; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=165005">
#165005</a></em>
<br>
<p>
Added methods to ProgressUtils for invoking a runnable or
similar with
a modal dialog blocking the UI and showing progress:
</p>
<ul>
<li>
<code>public static void showProgressDialogAndRun(Runnable operation, String displayName)</code>
</li>
<li>
<code>public static &lt;T&gt; T showProgressDialogAndRun(final ProgressRunnable&lt;T&gt; operation, final String displayName, boolean includeDetailLabel)</code>
</li>
<li>
<code>public static void showProgressDialogAndRun(Runnable operation, ProgressHandle progress, boolean includeDetailLabel)</code>
</li>
<li>
<code>public static RequestProcessor.Task showProgressDialogAndRunLater(Runnable operation, ProgressHandle progress, boolean includeDetailLabel)</code>
</li>
</ul>
<p>
Added interface ProgressRunnable for performing background
work, and an SPI class ProgressRunOffEdtProvider which is
implemented by the Progress UI module.
</p>
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! -->
<h3>
<a name="spi">SPI added</a>
</h3>
<em>Jan 8 '10; API spec. version: 1.18; made by: jglick; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=177945">
#177945</a></em>
<br>
<p>
An internal SPI package was exposed. Normal modules should not
need to access this package.
</p>
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! -->
<h3>
<a name="ProgressUtils"><code>ProgressUtils</code> class with <code>runOffEventDispatchThread</code> methods was added.</a>
</h3>
<em>Nov 2 '09; API spec. version: 1.16; affected top-level classes: <code>org.netbeans.api.progress.ProgressUtils</code>; made by: t_h; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=170882">
#170882</a></em>
<br>
<code>ProgressUtils</code> class with <code>runOffEventDispatchThread</code> methods
was added. These methods allow movement of operations out of AWT thread while blocking UI.
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! --><h3>
<a name="suspend">Add <code>ProgressHandle.suspend(String)</code> method for visual suspend of a running task.</a>
</h3>
<em>Oct 23 '06; API spec. version: 1.9; affected top-level classes: <a href="./org/netbeans/api/progress/ProgressHandle.html"><code>ProgressHandle</code></a>; made by: mkleint; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=63586">
#63586</a></em>
<br>
<p>Adding <code>suspend(String)</code> to <code>ProgressHandle</code> class.
Any progress event coming after this call wakes up the progress bar to previous state. </p>
<p>
Currently running task can switch to silent suspend mode where the progress bar stops moving, hides completely or partially.
The exact UI behaviour is undefined. </p>
<p>
Useful to make progress in status bar less intrusive for very long running tasks, eg. running an ant script that executes user application, debugs user application etc.
</p>
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! -->
<h3>
<a name="issue-58889">Add methods to create main/detail labels for an custom placed progress component.</a>
</h3>
<em>Aug 3 '06; API spec. version: 1.8; affected top-level classes: <code>org.netbeans.api.progress.ProgressHandleFactory</code> <code>org.netbeans.api.progress.aggregate.AggregateProgressFactory</code>; made by: mkleint; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=58889">
#58889</a></em>
<br>
<p>Adding <code>createMainLabelComponent(ProgressHandle)</code> and
<code>createDetailLabelComponent(ProgressHandle)</code> to <code>ProgressHandleFactory</code> and <code>AggregateProgressFactory</code> classes.
These are complementary to the <code>createProgressComponent(ProgressHandle)</code> method and allow to
externalize the display of task's display name and detail messages when embedded in custom UI components.
</p>
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! -->
<h3>
<a name="issue-78605">Split API and implementation of progress component</a>
</h3>
<em>Jul 24 '06; API spec. version: 1.7; made by: mkleint; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=78605">
#78605</a></em>
<br>
<p>
Split the implementation and APIs of progress component.
</p>
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! -->
<h3>
<a name="issue-68923">Allow to change display name of running progress task</a>
</h3>
<em>Nov 25 '05; API spec. version: 1.5; affected top-level classes: <a href="./org/netbeans/api/progress/ProgressHandle.html"><code>ProgressHandle</code></a> <a href="./org/netbeans/api/progress/aggregate/AggregateProgressHandle.html"><code>AggregateProgressHandle</code></a>; made by: mkleint; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=68923">
#68923</a></em>
<br>
<p>
Added new method <code>setDisplayName(String)</code> to <code>ProgressHandle</code> and <code>AggregateProgressHandle</code>,
allows to change the main identifying name of the progress task.
</p>
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! -->
<h3>
<a name="issue-66554">Adding <code>createProgressComponent(AggregateProgressHandle)</code> method to <code>AggregateProgressFactory</code></a>
</h3>
<em>Oct 19 '05; API spec. version: 1.3; affected top-level classes: <code>org.netbeans.api.progress.aggregate.AggregateProgressFactory</code> <a href="./org/netbeans/api/progress/aggregate/AggregateProgressHandle.html"><code>AggregateProgressHandle</code></a>; made by: mkleint; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=66554">
#66554</a></em>
<br>
<p>
For aggregated progress handles the equivalent of ProgressHandleFactory.createProgressComponent() was missing.
Added in this version.
</p>
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! -->
<h3>
<a name="issue-60966">Adding <code>setInitialDelay(int)</code> method to <code>ProgressHandle</code> and <code>AggregateProgressHandle</code></a>
</h3>
<em>Sep 26 '05; API spec. version: 1.2; affected top-level classes: <a href="./org/netbeans/api/progress/ProgressHandle.html"><code>ProgressHandle</code></a> <a href="./org/netbeans/api/progress/aggregate/AggregateProgressHandle.html"><code>AggregateProgressHandle</code></a>; made by: mkleint; issues: <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=60966">
#60966</a></em>
<br>
<p>
The newly added methods allow to customize the amount of time that shall pass between the start of handle's progress
and it's appearance in the status bar. If the progress task finishes fast enough it won't appear in the UI at all.
The default value is around 0.5s. </p>
<p>
For handles that are used in dialogs and elsewhere, this property has no effect and the handle's component is shown immediately.
</p>
<!-- AUTOMATICALLY GENERATED - DO NOT EDIT ME! -->
<h3>
<a name="version-1.0">Initial version released</a>
</h3>
<em>May 4 '05; API spec. version: 1.0; made by: mkleint</em>
<br>first initial release of the progress api.
<hr>
<p><span class="footnote">Built on September 14 2018.&nbsp;&nbsp;|&nbsp;&nbsp; Copyright &#169; 2017-2018 Apache Software Foundation. All Rights Reserved.</span></p>
</body>
</html>