Interface IProgressReporter

  • All Superinterfaces:
    java.lang.Comparable
    All Known Implementing Classes:
    ProgressReporter

    public interface IProgressReporter
    extends java.lang.Comparable
    The interface for a progress reporter
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      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
      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​(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 interface java.lang.Comparable

        compareTo
    • Method Detail

      • setReporterType

        void setReporterType​(java.lang.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,
                          java.lang.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,
                           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.

        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:
        addListener(IProgressReporterListener), removeListener(IProgressReporterListener)
      • setCancelCloses

        void setCancelCloses​(boolean cancelCloses)
      • getCancelCloses

        boolean getCancelCloses()
      • setName

        void setName​(java.lang.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​(java.lang.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​(java.lang.String errorMessage)
        Sets an error message to this reporter; subsequently isInErrorState will be set to true
        Parameters:
        errorMessage -
        See Also:
        #reInit()
      • setMessage

        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
        Parameters:
        message - a textual message
      • appendDetailMessage

        void appendDetailMessage​(java.lang.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​(java.lang.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: