Interface IProgressReporter

All Superinterfaces:
Comparable
All Known Implementing Classes:
ProgressReporter
public interface IProgressReporter extends Comparable
The interface for a progress reporter

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addListener(IProgressReporterListener listener)
     
    void
    appendDetailMessage(String detailMessage)
    Appends the detail message to this reporter.
    void
    cancel()
    Marks this reporter as canceled and notify any listeners about it
    void
    dispose()
    Disposes any resources or listeners that this reporter has references to or otherwise is responsible for
    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
    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 cancelCloses)
     
    void
    setDone()
    Indicates that the associated process is done
    void
    setErrorMessage(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(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(String name)
     
    void
    setObjectData(Object objectData)
    An arbitrary object reference that can be used to further identify the reporter.
    void
    setPercentage(int percentage, 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(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, String message)
    Sets the selection to the progress reporter; this is used when a traditional min, max, selection is specified.
    void
    setTitle(String title)
    Sets the title that may be used by a UI component.

    Methods inherited from interface Comparable

    compareTo

  • Method Details

    • setReporterType

      void setReporterType(String reporterType)
      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
      Parameters:
      reporterType -

    • dispose

      void dispose()
      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

    • getProgressReport

      IProgressReport getProgressReport()
      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.
      Returns:

    • setSelection

      void setSelection(int selection, String message)
      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

      Parameters:
      selection -
      message -

    • setPercentage

      void setPercentage(int percentage, 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.

      NOTE: this percentage value also synchronize the selection value of this reporter

      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

      void setIndeterminate(boolean isIndeterminate)
      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
      Parameters:
      isIndeterminate -

    • setDone

      void setDone()
      Indicates that the associated process is done

    • setMinimum

      void setMinimum(int min)
      Parameters:
      min - the min to set

    • setMaximum

      void setMaximum(int max)
      Parameters:
      max - the max to set

    • cancel

      void cancel()
      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

    • retry

      void retry()
      Notifies listener that a retry is requested

    • setCancelAllowed

      void setCancelAllowed(boolean cancelAllowed)
      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

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

    • setCancelCloses

      void setCancelCloses(boolean cancelCloses)

    • getCancelCloses

      boolean getCancelCloses()

    • addListener

      void addListener(IProgressReporterListener listener)
      Parameters:
      listener -

    • removeListener

      void removeListener(IProgressReporterListener listener)
      Parameters:
      listener -

    • setName

      void setName(String name)
      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

      void setTitle(String title)
      Sets the title that may be used by a UI component. A typical usage would be for the title of a progress dialog
      Parameters:
      title - the title to set

    • setImage

      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

      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

      Parameters:
      image - the image; may be null

    • setErrorMessage

      void setErrorMessage(String errorMessage)
      Sets an error message to this reporter; subsequently isInErrorState will be set to true
      Parameters:
      errorMessage -
      See Also:
      • invalid reference 
        #reInit()

    • setMessage

      void setMessage(String message)
      Sets the current status message for this reporter; this is typically used to display a message at each incremental update
      Parameters:
      message - a textual message

    • appendDetailMessage

      void appendDetailMessage(String detailMessage)
      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

      Parameters:
      detailMessage -

    • setRetryAllowed

      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
      Parameters:
      isRetryAllowed - true if the user should be prompted to retry when an error has occurred; false otherwise. Default is false

    • setObjectData

      void setObjectData(Object objectData)
      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.
      Parameters:
      objectData - the objectData to set

    • getMessageHistory

      IMessage[] getMessageHistory()
      Returns an array of IMessage's that has been generated since the reporter was created
      Returns: