Class Messager

  • public class Messager
extends java.lang.Object
    A replacement for System.out, System.err and even the StorageWriter class used to send error messages to the terminal about upgrade progress.

    This class is actually much less than meets the eye. All the Messager class really does is print output to a log / StorageWriter instance (this class inherits StorageWriter), while simultaneously keeping a count on the number of error messages that have been printed.

    The count allows this Tool's main-loops to ask if an error or warning has occured, thereby facilitating exiting the program more gracefully if an error has been printed. The primary value to a Messager over a simple exception throw is that multiple non-fatal errors can be printed before actually exiting the program. It is similar to the Java Compiler Messager - in that as many errors will be printed all at once, rather than expecting the user to receive just one error at a time between each attempt at compiling his code, thereby saving the programmer a significant amount of time! Collating a list of errors to the user about what has occured and report them all (at the end) is the primary feature of the messager.

    Recognizing that most of the classes in The Tool are not 'Helper Classes' at all, means that throwing an exception whenever a problem occurs is not really acceptable. Though several of the errors do involve printing an exception-message, and even its stack-trace, the messager forces the main method loops to take into consideration the end user's Java Virtual Machine, because halting the JVM with an exception throw is quite a bit more severe. Instead returning a null reply, and output explanatory error-text is quite a bit more reasonable.

    Essentially, anywhere this Messager's method's are used, try to envision that exact same error-message print being replaced with a throw new Exception..., and recognize that the surrounding loop body, instead, will continue iterating until too many errors have been logged, or the loop exits and the code attempts to move on to another section of the processing.

    Again, relying on Java's Exception Messages to report errors is a great way to signal a user mistke, but when an application is running, there has to be a more robust and advanced way of dealing with problems of user error, because wasint the user's time repairing one mistake at a time, and then re-running the Upgrader would be a very terrible waste of the end-user's time!


    • Method Detail

      • isVerbose

        🡇  ⇈  ⮫ 
        public static boolean isVerbose()
        Please review the Java code-body (below) to understand what this method does.
        Code:
        Exact Method Body:
         return VERBOSE_PRINT_STEPS;

      • checkPointLog

        🡅  🡇  ⇈  ⮫ 
        public static void checkPointLog()
        Code:
        Exact Method Body:
         String temp = C.toHTML(sw.getString(), true, true, true).replace("\t", "        ");

 try
 {
     // Since log check-points are done after processing a JavaDoc File, this extra 
     // "\n\n" just adds some space after each file has been printed.

     logAppendable.append(temp); // + "\n\n");

     // Clear the internal storage buffer.  Otherwise all the log-text would be re-written
     // again at the next log check-point!

     sw.erase();
 }

 catch (Exception e)
 {
     Messager.setCurrentFileName("User Provided Log", null);

     Messager.assertFailGeneralPurpose(
         e,
         "Exception thrown while attempting to write to User-Provided Appendable-Log",
         null
     );
 }

      • setCurrentFileName

        🡅  🡇  ⇈  ⮫ 
        public static void setCurrentFileName​(java.lang.String fName,
                                      java.lang.String fNameKind)
        Code:
        Exact Method Body:
         fileNameKind            = fNameKind;
 fileName                = fName;
 printedFirstFileName    = false;
 indentation             = 4;

 // Also clear the detail section
 detailSection           = null;
 printedFirstDetails     = false;

      • setCurrentDetailSection

        🡅  🡇  ⇈  ⮫ 
        public static void setCurrentDetailSection​(ReflHTML<?> detailSection)
        Code:
        Exact Method Body:
         Messager.detailSection              = detailSection;
 Messager.printedFirstDetails        = false;
 Messager.topDescriptionAsDetails    = false;
 Messager.indentation                = 8;

      • setTopDescriptionSection

        🡅  🡇  ⇈  ⮫ 
        public static void setTopDescriptionSection()
        Code:
        Exact Method Body:
         Messager.detailSection              = null;
 Messager.printedFirstDetails        = false;
 Messager.topDescriptionAsDetails    = true;
 Messager.indentation                = 8;

      • hadErrors

        🡅  🡇  ⇈  ⮫ 
        public static boolean hadErrors()
        Allows a user to query the Messager regarding whether any errors have been logged which didn't actually stop the upgrader from continuing.

        NOTE: Many errors can be logged to user-output without actually halting the Upgrade Process. This is done, for efficiency, to allow the developer to read as many mistakes as possible before forcing the developer to start up a new build.

        Any errors that are severe enough to halt the build (for example, file-system I/O errors) simply cannot be taken into account by this method - because they would have already forced the exiting of the Upgrader.
        Returns:
        If there have been errors issued by the Upgrade Processors that did not actually force the Upgrade to halt, this method will return TRUE.

        If no such errors have been encountered, this method returns FALSE
        Code:
        Exact Method Body:
         return errorCount > 0;

      • numErrors

        🡅  🡇  ⇈  ⮫ 
        public static int numErrors()
        Retrieve how many errors have been sent to the Messager. Not all errors will cause the Upgrade Process to exit immediately. This number is often - but not necessarily - zero.
        Returns:
        The number of errors issued to the Messager since the start of the Upgrade.
        Code:
        Exact Method Body:
         return errorCount;

      • numWarnings

        🡅  🡇  ⇈  ⮫ 
        public static int numWarnings()
        Retrieve how many warnings have been sent to the Messager
        Returns:
        The number of warnings issued during the Upgrade Process
        Code:
        Exact Method Body:
         return warningCount;

      • totalErrorsAndWarnings

        🡅  🡇  ⇈  ⮫ 
        public static int totalErrorsAndWarnings()
        Retrieve how many errrors and warnings (both) have been issued to the Messager.
        Returns:
        An integer specifying the total number of errors and warnings.
        Code:
        Exact Method Body:
         return errorCount + warningCount;

      • hadErrorsOrWarnings

        🡅  🡇  ⇈  ⮫ 
        public static boolean hadErrorsOrWarnings()
        Check if there have been any errors or warnings.
        Returns:
        TRUE if there have been any errors or warnings, and FALSE otherwise.
        Code:
        Exact Method Body:
         return (errorCount > 0) || (warningCount > 0);

      • reachedMaxErrorsOrWarnings

        🡅  🡇  ⇈  ⮫ 
        public static boolean reachedMaxErrorsOrWarnings()
        Check if more than 25 errors or warnings have been registered with the Messager.

        NOTE: It is usually better to allow warnings to accrue indefinitely, and focus more dilligently on the error count. With that thought in mind, the method reachedMaxErrors() should be thought of as a "more useful" method.
        Returns:
        TRUE If at least 25 errors and / or warnings have taken place, and FALSE otherwise.
        Code:
        Exact Method Body:
         return totalErrorsAndWarnings() > 25;

      • reachedMaxErrors

        🡅  🡇  ⇈  ⮫ 
        public static boolean reachedMaxErrors()
        Inspects the internal counter which keeps track of how many errors have been registered and printed into this Messager.
        Returns:
        TRUE If at least 25 errors have taken place, and FALSE otherwise.
        Code:
        Exact Method Body:
         return errorCount > 25;

      • warning

        🡅  🡇  ⇈  ⮫ 
        public static void warning​(java.lang.String message,
                           JDUProcessor p)
        Issue a warning to the Messager about any problem that may have cropped up during the upgrade. The Messager will send the text to whatever output mechanism has been specified by the user, and increase the warning count.
        Parameters:
        message - A message to be printed to the Messager's output.
        p - The processor to which the message shall be ascribed when performing the printing.
        Code:
        Exact Method Body:
         warningCount++;
 printHeadingIfNecessary(p);

 sw.println(
     INDENT() + "Warning: " +
     StrIndent.indentAfter2ndLine(message, 4 + indentation, true, true)
 );

      • note

        🡅  🡇  ⇈  ⮫ 
        public static void note​(java.lang.String message,
                        JDUProcessor p)
        Output a note using the Messager about anything that may or may not have happened during the upgrade. The Messager will send the text to whatever output mechanism has been specified by the user.
        Parameters:
        message - A message to be printed to the Messager's output.
        p - The processor to which the message shall be ascribed when performing the printing.
        Code:
        Exact Method Body:
         printHeadingIfNecessary(p);

 sw.println(
     INDENT() + "Note: " +
     StrIndent.indentAfter2ndLine(message, 4 + indentation, true, true)
 );

      • assertFailCheckup

        🡅  🡇  ⇈  ⮫ 
        public static <T> T assertFailCheckup​(java.lang.String message)
        Previously Unreleased. Intended to be used like a Java Assert - meaning programming error that shouldn't occur.
        Type Parameters:
        T - For convenience, this allows a programmer to put a 'return' statement in front of a call to this method. The Java-Compiler is not smart-enough to know that this method is guaranteed to throw. Occasionally this may cause compiler warnings in your code about uninitialized fields and/or variables.

        This method will never actually return anything, and therefore the Java-Compiler will match this Type-Parameter to anything assigned to it.
        Parameters:
        message - The error message
        Returns:
        Nothing - throws a JavaDocError
        Code:
        Exact Method Body:
         JavaDocError jde = new JavaDocError();
 ASSERT_FAIL("Assertion-Checkup Error: ", message, null, computeJDUProcessor(jde));
 throw jde;

      • assertFailHTML

        🡅  🡇  ⇈  ⮫ 
        public static <T> T assertFailHTML​(java.lang.String message,
                                   java.lang.String signature)
        Intended to be used like a Java Assert - meaning programming error that shouldn't occur. Intended for use specifically when parsing HTML.
        Type Parameters:
        T - For convenience, this allows a programmer to put a 'return' statement in front of a call to this method. The Java-Compiler is not smart-enough to know that this method is guaranteed to throw. Occasionally this may cause compiler warnings in your code about uninitialized fields and/or variables.

        This method will never actually return anything, and therefore the Java-Compiler will match this Type-Parameter to anything assigned to it.
        Parameters:
        message - The error message
        signature - This parameter should contain the detail-signature, or 'null'
        Returns:
        Nothing - throws a JavaDocHTMLParseException
        Code:
        Exact Method Body:
         JavaDocHTMLParseException jdhpe = new JavaDocHTMLParseException(message, signature);

 ASSERT_FAIL
     ("Java-Doc HTML Parsing Error: ", message, signature, computeJDUProcessor(jdhpe));

 throw jdhpe;

      • assertFailHTML

        🡅  🡇  ⇈  ⮫ 
        public static <T> T assertFailHTML​(java.lang.Throwable t,
                                   java.lang.String message,
                                   java.lang.String signature)
        Intended to be used like a Java Assert - meaning programming error that shouldn't occur. Intended for use specifically when parsing HTML.
        Type Parameters:
        T - For convenience, this allows a programmer to put a 'return' statement in front of a call to this method. The Java-Compiler is not smart-enough to know that this method is guaranteed to throw. Occasionally this may cause compiler warnings in your code about uninitialized fields and/or variables.

        This method will never actually return anything, and therefore the Java-Compiler will match this Type-Parameter to anything assigned to it.
        Parameters:
        t - The throwable that caused this assert-fail
        message - The error message
        signature - This parameter should contain the detail-signature, or 'null'
        Returns:
        Nothing - throws a JavaDocHTMLParseException
        Code:
        Exact Method Body:
         JavaDocHTMLParseException jdhpe = new JavaDocHTMLParseException(message, t, signature);

 ASSERT_FAIL
     ("Java-Doc HTML Parsing Error: ", t, message, signature, computeJDUProcessor(jdhpe));

 throw jdhpe;

      • assertFailJavaParser

        🡅  🡇  ⇈  ⮫ 
        public static <T> T assertFailJavaParser​(java.lang.String message,
                                         java.lang.String signature)
        Intended to be used like a Java Assert - meaning programming error that shouldn't occur.

        Intended for use specifically when parsing Java Source-Code - using the Java-Parser ™ Source-Code Parsing Package: org.github.javaparser
        Type Parameters:
        T - For convenience, this allows a programmer to put a 'return' statement in front of a call to this method. The Java-Compiler is not smart-enough to know that this method is guaranteed to throw. Occasionally this may cause compiler warnings in your code about uninitialized fields and/or variables.

        This method will never actually return anything, and therefore the Java-Compiler will match this Type-Parameter to anything assigned to it.
        Parameters:
        message - The error message
        signature - This parameter should contain the detail-signature, or 'null'
        Returns:
        Nothing - throws a SourceCodeParseException
        Code:
        Exact Method Body:
         SourceCodeParseException scpe = new SourceCodeParseException(message, signature);

 ASSERT_FAIL(
     "Java-Parser Source-Code Parsing Error: ", message, signature,
     computeJDUProcessor(scpe)
 );

 throw scpe;

      • assertFailJavaParser

        🡅  🡇  ⇈  ⮫ 
        public static <T> T assertFailJavaParser​(java.lang.Throwable t,
                                         java.lang.String message,
                                         java.lang.String signature)
        Intended to be used like a Java Assert - meaning programming error that shouldn't occur.

        Intended for use specifically when parsing Java Source-Code - using the Java-Parser ™ Source-Code Parsing Package: org.github.javaparser
        Type Parameters:
        T - For convenience, this allows a programmer to put a 'return' statement in front of a call to this method. The Java-Compiler is not smart-enough to know that this method is guaranteed to throw. Occasionally this may cause compiler warnings in your code about uninitialized fields and/or variables.

        This method will never actually return anything, and therefore the Java-Compiler will match this Type-Parameter to anything assigned to it.
        Parameters:
        t - The throwable that caused this assert-fail
        message - The error message
        signature - This parameter should contain the detail-signature, or 'null'
        Returns:
        Nothing - throws a SourceCodeParseException
        Code:
        Exact Method Body:
         SourceCodeParseException scpe = new SourceCodeParseException(message, t, signature);

 ASSERT_FAIL(
     "Java-Parser Source-Code Parsing Error: ", t, message, signature,
     computeJDUProcessor(scpe)
 );

 throw scpe;

      • assertFailOracleParser

        🡅  🡇  ⇈  ⮫ 
        public static <T> T assertFailOracleParser​(java.lang.String message,
                                           java.lang.String signature)
        Intended to be used like a Java Assert - meaning programming error that shouldn't occur.

        Intended for use specifically when parsing Java Source-Code - using the Sun-Oracle Source-Code Parsing Package: com.sun.source.tree.
        Type Parameters:
        T - For convenience, this allows a programmer to put a 'return' statement in front of a call to this method. The Java-Compiler is not smart-enough to know that this method is guaranteed to throw. Occasionally this may cause compiler warnings in your code about uninitialized fields and/or variables.

        This method will never actually return anything, and therefore the Java-Compiler will match this Type-Parameter to anything assigned to it.
        Parameters:
        message - The error message
        signature - This parameter should contain the detail-signature, or 'null'
        Returns:
        Nothing - throws a SourceCodeParseException
        Code:
        Exact Method Body:
         SourceCodeParseException scpe = new SourceCodeParseException(message, signature);

 ASSERT_FAIL(
     "Oracle-Sun Source-Code Parsing Error: ", message, signature,
     computeJDUProcessor(scpe)
 );

 throw scpe;

      • assertFailOracleParser

        🡅  🡇  ⇈  ⮫ 
        public static <T> T assertFailOracleParser​(java.lang.Throwable t,
                                           java.lang.String message,
                                           java.lang.String signature)
        Intended to be used like a Java Assert - meaning programming error that shouldn't occur.

        Intended for use specifically when parsing Java Source-Code - using the Sun-Oracle Source-Code Parsing Package: com.sun.source.tree.
        Type Parameters:
        T - For convenience, this allows a programmer to put a 'return' statement in front of a call to this method. The Java-Compiler is not smart-enough to know that this method is guaranteed to throw. Occasionally this may cause compiler warnings in your code about uninitialized fields and/or variables.

        This method will never actually return anything, and therefore the Java-Compiler will match this Type-Parameter to anything assigned to it.
        Parameters:
        t - The throwable that caused this assert-fail
        message - The error message
        signature - This parameter should contain the detail-signature, or 'null'
        Returns:
        Nothing - throws a SourceCodeParseException
        Code:
        Exact Method Body:
         SourceCodeParseException scpe = new SourceCodeParseException(message, t, signature);

 ASSERT_FAIL(
     "Oracle-Sun  Source-Code Parsing Error: ", t, message, signature,
     computeJDUProcessor(scpe)
 );

 throw scpe;

      • assertFailGeneralPurpose

        🡅  🡇  ⇈  ⮫ 
        public static <T> T assertFailGeneralPurpose​(java.lang.String message,
                                             java.lang.String signature)
        Previously Unreleased. Intended to be used like a Java Assert - meaning programming error that shouldn't occur. Intended for General-Purpose / unknown errors.
        Type Parameters:
        T - For convenience, this allows a programmer to put a 'return' statement in front of a call to this method. The Java-Compiler is not smart-enough to know that this method is guaranteed to throw. Occasionally this may cause compiler warnings in your code about uninitialized fields and/or variables.

        This method will never actually return anything, and therefore the Java-Compiler will match this Type-Parameter to anything assigned to it.
        Parameters:
        message - The error message
        signature - This parameter should contain the detail-signature, or 'null'
        Returns:
        Nothing - throws a UpgradeException
        Code:
        Exact Method Body:
         UpgradeException ue = new UpgradeException();

 ASSERT_FAIL("Java-Doc Upgrader Error: ", message, signature, computeJDUProcessor(ue));

 throw ue;

      • assertFailGeneralPurpose

        🡅  🡇  ⇈  ⮫ 
        public static <T> T assertFailGeneralPurpose​(java.lang.Throwable t,
                                             java.lang.String message,
                                             java.lang.String signature)
        Previously Unreleased Intended to be used like a Java Assert - meaning programming error that shouldn't occur. Intended for General-Purpose / unknown errors.
        Type Parameters:
        T - For convenience, this allows a programmer to put a 'return' statement in front of a call to this method. The Java-Compiler is not smart-enough to know that this method is guaranteed to throw. Occasionally this may cause compiler warnings in your code about uninitialized fields and/or variables.

        This method will never actually return anything, and therefore the Java-Compiler will match this Type-Parameter to anything assigned to it.
        Parameters:
        t - The throwable that caused this assert-fail
        message - The error message
        signature - This parameter should contain the detail-signature, or 'null'
        Returns:
        Nothing - throws a UpgradeException
        Code:
        Exact Method Body:
         UpgradeException ue = new UpgradeException();

 ASSERT_FAIL("Java-Doc Upgrader Error: ", t, message, signature, computeJDUProcessor(ue));

 throw ue;

      • userErrorHalt

        🡅  🡇  ⇈  ⮫ 
        public static <T> T userErrorHalt​(java.lang.String message)
        Log an error to the Messager, and throw a JavaDocError
        Type Parameters:
        T - For convenience, this allows a programmer to put a 'return' statement in front of a call to this method. The Java-Compiler is not smart-enough to know that this method is guaranteed to throw. Occasionally this may cause compiler warnings in your code about uninitialized fields and/or variables.

        This method will never actually return anything, and therefore the Java-Compiler will match this Type-Parameter to anything assigned to it.
        Parameters:
        message - The error message
        Returns:
        Does not return anything. This method is guaranteed to throw a JavaDocError
        Throws:
        JavaDocError - Always thrown
        Code:
        Exact Method Body:
         JavaDocError jde = new JavaDocError();
 ERROR(message, true /* FATAL */, computeJDUProcessor(jde));
 throw jde;

      • userErrorHalt

        🡅  🡇  ⇈  ⮫ 
        public static <T> T userErrorHalt​(java.lang.Throwable t,
                                  java.lang.String message)
        Log an error to the Messager, and throw a JavaDocError
        Type Parameters:
        T - For convenience, this allows a programmer to put a 'return' statement in front of a call to this method. The Java-Compiler is not smart-enough to know that this method is guaranteed to throw. Occasionally this may cause compiler warnings in your code about uninitialized fields and/or variables.

        This method will never actually return anything, and therefore the Java-Compiler will match this Type-Parameter to anything assigned to it.
        Parameters:
        t - The exception or cause throwable that has produced the error.
        message - The error message
        Returns:
        Does not return anything. This method is guaranteed to throw a JavaDocError
        Throws:
        JavaDocError - Always thrown
        Code:
        Exact Method Body:
         JavaDocError jde = new JavaDocError();
 ERROR(t, message, true /* FATAL */, true /* Show Stack-Trace */, computeJDUProcessor(jde));
 throw jde;

      • userErrorContinue

        🡅  🡇  ⇈  ⮫ 
        public static void userErrorContinue​(java.lang.String message,
                                     JDUProcessor p)
        Log an error to the Messager
        Parameters:
        message - The error message
        p - The Upgrade-Processor that has produced this error cannot be computed since a stack-trace cannot be obtained without throwing an unnecessary exception (which is extremely inefficient). Therefore, the Upgrade-Processor must be explicity specified here, using this parameter.
        Code:
        Exact Method Body:
         ERROR(message, false /* NON-FATAL */, p);

      • userErrorContinue

        🡅  🡇  ⇈  ⮫ 
        public static void userErrorContinue​(java.lang.Throwable t,
                                     java.lang.String message,
                                     JDUProcessor p)
        Log an error to the Messager
        Parameters:
        t - The exception or cause throwable that has produced the error.
        message - The error message
        p - The Upgrade-Processor that has produced this error cannot be computed since a stack-trace cannot be obtained without throwing an unnecessary exception (which is extremely inefficient). Therefore, the Upgrade-Processor must be explicity specified here, using this parameter.
        Code:
        Exact Method Body:
         ERROR(t, message, false /* NON-FATAL */, false  /* Don't Show Stack-Trace */, p);

      • userErrorContinueST

        🡅  🡇  ⇈  ⮫ 
        public static void userErrorContinueST​(java.lang.Throwable t,
                                       java.lang.String message,
                                       JDUProcessor p)
        Log an error to the Messager. Guarantees that the Stack-Trace is printed.
        Parameters:
        t - The exception or cause throwable that has produced the error.
        message - The error message
        p - The Upgrade-Processor that has produced this error cannot be computed since a stack-trace cannot be obtained without throwing an unnecessary exception (which is extremely inefficient). Therefore, the Upgrade-Processor must be explicity specified here, using this parameter.
        Code:
        Exact Method Body:
         ERROR(t, message, false /* NON-FATAL */, true  /* SHOW STACK TRACE */, p);

      • print

        🡅  🡇  ⇈  ⮫ 
        public static void print​(java.lang.String s)
        Prints input 's'
        Parameters:
        s - Any java.lang.String
        Code:
        Exact Method Body:
         sw.print(s);

      • println

        🡅  🡇  ⇈  ⮫ 
        public static void println​(java.lang.String s)
        Prints input 's', followed by a newline.
        Parameters:
        s - Any java.lang.String
        Code:
        Exact Method Body:
         sw.println(s);

      • println

        🡅  🡇  ⇈  ⮫ 
        public static void println()
        Prints a newline character
        Code:
        Exact Method Body:
         sw.println();

      • ifVPrintln

        🡅  🡇  ⇈  ⮫ 
        public static void ifVPrintln​(java.lang.String s)
        This prints a message to the parent-class StorageWriter, but only if the user has requested Upgrade.VERBOSE_PRINT_STEPS

        MINOR NOTE: If the message being passed involves some complicated Java StringBuilder, it would be smarter & more efficient, to only build that message after the 'VERBOSE' flag has been checked. Essentially, using this method is silly, if 's' has a bunch of '+' symbols before it is passed here.
        Parameters:
        s - The message to print to StorageWriter (the Messager's parent class)
        Code:
        Exact Method Body:
         if (VERBOSE_PRINT_STEPS) sw.println(s);

      • ifVPrint

        🡅  ⇈  ⮫ 
        public static void ifVPrint​(java.lang.String s)
        This prints a message to the parent-class StorageWriter, but only if the user has requested Upgrade.VERBOSE_PRINT_STEPS

        MINOR NOTE: If the message being passed involves some complicated Java StringBuilder, it would be smarter & more efficient, to only build that message after the 'VERBOSE' flag has been checked. Essentially, using this method is silly, if 's' has a bunch of '+' symbols before it is passed here.
        Parameters:
        s - The message to print to StorageWriter (the Messager's parent class)
        Code:
        Exact Method Body:
         if (VERBOSE_PRINT_STEPS) sw.print(s);