Class ProgressReporter
- java.lang.Object
-
- com.biglybt.ui.swt.progress.ProgressReporter
-
- All Implemented Interfaces:
IProgressReportConstants
,IProgressReporter
,java.lang.Comparable
public class ProgressReporter extends java.lang.Object implements IProgressReporter, IProgressReportConstants
A implementation ofIProgressReporter
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
The listeners will be passed an immutable progress reportProgressReportingManager
followed by a notification to all registered listeners of this reporterProgressReporter.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()
andretry()
. These commands are enabled by callingsetCancelAllowed(boolean)
orsetRetryAllowed(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 [
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 Classes Modifier and Type Class Description class
ProgressReporter.ProgressReport
An immutable object containing all interesting values in aProgressReporter
.
-
Field Summary
Fields Modifier and Type Field Description private boolean
cancelCloses
private java.lang.String
detailMessage
private java.lang.String
errorMessage
private int
ID
An instance id for this reporter that is guaranteed to be unique within this same sessionprivate org.eclipse.swt.graphics.Image
image
private boolean
isActive
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
isCancelAllowed
private boolean
isCanceled
private boolean
isDisposed
private boolean
isDone
private boolean
isIndeterminate
private boolean
isInErrorState
private boolean
isPercentageInUse
private boolean
isRetryAllowed
private IProgressReport
latestProgressReport
private int
latestReportType
private ProgressReportingManager
manager
private int
maximum
private java.lang.String
message
private CopyOnWriteList
messageHistory
Accumulates the detail messages in a Listprivate int
messageHistoryLimit
private int
minimum
private java.lang.String
name
private java.lang.Object
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 insufficientprivate int
percentage
private CopyOnWriteList
reporterListeners
private java.lang.String
reporterType
private int
selection
private java.lang.String
title
-
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
Constructors Modifier Constructor Description protected
ProgressReporter(ProgressReportingManager manager)
Construct aProgressReporter
; the returned instance is initialized with the proper IDprotected
ProgressReporter(ProgressReportingManager _manager, java.lang.String name)
Construct aProgressReporter
with the givenname
; the returned instance would have been initialized with the proper ID
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addListener(IProgressReporterListener listener)
private void
addToMessageHistory(java.lang.String value, int type)
Create and add anIMessage
to the message historyvoid
appendDetailMessage(java.lang.String detailMessage)
Appends the detail message to this reporter.void
cancel()
Marks this reporter as canceled and notify any listeners about itint
compareTo(java.lang.Object obj)
Numerically compare by reporter ID'svoid
dispose()
Disposes any resources or listeners that this reporter has references to or otherwise is responsible forboolean
equals(java.lang.Object obj)
Reporters are equal iif they have the same IDboolean
getCancelCloses()
IMessage[]
getMessageHistory()
Returns an array ofIMessage
's that has been generated since the reporter was createdIProgressReport
getProgressReport()
Returns anIProgressReport
which is a snapshot of this reporterint
hashCode()
Hashcode and ID are the sameprivate 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(java.lang.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(java.lang.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
setName(java.lang.String name)
void
setObjectData(java.lang.Object objectData)
An arbitrary object reference that can be used to further identify the reporter.void
setPercentage(int percentage, java.lang.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(java.lang.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, java.lang.String message)
Sets theselection
to the progress reporter; this is used when a traditional min, max, selection is specified.void
setTitle(java.lang.String title)
Sets the title that may be used by a UI component.private boolean
shouldIgnore()
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 Detail
-
manager
private ProgressReportingManager manager
-
ID
private int ID
An 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
private java.lang.String title
-
message
private java.lang.String message
-
messageHistory
private CopyOnWriteList 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
private java.lang.String detailMessage
-
errorMessage
private java.lang.String errorMessage
-
name
private java.lang.String name
-
image
private org.eclipse.swt.graphics.Image image
-
reporterType
private java.lang.String reporterType
-
latestProgressReport
private IProgressReport latestProgressReport
-
reporterListeners
private CopyOnWriteList reporterListeners
-
objectData
private java.lang.Object 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 isActive
If 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 Detail
-
ProgressReporter
protected ProgressReporter(ProgressReportingManager manager)
Construct aProgressReporter
; the returned instance is initialized with the proper ID
-
ProgressReporter
protected ProgressReporter(ProgressReportingManager _manager, java.lang.String name)
Construct aProgressReporter
with the givenname
; the returned instance would have been initialized with the proper ID- Parameters:
name
-
-
-
Method Detail
-
setReporterType
public void setReporterType(java.lang.String reporterType)
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
-
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
-
notifyListeners
private void notifyListeners(IProgressReport report)
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
public void setSelection(int selection, java.lang.String message)
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
-
setPercentage
public void setPercentage(int percentage, java.lang.String message)
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
-
setDone
public void setDone()
Description copied from interface:IProgressReporter
Indicates that the associated process is done- Specified by:
setDone
in interfaceIProgressReporter
-
setMessage
public void setMessage(java.lang.String message)
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
public void appendDetailMessage(java.lang.String detailMessage)
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
-
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:
IProgressReporter.addListener(IProgressReporterListener)
,IProgressReporter.removeListener(IProgressReporterListener)
-
setName
public void setName(java.lang.String name)
- 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
public void setTitle(java.lang.String title)
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
public void setErrorMessage(java.lang.String errorMessage)
Description copied from interface:IProgressReporter
Sets an error message to this reporter; subsequentlyisInErrorState
will be set totrue
- Specified by:
setErrorMessage
in interfaceIProgressReporter
- See Also:
#reInit()
-
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
private void addToMessageHistory(java.lang.String value, int type)
Create and add anIMessage
to the message history- Parameters:
value
-type
-
-
setObjectData
public void setObjectData(java.lang.Object objectData)
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
public IMessage[] 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
public void addListener(IProgressReporterListener listener)
- Specified by:
addListener
in interfaceIProgressReporter
-
removeListener
public void removeListener(IProgressReporterListener listener)
- Specified by:
removeListener
in interfaceIProgressReporter
-
compareTo
public int compareTo(java.lang.Object obj)
Numerically compare by reporter ID's- Specified by:
compareTo
in interfacejava.lang.Comparable
-
equals
public boolean equals(java.lang.Object obj)
Reporters are equal iif they have the same ID- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
Hashcode and ID are the same- Overrides:
hashCode
in classjava.lang.Object
-
getProgressReport
public IProgressReport 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:
-
-