Class ProgressReporter
- All Implemented Interfaces:
IProgressReportConstants
,IProgressReporter
,Comparable
IProgressReporter
Any process wishing to participate in providing global progress indication can instantiate this class and simply use the available methods so set values or issue a command
When ever any state changes in this reporter a notification will be sent to the global
reporting manager ProgressReportingManager
followed by a notification to all
registered listeners of this reporter
ProgressReporter.ProgressReport
which
represents a snapshot of all the public properties contained in this reporter; inspecting the
ProgressReport is the only way a listener can query the properties of this reporter. This pattern
allows the ProgressReporter to continue and process requests by not having to thread lock all public
methods. Additionally, the listeners are guaranteed a consistent snapshot of the reporter.
This reporter also has the capability to receive loop back commands from a listener for actions such like
cancel()
and retry()
. These commands are enabled by calling
setCancelAllowed(boolean)
or setRetryAllowed(boolean)
.
The listener only initiates these actions by sending a notification back to the owner of the reporter;
it is up the to owner to perform the actual act of canceling or retrying.
A typical life cycle of the ProgresReporter as seen from an owner is as follows (an owner is defined as the process that created the reporter):
- Create ProgressReporter
- Set initial properties
- Register a listener to the reporter to respond to loopback notifications (optional)
- Update the reporter
- Set selection or percentage [
setSelection(int, String)
,setPercentage(int, String)
] - Set message [
setMessage(String)
] - ...
- Repeat until done
- Set done [
setDone()
] - Then optionally Dispose of the reporter [
invalid reference
ProgressReporter#dispose(Object)
.
In addition to internal clean-ups, calling dispose(Object) will effectively remove the reporter from the history stack of the reporting manager and no more messages from this reporter will be processed.
Once a reporter is created and any property in the reporter is set the global reporting manager is notified; at which point any listener listening to the manager is forwarded this reporter. The manager listener may decide to display this reporter in a UI element, may register specific listeners to this reporter, may query its properties and take action, or can simply monitor it for such functions as logging.
This implementation is non-intrusive to the owner process and so provides existing processes the ability to participate in global progress indication without significant modification to the underlying processes.-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionclass
An immutable object containing all interesting values in aProgressReporter
. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate boolean
private String
private String
private int
An instance id for this reporter that is guaranteed to be unique within this same sessionprivate org.eclipse.swt.graphics.Image
private boolean
If any of the following states have been reached then the reporter is considered inactive:isDisposed
==true
isDone
==true
isInErrorState
==true
isCanceled
==true
private boolean
private boolean
private boolean
private boolean
private boolean
private boolean
private boolean
private boolean
private IProgressReport
private int
private ProgressReportingManager
private int
private String
private CopyOnWriteList
Accumulates the detail messages in a Listprivate int
private int
private String
private Object
An arbitrary object reference that can be used by the owner of theProgressReporter
and its listeners to share additional information should the current implementation be insufficientprivate int
private CopyOnWriteList
private String
private int
private String
Fields inherited from interface com.biglybt.ui.swt.progress.IProgressReportConstants
AUTO_CLOSE, BORDER, MANAGER_EVENT_ADDED, MANAGER_EVENT_REMOVED, MANAGER_EVENT_UPDATED, MODAL, MSG_TYPE_ERROR, MSG_TYPE_INFO, MSG_TYPE_LOG, NONE, REPORT_TYPE_CANCEL, REPORT_TYPE_DISPOSED, REPORT_TYPE_DONE, REPORT_TYPE_ERROR, REPORT_TYPE_INIT, REPORT_TYPE_MODE_CHANGE, REPORT_TYPE_PROPERTY_CHANGED, REPORT_TYPE_RETRY, REPORTER_TYPE_DEFAULT, REPORTER_VISIBILITY_SYSTEM, REPORTER_VISIBILITY_USER, RETVAL_OK, RETVAL_OK_TO_DISPOSE, SHOW_TOOLBAR, STANDALONE
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
ProgressReporter
(ProgressReportingManager manager) Construct aProgressReporter
; the returned instance is initialized with the proper IDprotected
ProgressReporter
(ProgressReportingManager _manager, String name) Construct aProgressReporter
with the givenname
; the returned instance would have been initialized with the proper ID -
Method Summary
Modifier and TypeMethodDescriptionvoid
addListener
(IProgressReporterListener listener) private void
addToMessageHistory
(String value, int type) Create and add anIMessage
to the message historyvoid
appendDetailMessage
(String detailMessage) Appends the detail message to this reporter.void
cancel()
Marks this reporter as canceled and notify any listeners about itint
Numerically compare by reporter ID'svoid
dispose()
Disposes any resources or listeners that this reporter has references to or otherwise is responsible forboolean
Reporters are equal iif they have the same IDboolean
IMessage[]
Returns an array ofIMessage
's that has been generated since the reporter was createdReturns anIProgressReport
which is a snapshot of this reporterint
hashCode()
Hashcode and ID are the sameprivate void
private void
notifyListeners
(IProgressReport report) Notifies registered listener that an event has occurred.private void
reInit()
Resets this reporter to its initial states such that values are reset to defaultvoid
removeListener
(IProgressReporterListener listener) void
retry()
Notifies listener that a retry is requestedvoid
setCancelAllowed
(boolean cancelAllowed) Sets whether the process associated with this reporter is allowed to be canceled by the user.void
setCancelCloses
(boolean b) void
setDone()
Indicates that the associated process is donevoid
setErrorMessage
(String errorMessage) Sets an error message to this reporter; subsequentlyisInErrorState
will be set totrue
void
setImage
(org.eclipse.swt.graphics.Image image) Sets the image corresponding to this reporter; this image may be used by the UI to decorate this reportervoid
setIndeterminate
(boolean isIndeterminate) Set this reporter into indeterminate mode; use this when an accurate ratio of amount of work done vs.void
setMaximum
(int max) void
setMessage
(String message) Sets the current status message for this reporter; this is typically used to display a message at each incremental updatevoid
setMinimum
(int min) void
void
setObjectData
(Object objectData) An arbitrary object reference that can be used to further identify the reporter.void
setPercentage
(int percentage, String message) Sets thepercentage
value to the progress reporter; this is used when a simple percentage is specified as opposed to setting min, max, and selection.void
setReporterType
(String reporterType) Sets the type of a reporter.void
setRetryAllowed
(boolean retryOnError) This is a hint to any UI components displaying this reporter to determine if the user should be prompted to retry on errorvoid
setSelection
(int selection, String message) Sets theselection
to the progress reporter; this is used when a traditional min, max, selection is specified.void
Sets the title that may be used by a UI component.private boolean
A convenience method to return whether this reporter should ignore subsequent calls to its accessor methods.private void
updateAndNotify
(int eventType) Updates and notifies listeners
-
Field Details
-
manager
-
ID
private int IDAn instance id for this reporter that is guaranteed to be unique within this same session -
minimum
private int minimum -
maximum
private int maximum -
selection
private int selection -
percentage
private int percentage -
latestReportType
private int latestReportType -
isIndeterminate
private boolean isIndeterminate -
isDone
private boolean isDone -
isPercentageInUse
private boolean isPercentageInUse -
isCancelAllowed
private boolean isCancelAllowed -
isCanceled
private boolean isCanceled -
isRetryAllowed
private boolean isRetryAllowed -
isInErrorState
private boolean isInErrorState -
isDisposed
private boolean isDisposed -
title
-
message
-
messageHistory
Accumulates the detail messages in a ListThis is for when a listener starts listening to this reporter after it has started running; upon initialization the listener may query this list to get all messages sent up to that point.
-
detailMessage
-
errorMessage
-
name
-
image
private org.eclipse.swt.graphics.Image image -
reporterType
-
latestProgressReport
-
reporterListeners
-
objectData
An arbitrary object reference that can be used by the owner of theProgressReporter
and its listeners to share additional information should the current implementation be insufficient -
messageHistoryLimit
private int messageHistoryLimit -
isActive
private boolean isActiveIf any of the following states have been reached then the reporter is considered inactive:isDisposed
==true
isDone
==true
isInErrorState
==true
isCanceled
==true
-
cancelCloses
private boolean cancelCloses
-
-
Constructor Details
-
ProgressReporter
Construct aProgressReporter
; the returned instance is initialized with the proper ID -
ProgressReporter
Construct aProgressReporter
with the givenname
; the returned instance would have been initialized with the proper ID- Parameters:
name
-
-
-
Method Details
-
setReporterType
Description copied from interface:IProgressReporter
Sets the type of a reporter. This is a user defined property and no duplication check is ensured. This optional property can be used to identify particular types of reports so that report consumers have a way to ignore uninteresting report types- Specified by:
setReporterType
in interfaceIProgressReporter
- Parameters:
reporterType
-
-
dispose
public void dispose()Description copied from interface:IProgressReporter
Disposes any resources or listeners that this reporter has references to or otherwise is responsible forAlso removes it from the global
ProgressReportingManager
so that any subsequent event from this reporter is no longer forwarded- Specified by:
dispose
in interfaceIProgressReporter
-
reInit
private void reInit()Resets this reporter to its initial states such that values are reset to defaultAn appropriate use for this is when a process is restarting or retrying; this allows an owning process to keep on using the same instance of this reporter without having to create and dispatch a new one
-
initMessageHistory
private void initMessageHistory() -
notifyListeners
Notifies registered listener that an event has occurred. Subsequently a listener may be removed if it returns the value ofRETVAL_OK_TO_DISPOSE
; this optimization is designed to prevent dangling/orphaned listeners, and also reduces the number of listeners to notify upon the next event -
updateAndNotify
private void updateAndNotify(int eventType) Updates and notifies listeners- Parameters:
REPORT_TYPE
-
-
setSelection
Description copied from interface:IProgressReporter
Sets theselection
to the progress reporter; this is used when a traditional min, max, selection is specified.NOTE: this selection value also synchronize the
percentage
value of this reporter- Specified by:
setSelection
in interfaceIProgressReporter
- Parameters:
selection
-message
-
-
setPercentage
Description copied from interface:IProgressReporter
Sets thepercentage
value to the progress reporter; this is used when a simple percentage is specified as opposed to setting min, max, and selection.NOTE: this percentage value also synchronize the
selection
value of this reporter- Specified by:
setPercentage
in interfaceIProgressReporter
- Parameters:
percentage
- an integer from 0-100message
- a textual message to display;null
to leave the previous message untouched, empty String to clear any previous message
-
setIndeterminate
public void setIndeterminate(boolean isIndeterminate) Description copied from interface:IProgressReporter
Set this reporter into indeterminate mode; use this when an accurate ratio of amount of work done vs. total amount of work can not be calculated- Specified by:
setIndeterminate
in interfaceIProgressReporter
- Parameters:
isIndeterminate
-
-
setDone
public void setDone()Description copied from interface:IProgressReporter
Indicates that the associated process is done- Specified by:
setDone
in interfaceIProgressReporter
-
setMessage
Description copied from interface:IProgressReporter
Sets the current status message for this reporter; this is typically used to display a message at each incremental update- Specified by:
setMessage
in interfaceIProgressReporter
- Parameters:
message
- a textual message
-
appendDetailMessage
Description copied from interface:IProgressReporter
Appends the detail message to this reporter. This is typically a more verbose message that is optionally displayed by the UI. This is an optional property so UI components displaying this can decide to show nothing for it (if it'snull
)or show the regular message in its placeAdditionally this is an appending message so that reporters can send smaller units of the message rather than having to store and send the entire (and ever increasing) messages for each update
- Specified by:
appendDetailMessage
in interfaceIProgressReporter
- Parameters:
detailMessage
-
-
setMinimum
public void setMinimum(int min) - Specified by:
setMinimum
in interfaceIProgressReporter
- Parameters:
min
- the min to set
-
setMaximum
public void setMaximum(int max) - Specified by:
setMaximum
in interfaceIProgressReporter
- Parameters:
max
- the max to set
-
cancel
public void cancel()Description copied from interface:IProgressReporter
Marks this reporter as canceled and notify any listeners about itNOTE: This is only a hint back to the processes listening to this reporter; it is up to that process to determine the correct course of action in response to this flag
- Specified by:
cancel
in interfaceIProgressReporter
-
retry
public void retry()Description copied from interface:IProgressReporter
Notifies listener that a retry is requested- Specified by:
retry
in interfaceIProgressReporter
-
setCancelAllowed
public void setCancelAllowed(boolean cancelAllowed) Description copied from interface:IProgressReporter
Sets whether the process associated with this reporter is allowed to be canceled by the user. This serves as a hint to the progress manager handling this reporter. If set totrue
the manager may enable a UI component allowing the user to cancel the associated process if appropriate.The holder of this reporter can register a listener to receive the cancel event
- Specified by:
setCancelAllowed
in interfaceIProgressReporter
- Parameters:
cancelAllowed
-true
to indicate that this process may solicit aREPORT_TYPE_CANCEL
input from the user; default isfalse
- See Also:
-
setName
- Specified by:
setName
in interfaceIProgressReporter
- Parameters:
name
- a textual name to identify the process this reporter represents; need not be unique (should not be used as a lookup key), and may benull
.
-
setTitle
Description copied from interface:IProgressReporter
Sets the title that may be used by a UI component. A typical usage would be for the title of a progress dialog- Specified by:
setTitle
in interfaceIProgressReporter
- Parameters:
title
- the title to set
-
setImage
public void setImage(org.eclipse.swt.graphics.Image image) Description copied from interface:IProgressReporter
Sets the image corresponding to this reporter; this image may be used by the UI to decorate this reporterNOTE: Though not strictly required (nor enforced) the image should be 32X32 pixels with transparency. If not then cropping or enlargement may be applied as required by the particular UI
- Specified by:
setImage
in interfaceIProgressReporter
- Parameters:
image
- the image; may benull
-
setErrorMessage
Description copied from interface:IProgressReporter
Sets an error message to this reporter; subsequentlyisInErrorState
will be set totrue
- Specified by:
setErrorMessage
in interfaceIProgressReporter
- Parameters:
errorMessage
-- See Also:
-
setRetryAllowed
public void setRetryAllowed(boolean retryOnError) Description copied from interface:IProgressReporter
This is a hint to any UI components displaying this reporter to determine if the user should be prompted to retry on error- Specified by:
setRetryAllowed
in interfaceIProgressReporter
-
shouldIgnore
private boolean shouldIgnore()A convenience method to return whether this reporter should ignore subsequent calls to its accessor methods. When a reporter has reached this state listeners usually make the assumption that there will be no more changes to any properties in this reporter. The use of this method is intended to provide a more consistent state for the reporter; without this check a listener may have reference to a reporter that is marked asdone
but then a subsequent message says it's at 50% completion. By cutting of the notification here we prevent such ambiguity from occurring for the listeners.If any of the following states have been reached then the reporter can ignore subsequent calls to its accessor methods:
isDisposed
==true
isDone
==true
- Returns:
-
getCancelCloses
public boolean getCancelCloses()- Specified by:
getCancelCloses
in interfaceIProgressReporter
-
setCancelCloses
public void setCancelCloses(boolean b) - Specified by:
setCancelCloses
in interfaceIProgressReporter
-
addToMessageHistory
Create and add anIMessage
to the message history- Parameters:
value
-type
-
-
setObjectData
Description copied from interface:IProgressReporter
An arbitrary object reference that can be used to further identify the reporter. This object is also accessible to listeners of the reporter throughProgressReporter.ProgressReport.objectData
so that it can be used to pass information to and from the listeners.- Specified by:
setObjectData
in interfaceIProgressReporter
- Parameters:
objectData
- the objectData to set
-
getMessageHistory
Description copied from interface:IProgressReporter
Returns an array ofIMessage
's that has been generated since the reporter was created- Specified by:
getMessageHistory
in interfaceIProgressReporter
- Returns:
-
addListener
- Specified by:
addListener
in interfaceIProgressReporter
- Parameters:
listener
-
-
removeListener
- Specified by:
removeListener
in interfaceIProgressReporter
- Parameters:
listener
-
-
compareTo
Numerically compare by reporter ID's- Specified by:
compareTo
in interfaceComparable
-
equals
Reporters are equal iif they have the same ID -
hashCode
public int hashCode()Hashcode and ID are the same -
getProgressReport
Description copied from interface:IProgressReporter
Returns anIProgressReport
which is a snapshot of this reporterNOTE: Each call to this method creates a new snapshot therefore the correct usage pattern is:
IProgressReport report = getProgressReport(); if( report.isDone() == false ){ // Do something { else if( report.isCanceled() == false ){ // Do something else { ...
It may be tempting to use the less verbose pattern by repeatedly calling this method directly such as:if( getProgressReport().isDone == false ){ // Do something { else if( getProgressReport().isCanceled == false ){ // Do something else {
BUT this can produce inconsistent results since each successive call to getProgressReport() is returning a different snapshot.- Specified by:
getProgressReport
in interfaceIProgressReporter
- Returns:
-