Interface MessageRecorder

  • All Known Implementing Classes:
    AbstractRecorder, ListRecorder, LoggerRecorder, PrintStreamRecorder

    public interface MessageRecorder
    Records warnings and errors during the processing of a task. Contexts can be added and removed. This allows one to collect more than one warning/error, keep processing, and then the code that initiated the processing can determine what to do with the warnings/errors if they exist.

    A typical usage might be:

    
        void process(MessageRecorder msgRecorder) {
            msgRecorder.pushContextName(getName());
            try {
                  // prcess task
                  ....
                  // need to generate warning message
                  String msg = ...
                  msgRecorder.reportWarning(msg);
                  ....
            } finally {
                  msgRecorder.popContextName();
            }
        }
     

    Implementations must provide the means for extracting the error/warning messages.

    Code that is processing should not catch the MessageRecorder.RTException. This Exception is thrown by the MessageRecorder when too many errors have been seen. Throwing this Exception is the mechanism used to stop processing and return to the initiating code. The initiating code should expect to catch the MessageRecorder.RTException Exception.

    
        void initiatingCode(MessageRecorder msgRecorder) {
          // get MessageRecorder implementation
          MessageRecorder msgRecorder = ....
          try {
              processingCode(msgRecorder);
          } catch (MessageRecorder.RTException mrex) {
              // empty
          }
          if (msgRecorder.hasErrors()) {
              // handle errors
          } else if (msgRecorder.hasWarnings()) {
              // handle warnings
          }
        }
     

    The reporting methods all have variations that take an "info" Object. This can be used to pass something, beyond a text message, from the point of warning/error to the initiating code.

    Concerning logging, it is a rule that a message, if logged by the code creating the MessageRecorder implementation, is logged at is reporting level, errors are logged at the error log level, warnings at the warning level and info at the info level. This allows the client code to "know" what log level their messages might appear at.

    Author:
    Richard M. Emberson
    • Method Detail

      • clear

        void clear()
        Clear all context, warnings and errors from the MessageRecorder. After calling this method the MessageRecorder implemenation should be in the same state as if it were just constructed.
      • getStartTimeMillis

        long getStartTimeMillis()
        Get the time when the MessageRecorder was created or the last time that the clear method was called.
        Returns:
        the start time
      • getRunTimeMillis

        long getRunTimeMillis()
        How long the MessageRecorder has been running since it was created or the last time clear was called.
      • hasInformation

        boolean hasInformation()
        Returns true if there are one or more informational messages.
        Returns:
        true if there are one or more infos.
      • hasWarnings

        boolean hasWarnings()
        Returns true if there are one or more warning messages.
        Returns:
        true if there are one or more warnings.
      • hasErrors

        boolean hasErrors()
        Returns true if there are one or more error messages.
        Returns:
        true if there are one or more errors.
      • getContext

        String getContext()
        Get the current context string.
        Returns:
        the context string.
      • pushContextName

        void pushContextName​(String name)
        Add the name parameter to the current context.
        Parameters:
        name -
      • popContextName

        void popContextName()
        Remove the last context name added.
      • throwRTException

        void throwRTException()
                       throws RecorderException
        This simply throws a RTException. A client calls this if 1) there is one or more error messages reported and 2) the client wishes to stop processing. Implementations of this method should only throw the RTException if there have been errors reported - if there are no errors, then this method does nothing.
        Throws:
        RecorderException
      • reportError

        void reportError​(Exception ex,
                         Object info)
                  throws RecorderException
        Add an Exception and extra informaton.
        Parameters:
        ex - the Exception added.
        info - extra information (not meant to be part of printed message)
        Throws:
        RecorderException - if too many error messages have been added.
      • reportError

        void reportError​(String msg)
                  throws RecorderException
        Add an error message.
        Parameters:
        msg - the text of the error message.
        Throws:
        RecorderException - if too many error messages have been added.
      • reportError

        void reportError​(String msg,
                         Object info)
                  throws RecorderException
        Add an error message and extra information.
        Parameters:
        msg - the text of the error message.
        info - extra information (not meant to be part of printed message)
        Throws:
        RecorderException - if too many error messages have been added.
      • reportWarning

        void reportWarning​(String msg)
        Add a warning message.
        Parameters:
        msg - the text of the warning message.
      • reportWarning

        void reportWarning​(String msg,
                           Object info)
        Add a warning message and extra information.
        Parameters:
        msg - the text of the warning message.
        info - extra information (not meant to be part of printed message)
      • reportInfo

        void reportInfo​(String msg)
        Add an informational message.
        Parameters:
        msg - the text of the info message.
      • reportInfo

        void reportInfo​(String msg,
                        Object info)
        Add an informational message and extra information.
        Parameters:
        msg - the text of the info message.
        info - extra information (not meant to be part of printed message)