|
| |
|
| java.lang.Object
 org.netbeans.installer.utils.progress.Progress
All known Subclasses: org.netbeans.installer.utils.progress.CompositeProgress,
| Progress | | public class Progress (Code) | | This class encapsulates data that describes the course of an operation, such as
the operation description, detailed status string and completion percentage.
A typical usecase would be for a client to costruct an instance of this object
and pass it to the operation handler, which will update the progress as the
operation goes on. The client can register itself as a listener for the progress
object; this way it will receive notifications on the progress updates.
The client can also use the built-in cancellation facility to inform the
operation handler of the necessity to break the operation and return. Whether
the operation will be stopped, however, solely depends on the operation handler's
politeness.
In some cases the opreation handler is not capable of working directly with the
progress that was passed to it. In this case it should construct a specialized
Progress instance and use the synchronization facility to keep these two
in sync.
See Also: Progress.addProgressListener(ProgressListener)
See Also: Progress.setCanceled(boolean)
See Also: Progress.synchronizeFrom(Progress)
See Also: CompositeProgress
author:
Kirill Sorokin
since:
1.0 |
| Field Summary | |
| final public static int | COMPLETE
The final (maximum) value of a progress' percentage. | | final public static String | ERROR_WRONG_PERCENTAGE
The error message which will be displayed when a user tries to set an invalid
percentage. | | final public static int | START
The initial (minimum) value of a progress' percentage. | | protected boolean | canceled
A flag which indicates whether or not the progress has been canceled. | | protected String | detail
The detailed status of the progress. | | protected int | percentage
The current state of the progress expressed in percents. | | protected String | title
The title (i.e. |
| Constructor Summary | |
| public | Progress()
Creates a new
Progress instance. | | public | Progress(ProgressListener initialListener)
Creates a new
Progress instance and registers the supplied listener.
It's important to remember that listeners in progress are not implemented via
weak references and hence should be handled with care. |
| Method Summary | |
| public void | addPercentage(int addition)
Adds the specified amount to the percentage property. | | public void | addProgressListener(ProgressListener listener)
Adds (registers) a progress listener to this progrss object. | | public String | getDetail()
Returns the value of the detail property. | | public int | getPercentage()
Returns the value of the percentage property. | | public String | getTitle()
Returns the value of the title property. | | public boolean | isCanceled()
Returns the value of the canceled property. | | protected void | notifyListeners()
Notifies the registered listeners that one or more of the progress'
properties has changed. | | public void | removeProgressListener(ProgressListener listener)
Removes (unregisters) a progress listener from this progress object. | | public void | reverseSynchronizeFrom(Progress progress)
Sets up the reverse synchronization of this progress object from the
specified source. | | public void | reverseSynchronizeTo(Progress progress)
Sets up the reverse synchronization of this progress object to the specified
target. | | public void | setCanceled(boolean canceled)
Sets the value of the canceled property. | | public void | setDetail(String detail)
Sets the value of the detail property. | | public void | setPercentage(int percentage)
Sets the value of the percentage property. | | public void | setPercentage(long percentage)
Sets the value of the percentage property. | | public void | setTitle(String title)
Sets the value of the title property. | | public void | synchronizeFrom(Progress progress)
Sets up the synchronization of this progress object from the specified
source. | | public void | synchronizeTo(Progress progress)
Sets up the synchronization of this progress object to the specified target. |
| COMPLETE | | final public static int COMPLETE(Code) | | The final (maximum) value of a progress' percentage.
|
| ERROR_WRONG_PERCENTAGE | | final public static String ERROR_WRONG_PERCENTAGE(Code) | | The error message which will be displayed when a user tries to set an invalid
percentage.
|
| START | | final public static int START(Code) | | The initial (minimum) value of a progress' percentage.
|
| canceled | | protected boolean canceled(Code) | | A flag which indicates whether or not the progress has been canceled. It is
expected that the updater of the progress will check the value of this
flag and act accordingly. It should be used to establish some basic
communication between the invoker of a lengthy operation and the code which
actually performs the operation.
|
| detail | | protected String detail(Code) | | The detailed status of the progress. As opposed to the title, the detail
is expected to change with every couple changes in the procentage.
|
| percentage | | protected int percentage(Code) | | The current state of the progress expressed in percents. Obviously the most
often changed property of the progress.
|
| title | | protected String title(Code) | | The title (i.e. human readable description) of the progress. The title is
expected not to change often during the course of the progress.
|
| Progress | | public Progress()(Code) | | Creates a new
Progress instance. The new instance has its
title and detail set to empty strings,
percentage to
Progress.START and canceled to
false.
|
| addPercentage | | public void addPercentage(int addition)(Code) | | Adds the specified amount to the percentage property. The added
amount can be either positive or negative. Teh percentage value will be
updated only if the result of the addition is different from the current
percentage. Also the listeners are notified only is the update actually took
place.
Parameters:
addition - The amount to add to the percentage property. {@link IllegalArgumentException} if the supplied percentage cannot be added. |
| addProgressListener | | public void addProgressListener(ProgressListener listener)(Code) | | Adds (registers) a progress listener to this progrss object. If the argument
is null, no action will be performed.
In most cases a single
Progress instance will have only one listener,
so it is feasible to use the specialized constructor overlod instead of this
method.
Parameters:
listener - A progress listener to add.
See Also: ProgressListener
See Also: Progress.Progress(ProgressListener) |
| getDetail | | public String getDetail()(Code) | | Returns the value of the detail property.
The value of the detail property. |
| getPercentage | | public int getPercentage()(Code) | | Returns the value of the percentage property.
The value of the percentage property. |
| getTitle | | public String getTitle()(Code) | | Returns the value of the title property.
The value of the title property. |
| isCanceled | | public boolean isCanceled()(Code) | | Returns the value of the canceled property.
The value of the canceled property. |
| notifyListeners | | protected void notifyListeners()(Code) | | Notifies the registered listeners that one or more of the progress'
properties has changed.
See Also: ProgressListener |
| removeProgressListener | | public void removeProgressListener(ProgressListener listener)(Code) | | Removes (unregisters) a progress listener from this progress object. If the
argument is null or is not present in the listeners list, no action will
be performed.
Parameters:
listener - A progress listener to remove.
See Also: ProgressListener |
| reverseSynchronizeFrom | | public void reverseSynchronizeFrom(Progress progress)(Code) | | Sets up the reverse synchronization of this progress object from the
specified source.
This method is very similar to the
Progress.synchronizeFrom(Progress) method.
The only difference is in that instead of setting the percentage of this
progress object to the percentage of the source, it is set to the difference
between
Progress.COMPLETE and the source's percentage.
In order to remove the synchronization link on this progress, just supply
null as the parameter.
Parameters:
progress - A progress object from which to set up the synchronization,or null to cancel the synchronization.
See Also: Progress.synchronizeFrom(Progress) |
| setCanceled | | public void setCanceled(boolean canceled)(Code) | | Sets the value of the canceled property. The value is updated
only if the supplied value is different from the current. Also the progress
listeners are notified only if the update actually took place.
If the progress is in being synchronized from another progress. The cancelled
status will be propagated to the synchronization source.
Parameters:
canceled - The new value for the canceled property. |
| setDetail | | public void setDetail(String detail)(Code) | | Sets the value of the detail property. The value is updated only
if the supplied detail is different from the current. Also the progress
listeners are notified only if the update actually took place.
Parameters:
detail - The new value for the detail property. |
| setPercentage | | public void setPercentage(int percentage)(Code) | | Sets the value of the percentage property. The value is updated
only if the supplied percentage is different from the current. Also the
progress listeners are notified only if the update actually took place.
Parameters:
percentage - The new value for the percentage property. {@link IllegalArgumentException} if the supplied percentage cannot be set. |
| setPercentage | | public void setPercentage(long percentage)(Code) | | Sets the value of the percentage property. This method is the
same as the
Progress.setPercentage(int) one, with the only difference that
it accepts a long parameter. The parameter is converted to an
int and the corresponding method is called.
Parameters:
percentage - The new value for the percentage property. {@link IllegalArgumentException} if the supplied percentage cannot be set. |
| setTitle | | public void setTitle(String title)(Code) | | Sets the value of the title property. The value is updated only
if the supplied title is different from the current. Also the progress
listeners are notified only if the update actually took place.
Parameters:
title - The new value for the title property. |
| synchronizeFrom | | public void synchronizeFrom(Progress progress)(Code) | | Sets up the synchronization of this progress object from the specified
source. If there was a synchronization link already set up, it is removed.
Once the synchronization is established, the methods that set the core
progress properties do not have any effect - the properties will be correctly
set, but will be overwritten with the next source update.
In order to remove the synchronization link on this progress, just supply
null as the parameter.
Parameters:
progress - A progress object from which to set up the synchronization,or null to cancel the synchronization. |
|
|
|