| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <!-- Generated by javadoc (1.8.0_181) on Fri Sep 14 11:34:55 BST 2018 --> |
| <title>Overview (Progress API)</title> |
| <meta name="date" content="2018-09-14"> |
| <link rel="stylesheet" type="text/css" href="javadoc.css" title="Style"> |
| <script type="text/javascript" src="script.js"></script> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| try { |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="Overview (Progress API)"; |
| } |
| } |
| catch(err) { |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar.top"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.top.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li class="navBarCell1Rev">Overview</li> |
| <li>Package</li> |
| <li>Class</li> |
| <li>Use</li> |
| <li><a href="overview-tree.html">Tree</a></li> |
| <li><a href="deprecated-list.html">Deprecated</a></li> |
| <li><a href="index-files/index-1.html">Index</a></li> |
| <li><a href="help-doc.html">Help</a></li> |
| </ul> |
| <div class="aboutLanguage">org.netbeans.api.progress/1 1.49.1 </div> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li>Prev</li> |
| <li>Next</li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="index.html?overview-summary.html" target="_top">Frames</a></li> |
| <li><a href="overview-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <div class="header"> |
| <h1 class="title">Progress API<br/><span style='font-style:normal; font-size:medium; font-weight:normal; background-color:#ffffff;'><a href='http://wiki.netbeans.org/API_Stability#Official' target='_blank'>Official</a></span></h1> |
| </div> |
| <div class="header"> |
| <p>See: <a href="#overview.description">Description</a></p> |
| </div> |
| <div class="contentContainer"> |
| <table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Progress API table, listing packages, and an explanation"> |
| <caption><span>Progress API</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Package</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="org/netbeans/api/progress/package-summary.html">org.netbeans.api.progress</a></td> |
| <td class="colLast"> |
| <div class="block">This API allows to visualize tracking for progress of long lasting tasks.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="org/netbeans/api/progress/aggregate/package-summary.html">org.netbeans.api.progress.aggregate</a></td> |
| <td class="colLast"> |
| <div class="block">Advanced progress manipulation, allowing to construct a single progress indication bar |
| from multiple, possibly independent sources.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="org/netbeans/modules/progress/spi/package-summary.html">org.netbeans.modules.progress.spi</a></td> |
| <td class="colLast"> |
| <div class="block">Interfaces permitting a UI for the progress system to be supplied.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="contentContainer"><a name="overview.description"> |
| <!-- --> |
| </a> |
| <div class="block"><p> |
| |
| <p> |
| The module will be autoload. |
| There is an api module and a pluggable implementation. |
| <a href="../org-netbeans-api-progress/index.html">Progress</a> |
| |
| </p> |
| |
| </p> |
| <h3>What is New (see <a href="apichanges.html">all changes</a>)?</h3> |
| <ul> |
| |
| |
| <!--Search for dates that are later or equal to 1997-09-01 in |
| .--> |
| <!--Checking date 2015-2-4 with count of newer 0--><!--year ok--> |
| <li>Feb 4 '15 <a href="apichanges.html#progresshandle.time"> |
| Allow tracking of stale handles |
| </a> |
| <p> |
| 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. |
| </p> |
| </li> |
| <!--Checking date 2014-12-7 with count of newer 1--><!--year ok--> |
| <li>Dec 7 '14 <a href="apichanges.html#taskmodel.sync"> |
| Allow to synchronize with Controller's event delivery. |
| </a> |
| <p> |
| 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. |
| </p> |
| </li> |
| <!--Checking date 2014-9-18 with count of newer 2--><!--year ok--> |
| <li>Sep 18 '14 <a href="apichanges.html#swingSplit"> |
| Swing dependencies separated into a new module. |
| </a> |
| <p> |
| |
| <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> |
| |
| </p> |
| </li> |
| <!--Checking date 2012-8-28 with count of newer 3--><!--year ok--> |
| <li>Aug 28 '12 <a href="apichanges.html#customDialogs"><code>ProgressUtils</code> class with <code>runOffEventThreadWithCustomDialogContent</code> and <code>runOffEventThreadWithProgressDialog</code> methods were added.</a> |
| <p> |
| <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. |
| </p> |
| </li> |
| <!--Checking date 2010-2-8 with count of newer 4--><!--year ok--> |
| <li>Feb 8 '10 <a href="apichanges.html#modalRunMethods">Modal progress dialogs</a> |
| <p> |
| |
| <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 <T> T showProgressDialogAndRun(final ProgressRunnable<T> 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> |
| |
| </p> |
| </li> |
| <!--Checking date 2010-1-8 with count of newer 5--><!--Skipped as the amount of changes is too big--> |
| <!--Checking date 2009-11-2 with count of newer 6--><!--Skipped as the amount of changes is too big--> |
| <!--Checking date 2006-10-23 with count of newer 7--><!--Skipped as the amount of changes is too big--> |
| <!--Checking date 2006-8-3 with count of newer 8--><!--Skipped as the amount of changes is too big--> |
| <!--Checking date 2006-7-24 with count of newer 9--><!--Skipped as the amount of changes is too big--> |
| <!--Checking date 2005-11-25 with count of newer 10--><!--Skipped as the amount of changes is too big--> |
| <!--Checking date 2005-10-19 with count of newer 11--><!--Skipped as the amount of changes is too big--> |
| <!--Checking date 2005-9-26 with count of newer 12--><!--Skipped as the amount of changes is too big--> |
| <!--Checking date 2005-5-4 with count of newer 13--><!--Skipped as the amount of changes is too big--> |
| </ul> |
| <h3>Use Cases</h3> |
| <answer id="arch-usecases"> |
| |
| <h5>Basic usage</h5> |
| |
| <p>There are 3 types of progress indication:</p> |
| |
| <ul> |
| |
| <li>1. indefinite when it's not known how much time will be needed to complete</li> |
| |
| <li>2. definite with time estimate for completion (UI shows time that remains)</li> |
| |
| <li>3. definite without time estimate where the UI shows percentage completed.</li> |
| |
| </ul> |
| |
| <p> |
| The default location of the progress indication is the status bar which aggregates all |
| tasks running in the IDE that show progress. However it's possible to exclude the task from the default location |
| and show the progress in one's custom dialog component. In such a case the same task should not appear in the status line component as well. |
| </p> |
| |
| <p> |
| It's possible to request cancelling the task from status line progress aggregator if the task allows cancelling. |
| </p> |
| |
| |
| <p> |
| Progress tasks that get started as a result of explicit user action takes precedence in the status line |
| docked component over tasks that are triggered by the system. (say filesystem refresh for example) |
| </p> |
| |
| <p> The most common usecase of the API looks like this: </p> |
| |
| <pre xml:space="preserve"> |
| ProgressHandle handle = ProgressHandleFactory.creatHandle("My custom task"); |
| ... |
| // we have 100 workunits |
| // at this point the task appears in status bar. |
| handle.start(100); |
| ... |
| handle.progress(10); |
| ... |
| handle.progress("half way through", 50); |
| ... |
| handle.progress(99); |
| // at this point the task is finished and removed from status bar |
| // it's not realy necessary to count all the way to the limit, finish can be called earlier. |
| // however it has to be called at the end of the processing. |
| handle.finish(); |
| </pre> |
| |
| |
| <h5>Advanced Usage</h5> |
| |
| <p>In case your usage of the API </p> |
| |
| <ul> |
| |
| <li>spans across multiple independent modules, </li> |
| |
| <li>requires adjusting of number of workunits or </li> |
| |
| <li>triggers additional action based on the current progress</li> |
| |
| </ul> |
| |
| <p> |
| then you should consider using the aggregating version of APIs which is similar to the |
| simple APIs but has distinctive differences and additions that allow for more complex scenarios. |
| </p> |
| |
| <p> |
| It allows to compose the progress bar from 1+ independent sources, all sharing proportional piece |
| of the progress bar. Additionally you can monitor the task's overall progress from one central place and possibly |
| add more contributing sources of the progress during processing. |
| </p> |
| |
| <pre xml:space="preserve"> |
| // let's have a factory for client code that performs some part of the job to be done.. |
| Lookup.Result res = Lookup.getDefault().lookup(new LookupTemplate(MyWorkerFactory.class)); |
| Iterator it = res.allInstances().iterator(); |
| ProgressContributor[] contribs = new ProgressContributor[res.allInstances().size()]; |
| int i = 0; |
| while (it.hasNext()) { |
| MyWorkerFactory prov = (MyWorkerFactory)it.next(); |
| contribs[i] = AggregateProgressFactory.createProgressContributor("Module X contribution"); |
| MyWorker worker = prov.createWorker(contribs[i]); |
| //... snip ... do something with the worker.. |
| i = i + 1; |
| } |
| AggregateProgressHandle handle = AggregateProgressFactory.createHandle("My Task", contribs, null, null); |
| // non-cancellable and with out output link. |
| |
| // calling start() at the time when the actual long running task starts processing |
| handle.start("here we go"); |
| // ...snip... |
| // now the individual MyWorker instances log their progress. |
| // possibly in other threads too.. |
| // ... snip... |
| // |
| if (myConditionThatSpawnsAnotherContributor()) { |
| ProgressContributor cont = AggregateProgressFactory.createProgressContributor("Additional exceptional contribution"); |
| handle.addContributor(cont); |
| // ... snip ... |
| } |
| |
| // the task is finished when all the ProgressContributors finish.. |
| </pre> |
| |
| |
| |
| </answer> |
| <h3>Exported Interfaces</h3> |
| |
| This table lists all of the module exported APIs |
| with |
| defined stability classifications. It is generated |
| based on answers to questions about the architecture |
| of the module. <a href="architecture-summary.html">Read them all</a>... |
| |
| |
| <a name="group-java"> |
| <h5>Group of java interfaces</h5> |
| </a> |
| <table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%"> |
| <tr> |
| <td> |
| <table border="0" cellpadding="3" cellspacing="1" width="100%"> |
| <tr class="tablersh"> |
| <td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td> |
| </tr> |
| <tr class="tabler"> |
| <td>Progress</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Official">Official</a></td><td><a name="java-Progress"><a href="../org-netbeans-api-progress/index.html">../org-netbeans-api-progress/index.html</a> |
| <p></p> |
| </a></td> |
| </tr> |
| </table> |
| </td> |
| </tr> |
| </table> |
| <p></p> |
| <h3>Implementation Details</h3> |
| <h5>What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?</h5> |
| |
| <p> |
| Nothing. |
| </p> |
| |
| <p> |
| Read more about the implementation in the <a href="architecture-summary.html">answers to |
| architecture questions</a>. |
| </p></div> |
| </div> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar.bottom"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.bottom.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li class="navBarCell1Rev">Overview</li> |
| <li>Package</li> |
| <li>Class</li> |
| <li>Use</li> |
| <li><a href="overview-tree.html">Tree</a></li> |
| <li><a href="deprecated-list.html">Deprecated</a></li> |
| <li><a href="index-files/index-1.html">Index</a></li> |
| <li><a href="help-doc.html">Help</a></li> |
| </ul> |
| <div class="aboutLanguage">org.netbeans.api.progress/1 1.49.1 </div> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li>Prev</li> |
| <li>Next</li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="index.html?overview-summary.html" target="_top">Frames</a></li> |
| <li><a href="overview-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| <p class="legalCopy"><small><span class="footnote">Built on September 14 2018. | Copyright © 2017-2018 Apache Software Foundation. All Rights Reserved.</span></small></p> |
| </body> |
| </html> |
