org.gudy.azureus2.ui.swt.progress
Class ProgressReporter

java.lang.Object
  org.gudy.azureus2.ui.swt.progress.ProgressReporter

All Implemented Interfaces:

java.lang.Comparable, IProgressReportConstants, IProgressReporter

public class ProgressReporter
extends java.lang.Object
implements IProgressReporter, IProgressReportConstants

A implementation of 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

The listeners will be passed an immutable progress report 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 [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.

Author:

knguyen

Nested Class Summary

class

ProgressReporter.ProgressReport An immutable object containing all interesting values in a ProgressReporter.

Field Summary

Fields inherited from interface org.gudy.azureus2.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

protected	ProgressReporter(ProgressReportingManager manager) Construct a ProgressReporter; the returned instance is initialized with the proper ID
protected	ProgressReporter(ProgressReportingManager _manager, java.lang.String name) Construct a ProgressReporter with the given name; the returned instance would have been initialized with the proper ID

Method Summary

void	addListener(IProgressReporterListener listener)
void	appendDetailMessage(java.lang.String detailMessage) Appends the detail message to this reporter.
void	cancel() Marks this reporter as canceled and notify any listeners about it
int	compareTo(java.lang.Object obj) Numerically compare by reporter ID's
void	dispose() Disposes any resources or listeners that this reporter has references to or otherwise is responsible for
boolean	equals(java.lang.Object obj) Reporters are equal iif they have the same ID
boolean	getCancelCloses()
IMessage[]	getMessageHistory() Returns an array of IMessage's that has been generated since the reporter was created
IProgressReport	getProgressReport() Returns an IProgressReport which is a snapshot of this reporter
int	hashCode() Hashcode and ID are the same
void	removeListener(IProgressReporterListener listener)
void	retry() Notifies listener that a retry is requested
void	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 done
void	setErrorMessage(java.lang.String errorMessage) Sets an error message to this reporter; subsequently isInErrorState will be set to true
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 reporter
void	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 update
void	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 the percentage 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 error
void	setSelection(int selection, java.lang.String message) Sets the selection 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.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ProgressReporter

protected ProgressReporter(ProgressReportingManager manager)

Construct a ProgressReporter; the returned instance is initialized with the proper ID

ProgressReporter

protected ProgressReporter(ProgressReportingManager _manager,
                           java.lang.String name)

Construct a ProgressReporter with the given name; 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 interface IProgressReporter

dispose

public void dispose()

Description copied from interface: IProgressReporter

Disposes any resources or listeners that this reporter has references to or otherwise is responsible for

Also removes it from the global ProgressReportingManager so that any subsequent event from this reporter is no longer forwarded

Specified by:

dispose in interface IProgressReporter

setSelection

public void setSelection(int selection,
                         java.lang.String message)

Description copied from interface: IProgressReporter

Sets the selection 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 interface IProgressReporter

setPercentage

public void setPercentage(int percentage,
                          java.lang.String message)

Description copied from interface: IProgressReporter

Sets the percentage 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 interface IProgressReporter

Parameters:

percentage - an integer from 0-100

message - 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 interface IProgressReporter

setDone

public void setDone()

Description copied from interface: IProgressReporter

Indicates that the associated process is done

Specified by:

setDone in interface IProgressReporter

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 interface IProgressReporter

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's null)or show the regular message in its place

Additionally 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 interface IProgressReporter

setMinimum

public void setMinimum(int min)

Specified by:

setMinimum in interface IProgressReporter

Parameters:

min - the min to set

setMaximum

public void setMaximum(int max)

Specified by:

setMaximum in interface IProgressReporter

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 it

NOTE: 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 interface IProgressReporter

retry

public void retry()

Description copied from interface: IProgressReporter

Notifies listener that a retry is requested

Specified by:

retry in interface IProgressReporter

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 to true 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 interface IProgressReporter

Parameters:

cancelAllowed - true to indicate that this process may solicit a REPORT_TYPE_CANCEL input from the user; default is false

See Also:

IProgressReporter.addListener(IProgressReporterListener), IProgressReporter.removeListener(IProgressReporterListener)

setName

public void setName(java.lang.String name)

Specified by:

setName in interface IProgressReporter

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 be null.

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 interface IProgressReporter

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 reporter

NOTE: 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 interface IProgressReporter

Parameters:

image - the image; may be null

setErrorMessage

public void setErrorMessage(java.lang.String errorMessage)

Description copied from interface: IProgressReporter

Sets an error message to this reporter; subsequently isInErrorState will be set to true

Specified by:

setErrorMessage in interface IProgressReporter

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 interface IProgressReporter

getCancelCloses

public boolean getCancelCloses()

Specified by:

getCancelCloses in interface IProgressReporter

setCancelCloses

public void setCancelCloses(boolean b)

Specified by:

setCancelCloses in interface IProgressReporter

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 through ProgressReporter.ProgressReport.objectData so that it can be used to pass information to and from the listeners.

Specified by:

setObjectData in interface IProgressReporter

Parameters:

objectData - the objectData to set

getMessageHistory

public IMessage[] getMessageHistory()

Description copied from interface: IProgressReporter

Returns an array of IMessage's that has been generated since the reporter was created

Specified by:

getMessageHistory in interface IProgressReporter

Returns:

addListener

public void addListener(IProgressReporterListener listener)

Specified by:

addListener in interface IProgressReporter

removeListener

public void removeListener(IProgressReporterListener listener)

Specified by:

removeListener in interface IProgressReporter

compareTo

public int compareTo(java.lang.Object obj)

Numerically compare by reporter ID's

Specified by:

compareTo in interface java.lang.Comparable

equals

public boolean equals(java.lang.Object obj)

Reporters are equal iif they have the same ID

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Hashcode and ID are the same

Overrides:

hashCode in class java.lang.Object

getProgressReport

public IProgressReport getProgressReport()

Description copied from interface: IProgressReporter

Returns an IProgressReport which is a snapshot of this reporter

NOTE: 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 interface IProgressReporter

Returns: