This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.
I'd like to ask for inception review on new Progress API.
Created attachment 20505 [details] initial version of API.
Created attachment 20557 [details] arch document
reassigning to apireviews (inception review on 8/3/2005), API javadoc and arch document attached. UI spec at: http://ui.netbeans.org/docs/ui/progress_indication/progress_indication_spec.html
The responsible reviewer is going to be Mila. Pavel, Tonda and Petr will have the vote as they are either main consumers or requestors of the progress indicator effort. Review is going to be next tuesday. Mila please announce it on nbdev soon.
I miss "shutdown progress bar" use case. Could you add it, please? Thanks.
Comments on the API: Javadoc should clarify if display names are unique - if I call ProgressHandle a = ProgressHandleFactory.createHandle ("foo"); ProgressHandle b = ProgressHandleFactory.createHandle ("foo"); a == b? a != b? a.equals(b) --- Slightly prefer "Cancelable" over "CancelableTask" --- Unclear what the distinction between createHandle() and createSystemHandle() is, but I can guess: createHandle() blocks the UI and createSystemHandle() doesn't? If so, would prefer method names which make clear the UI behavior - "system" won't be terribly clear to someone new to NetBeans. Maybe createHandle (String s, boolean blockUI)? Or maybe this is just some distinction in the way the UI is presented and has nothing to do with blocking. --- Unclear what happens if I call createProgressComponent() twice. --- If I understand the netbeans package naming convention correctly, shouldn't the package be "org.netbeans.api.progress", not "org.netbeans.progress.api"? --- Typically for long running tasks, we show "Finished doing something" in the statusbar. You might want ProgressHandle.finish (String message) to do this.
ProgressHandle a = ProgressHandleFactory.createHandle ("foo"); ProgressHandle b = ProgressHandleFactory.createHandle ("foo"); correct is: a != b I thought the name of the method "createHandle" is more than a hint that you get 2 distinct instances. I can add a comment about it though. -- Cancelable vs. CancelableTask, I was deciding between the two.. no real preference, CancelableTask somehow pretends to be a task of it's own which is not. I used to have Backgroundable interface as well, but that one sounded strange. that's why I picked Cancelabletask. -- systemhandles are just a distinction in the UI. (lower priority for display in the status line etc) how would you rephrase the javadoc to make it more obvious? "Create a handle for a long lasting task that is not triggered by explicit user action." -- "Unclear what happens if I call createProgressComponent() twice." You get an illegal state exception. -- "org.netbeans.api.progress" vs. "org.netbeans.progress.api". refactoring is cheap nowadays ;) -- Not part of the UI spec now. Could be added in future if required.
> Cancelable vs. CancelableTask: BTW we already have identical Cancellable interface in the openide: package org.openide.util; public interface Cancellable { public boolean cancel (); } --- It looks like this API solves scenario, when I know progress and I want to show it. But it does not solve scenario when I want to listen on someone's progress and I want to show it. Consider this use case (Find Usages): Refactoring module asks java model to get references of some Field. It is long lasting task and refactoring module wants to listen on this task and show progress indication to user. Currently it is implemented this way: JavaMetamodel.getManager().getProgressSupport().addProgressListener(l); field.getReferences(); . . class L implements ProgressListener { public start(ProgressEvent e) { //do something } . public step(ProgressEvent e) ... . } It looks like proposed progress indication api does not solve progress observing, which is necessary for us.
Re: Jan Becicka 1. Cancelable from org.openide.util makes sense, I was not aware such interface exists already.. 2. I'm not sure I understand te problem here. Would this not work for you? JavaMetamodel.getManager().getProgressSupport().addProgressListener(l); field.getReferences(); . . class L implements ProgressListener { public start(ProgressEvent e) { ProgressHandle handle = ProgresshandleFactory.createHandle("xxx"); handle.start() } . public step(ProgressEvent e) { handle.progress("Another step done"); } public void stop(ProgressEvent event) { handle.finish(); }
Created attachment 20676 [details] updated progress arch document (this time in html for better reading
I have updated the arch document's usecase section.
> 2. I'm not sure I understand te problem here. Would this not work for you? Yes. Exactly. It works for me this way, but it does not replace my own "Progress API". Background of my previous post: There was an internal Progress API in javacore (ProgressListener and ProgressEvent). This mini Progress API was used in javacore and also in Refactoring API. DevRev required not to use javacore's progress API in refactoring API and advised to create an copy of this API in refactoring module. So we have 2 progress APIs. One in javacore module and second in refactoring module. My expactation was, that this unhandsome thing disappears with new official Progress API.
ok, I understand now. I think the currently defined scope of the API is to provide api for UI components representing progress. Your usecase is more close to the concept of Job (as is in eclipse for example) which includes the progress listening, job scheduling, job chaining, task prioritizing etc. As we already have RequestProcessor, your progress listening API should most probably go there IMHO. One of the default listener implementations could be a bridge to the Progress API that displays the status in th UI. (That would be on par with the Eclipse job api example)
I've talked to the refactoring guys and I think I understand the usecase now: 1. there are 1+ contributors to the progress, all having equal share of the total length. 2. each of the contributors fills it's part of the progress with a variable number of steps. (number of steps can change during processing as well) 3. contributors can be added during processing, than the remaining lenght has to be split and accustomize the new additional progress contributor. 4. processing happens serially, one progress contributor after another. is that correct?
Seems correct. But as we discussed, we were hoping to also get a general progress API (not bound to any visual component) that could replace our ProgressListener and ProgressProvider interfaces that we had to duplicate in javacore and refactoring. It is a simple API for reporting progress to other (not necessarily visual) clients.
BTW: s/Cancelable/Cancellable/g Any support for named/metered subtasks? (Does anyone care?)
Various notes touching ProcessHAndle ("PH") API other UI spec: - (semantics) Swing's ProgressMonitor allows to define a silence interval. Typically 2 sec. During this interval no progress is shown. It allows to use progress API in all cases - no one can project actual operation length (does it fit to <1sec category or >1sec category for given input?). - (ui, api) I need second progress component instance. I place the component in dedicated window that shows detailed action progress (including partial results). Add BoundedRangeModel PH.getBoundedRangeModel(). - (api) remove Components from API and replace with models (see above). - (ui, api) I need navigation action. It should call my Runnable. Add PH.setNavigationAction(Runnable). - (api) cancellation should not be static parameter. Better PH.setCancelAction(Cancellable); - (api) Make the API thread safe. I can have two paralell threads one estimating complexity (counting folders is really expensive) and one performing actual operation. - (api) estimates should not be static parameter (passed in start()). More accurate estimate can be provided while operarion in progress. Add PH.estimate(int units) and PH.estimate(long time) methods. - (api) I do not like start() semantics. I'd prefer the factory method to return already started instance.
Jesse Glick wrote: Any support for named/metered subtasks? (Does anyone care?) Not exactly sure what you mean. Yarda showed me a usecase when a directory structure copy would need to lookup the progress task somehow and create a subtask for itself to be added to the overall task. I think such a usecase can be solved by another layer of APIs on top of the basic one (which is attached to the issue) I would prefer to keep them separate for sake of simplicity of the basic API, as anything with subtasks has different contract that a simple task. refactoring has a usecase for subtasks that together compose a progressbar to be shown, that's IMHO similar.
the ui spec was updated http://ui.netbeans.org/docs/ui/progress_indication/progress_indication_spec.html
Review will be on 27/04/2005 [17.00 CET]. Mila. Pavel, Tonda and Petr, I hope that this date works for you. Milos, please make sure that uptodate documentation (especially list of usecases) is linked from this issue. Mila please annouce this on nbdev.
Created attachment 21722 [details] updated javadocs.
Created attachment 21728 [details] updated arch document with code snippets.
detailed list of use cases with design proposal for them is now on netbeans.org: http://performance.netbeans.org/proposals/ProgressIndicationUsecases.html
From "Detailed list of Progress Indication usecases" > FIRST OPEN EMPTY EDITOR TAB WITH "PLEASE WAIT" TEXT, THEN RUN THE DIFF AS A > REGULAR BACKGROUND TASK, AT THE END FILL THE EDITOR TAB WITH THE DIFF TEXT AND > MAYBE FLASH THE TAB'S TITLE During usability study users complained a lot about this approach. They want progress directly in component that waits on background task results. I'm mentioning it because it raises requirement for showing progress on two places (in component and in status line).
integrated into trunk.
The opinion document is available at http://openide.netbeans.org/tutorial/reviews/opinions_54941.html Apologies for delay.