Package Torello.Java

Class EXCC


  • public class EXCC
    extends java.lang.Object
    EXCC Exception Cause Chain - Documentation.

    EXCC: Exception Cause Chain


    The acronym "EXCC" stands for the words "Exception Cause Chain". In Java, there are a few (very few) places where the web-scraping is benefited by a multi-threaded environment. In such cases, exceptions that are generated/thrown in your code, may have been thrown by a different thread. One of Java's strengths is that multi-threaded code was quite developed for the JRE, and that includes exceptions. In Java, Exception's thrown by a different thread will often be wrapped into another Exception. To retrieve the "cause," simply invoke Exception.getCause() to get the Exception that was thrown in the other thread.

    Java does not expect every exception throw to provide a "cause" - quite the contrary, most do not. There are also a number of java Exception's that do not even allow for a "cause throwable" in any of the provided constructors. Multi-threaded code is on source of "exception chaining" - but code there are also instances where simple try-catchblocks will catch an exceptions and wrap it (and throw the new Exception instance) in order to give the Exception a different name, and also to provide more detailed information about the error that has occurred.

    Either way, printing such information is easier to read if there is a standardized formatting for such information. This is the intended purpose to class EXCC

    ASIDE: An example that may be found multi-threaded code where one thread "monitoring" another to prevent program execution progress from "hanging" because of an internet connection would be Java's class TimeOutException and it's class ExecutionException. When java throws a time-out exception, it usually means that the underlying thread timed-out, and no "cause exception chain" is needed. However, there are also situations where java will use the class ExecutionException, because the monitor-thread detected a crash. Here, finding out which exception that the monitor thread actually caught (and wrapped inside instance class ExecutionException) requires looking at the 'ExecutionException.getCause();' throwable-chain.

    In this case, an exception from another thread will actually have two different stack-traces:

    1. ex.printStackTrace();
    2. ex.getCause().printStackTrace();

    FURTHER-ASIDE: Generally the nuts-and-bolts of Java's IO network communications exceptions are not very interesting. However, if viewing the "getCause()" of an exception has become important, this class will help print the cause-exception (and even its causes' cause - recursively). The String-methods in this class use recursion to traverse through each "parent exception", adding indentations, until a null getCause() is returned.

    Static (Functional) API: The methods in this class are all (100%) defined with the Java Key-Word / Key-Concept 'static'. Furthermore, there is no way to obtain an instance of this class, because there are no public (nor private) constructors. Java's Spring-Boot, MVC feature is *not* utilized because it flies directly in the face of the light-weight data-classes philosophy. This has many advantages over the rather ornate Component Annotations (@Component, @Service, @AutoWired, etc... 'Java Beans') syntax:

    • The methods here use the key-word 'static' which means (by implication) that there is no internal-state. Without any 'internal state' there is no need for constructors in the first place! (This is often the complaint by MVC Programmers).
    • A 'Static' (Functional-Programming) API expects to use fewer data-classes, and light-weight data-classes, making it easier to understand and to program.
    • The Vectorized HTML data-model allows more user-control over HTML parse, search, update & scrape. Also, memory management, memory leakage, and the Java Garbage Collector ought to be intelligible through the 'reuse' of the standard JDK class Vector for storing HTML Web-Page data.

    The power that object-oriented programming extends to a user is (mostly) limited to data-representation. Thinking of "Services" as "Objects" (Spring-MVC, 'Java Beans') is somewhat 'over-applying' the Object Oriented Programming Model. Like most classes in the Java-HTML JAR Library, this class backtracks to a more C-Styled Functional Programming Model (no Objects) - by re-using (quite profusely) the key-word static with all of its methods, and by sticking to Java's well-understood class Vector

    Internal-State: A user may click on this class' source code (see link below) to view any and all internally defined fields class. A cursory inspection of the code would prove that this class has precisely zero internally defined global fields (Spaghetti). All variables used by the methods in this class are local fields only, and therefore this class ought to be though of as 'state-less'.



    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method
      static String toString​(Throwable t)
      static String toString​(Throwable t, int indentations)
      protected static String toString​(Throwable t, int indentations, int curLevel)
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • toString

        public static java.lang.String toString​(java.lang.Throwable t,
                                                int indentations)
        This will convert a chain of Exception's into a String with a detailed error message.
        Parameters:
        t - Any Throwable. It is not required that this Throwable have a non-null Throwable.getCause(), and if the input does not, the only stack-traces printed will be the stack-trace of the input-Throwable.
        indentations - This is a convenience parameter to allow for "tabbed indentations" in the output String. Any integer that is negative, or greater than five will be ignored. A value between '0' and '5' will correspond to between 0 and 5 tab characters ('\t') being appended to the output. Also, successive "parent Exceptions" will be further indented.
        Returns:
        The output of the exception-printing as a java.lang.String. This may be printed to standard out, saved, logged, etc.

        NOTE: No text-output is actually sent to the console, but rather a pre-formatted String is returned. So, for example, to view the results of this method, one could call the following:
        1
        2
         System.out.println(EXCC.toString(ex, 1));
         
        


        ALSO: Remember, there is an "ending newline" or "ending '\n'" - meaning if this String is printed, use System.out.print(), instead of print() - or there will be two newline's!
        See Also:
        toString(Throwable, int, int)
        Code:
        Exact Method Body:
        1
         return toString(t, indentations, 0);
        
      • toString

        public static java.lang.String toString​(java.lang.Throwable t)
        A convenience method that calls the method in this class with the exact same name and fills in the value for missing-parameter 'indentations.' Uses a value of '0' (zero) for starting-value of parameter int 'indentations' This just means no tab's ('\t') will be prepended to each line of the returned 'String.'
        Parameters:
        t - Any Throwable generated by an Exception. Usually, this should be used in multi-threaded code where the possibility exists that two subsequent Throwable's were generated, and the former does not have the entire stack-trace.
        Returns:
        The output of the exception-printing as a java.lang.String. This may be printed to standard out, saved, logged, etc.

        NOTE: No text-output is actually sent to the console, but rather a pre-formatted String is returned. So, for example, to view the results of this method, one could call the following:
        1
        2
         System.out.print(EXCC.toString(ex, 1));
         
        


        ALSO: Remember, there is an "ending newline" or "ending '\n'" - meaning if this String is printed, use System.out.print(), instead of println() - or there will be two newline's!
        See Also:
        toString(Throwable, int, int)
        Code:
        Exact Method Body:
        1
         return toString(t, 0, 0);
        
      • toString

        protected static java.lang.String toString​(java.lang.Throwable t,
                                                   int indentations,
                                                   int curLevel)
        Prints the Exception-cause and Exception-stack trace to an output String. This is protected / internal, and exposes the previous two functions having the self-same name.
        Parameters:
        t - Any Java Throwable
        indentations - The amount to tab-indent the lines of text
        curLevel - This, actually, is a recursive method. It makes calls to itself and increases the value of 'curLevel' by one for each recursive call. This increases the amount of indentation changes the text-messages printed.
        Returns:
        This method doesn't actually print anything to the screen or terminal, it just returns a String that you may print yourself - or write to a class StorageBuffer, or any variation of logging you wish.
        See Also:
        toString(Throwable), toString(Throwable, int)
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
         StackTraceElement[] steArr      = t.getStackTrace();
         StringBuilder       sb          = new StringBuilder();
         String              indent      = "";
         Throwable           cause       = t.getCause();
         String              throwLevel  = (curLevel == 0) ? "THROWN: " : "THROW CAUSED BY EXCEPTION THROW: ";
        
         for (int i=0; (i < indentations) && (i < 5); i++) indent += '\t';
        
         sb.append(
             indent + throwLevel + t.getClass().getCanonicalName() + "\n" +
             indent + "throwable.getLocalizedMessage():\t[" + t.getLocalizedMessage() + "]\n" +
             indent + "throwable.getMessage():\t\t[" + t.getMessage() + "]\n"
         );
        
         for (int k=0; k < steArr.length; k++)
         {
             int     lineNum     = steArr[k].getLineNumber();
             String  lineNumStr  = (lineNum < 9999) ? StringParse.zeroPad10e4(lineNum) : ("" + lineNum);
        
             sb.append(
                 indent + lineNumStr + ": " +
                 steArr[k].getClassName() + "." + 
                 steArr[k].getMethodName() + "()\n"
             );
         }
        
         if (cause == null) return sb.toString();
         else               return sb.append(toString(cause, indentations + 1)).toString();