Class AppendableLog

  • All Implemented Interfaces:
    java.lang.Appendable
    public class AppendableLog
extends java.lang.Object
implements java.lang.Appendable
    Appendable Implementation:
    This class implements and upgrades the Simple, Java java.lang.Appendable interface, providing additional features and improvements to it. The Appendable interace is a viable design-decsion possibility for outputing text-data to a log.

    An Appendable is both blindingly easy, and highly customizable to use for third-party developers who may not be familiar with the internals of another developer's source-code.

    This Class' Primary Addition to Appendable:
    An AppendableLog instance merely adds the features offered by the enum Verbosity to make it easier to use an Appendable implementation in a tool or application that outputs varying levels of verbosity when writing log-text to a user. Verbosity can actually be an invaluable concept for a program-designer who would like to make his utilities more manageable, and easier to understand and learn for other software developers.

    There class also provides some basic indentation methods that are useful when outputing large numbers of related messages. Finally, there is the stipulation that the wrapped (internal) Appendable used for output must be an instance of AppendableSafe rather than just the standard java.lang.Appendable. AppendableSafe instances make it easier for a utility designer to avoid the (sometimes) messy, checked Java-Exception IOException from cluttering up log-code, if he so choses.

    Used in Java-HTML JAR Library:
    This class was originally developed for use with the tool ImageScraper, and it's use can be seen by clicking through the source-code for that tool and its helper classes.
    Another Logging-Helper class. This interface builds on the AppendableSafe class, and in this case it meaans that the internal Appendable that is wrapped by this one is an instance of AppendableSafe - rather than the Standard-Java java.lang.Appendable interface.

    The purpose of the AppendableSafe class is merely to prevent Java's Checked-Exception 'IOException', and replace it with any number of unchecked Throwable options. The purpose of this class is merely to add several convenience fields (hasLog and level) so that in the course of writing output-log code, a programmer is not bogged-down with 'Verbose Log Code' (Logging code that is, itself, extremely verbose-looking).
    See Also:
    ImageScraper, AppendableSafe


    • Field Detail

      • log

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final AppendableSafe log
        The actual log, itself.

        This field may be passed and assigned null by the constructor. The user should be aware to take some care if null log's are allowed in your code. This just means that there are circumstances where logging is to be "turned off". In such cases, make sure to write code that chcks whether the log is null before printing to it. (Make sure to avoid throwing NullPointerException)

        This is an instance of AppendableSafe because the actual class java.lang.Appendable has methods all of which throw IOException. The AppendableSafe class wraps those method calls and blocks the unchecked IOException's.
        See Also:
        AppendableSafe
        Code:
        Exact Field Declaration Expression:
         public final AppendableSafe log;

      • hasLog

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean hasLog
        Simple way for the user to identify whether or not a null 'appendable' parameter was passed to this class Constructor. If null was passed to log, then this boolean will be false.

    • Constructor Detail

      • AppendableLog

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableLog​(java.lang.Appendable appendable,
                     Verbosity verbosity)
        Construct an instance of this class. The 'appendable' parameter, if non-null, is immediately wrapped into an AppendableSafe instance, and configured to throw AppendableError rather than IOException when / if the internal method throws any IOException's.
        Parameters:
        appendable - This may be any instance of java.lang.Appendable.
        verbosity - An instance of the Verbosity enum. If parameter 'appendable' is null, then this paramter may also be null. However if 'appendable' is non-null, then this may not be null either - or an exception shall throw.
        Throws:
        java.lang.NullPointerException - If parameter 'appendable' is non-null, but parameter 'verbosity' is null, then a NullPointerException will throw.

      • AppendableLog

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableLog​(AppendableSafe appendableSafe,
                     Verbosity verbosity)
        Construct an instance of this class. Since there are several ways to configure the internal AppendableSafe instance, this constructor allows a user to simply pass an already built instance of AppendableSafe as a parameter.
        Parameters:
        appendableSafe - This may be any instance of AppendableSafe. The primary purpose of this class is to shunt the IOException that is thrown by java.lang.Appendable methods, and either suppress them, or re-wrap them into an unchecked-Throwable.

        Being able to leave off the throws IOException when writing log code makes the process much easier.
        verbosity - An instance of the Verbosity enum. If parameter 'appendableSafe' is null, then this paramter may also be null. However if 'appendableSafe' is non-null, then this may not be null either - or an exception shall throw.
        Throws:
        java.lang.NullPointerException - If parameter 'appendableSafe' is non-null, but parameter 'verbosity' is null, then a NullPointerException will throw.

    • Method Detail

      • append

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableSafe append​(char c)
        Appends the specified character to this Appendable.

        Description copied from class: java.lang.Appendable, JDK 1.8
        Specified by:
        append in interface java.lang.Appendable
        Parameters:
        c - The character to append
        Returns:
        A reference to this Appendable.
        Throws:
        java.lang.NullPointerException - If the AppendableSafe instance field (log) was passed null during construction of 'this' instance.
        Code:
        Exact Method Body:
         return this.log.append(c);

      • append

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableSafe append​(java.lang.CharSequence csq)
        Appends the specified character sequence to this Appendable.

        Depending on which class implements the character sequence 'csq', the entire sequence may not be appended. For instance, if 'csq' is a 'CharBuffer' the subsequence to append is defined by the buffer's position and limit.

        Description copied from class: java.lang.Appendable, JDK 1.8
        Specified by:
        append in interface java.lang.Appendable
        Parameters:
        csq - The character sequence to append. If csq is null, then the four characters "null" are appended to this Appendable.
        Returns:
        A reference to this Appendable.
        Throws:
        java.lang.NullPointerException - If the AppendableSafe instance field (log) was passed null during construction of 'this' instance.
        Code:
        Exact Method Body:
         return this.log.append(csq);

      • append

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableSafe append​(java.lang.CharSequence csq,
                             int start,
                             int end)
        Appends a subsequence of the specified character sequence to this Appendable.

        An invocation of this method of the form out.append(csq, start, end) when 'csq' is not null, behaves in exactly the same way as the invocation:

        Java Line of Code:
         out.append(csq.subSequence(start, end))


        Description copied from class: java.lang.Appendable, JDK 1.8
        Specified by:
        append in interface java.lang.Appendable
        Parameters:
        csq - The character sequence from which a subsequence will be appended. If csq is null, then the four characters "null" are appended to this Appendable.
        start - The index of the first character in the subsequence
        end - The index of the character following the last character in the subsequence
        Returns:
        A reference to this Appendable.
        Throws:
        java.lang.NullPointerException - If the AppendableSafe instance field (log) was passed null during construction of 'this' instance.
        Code:
        Exact Method Body:
         return this.log.append(csq, start, end);

      • appendI4

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableSafe appendI4​(java.lang.String s)
        Appends four character spaces of indentation, and then appends String-parameter 's'.
        Returns:
        A reference to this Appendable.
        Throws:
        java.lang.NullPointerException - If the AppendableSafe instance field (log) was passed null during construction of 'this' instance.
        Code:
        Exact Method Body:
         return this.log.append(I4).append(s);

      • appendI8

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableSafe appendI8​(java.lang.String s)
        Appends eight character spaces of indentation, and then appends String-parameter 's'.
        Returns:
        A reference to this Appendable.
        Throws:
        java.lang.NullPointerException - If the AppendableSafe instance field (log) was passed null during construction of 'this' instance.
        Code:
        Exact Method Body:
         return this.log.append(I8).append(s);

      • appendI12

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableSafe appendI12​(java.lang.String s)
        Appends twelve character spaces of indentation, and then appends String-parameter 's'.
        Returns:
        A reference to this Appendable.
        Throws:
        java.lang.NullPointerException - If the AppendableSafe instance field (log) was passed null during construction of 'this' instance.
        Code:
        Exact Method Body:
         return this.log.append(I12).append(s);

      • appendI16

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableSafe appendI16​(java.lang.String s)
        Appends sixteen character spaces of indentation, and then appends String-parameter 's'.
        Returns:
        A reference to this Appendable.
        Throws:
        java.lang.NullPointerException - If the AppendableSafe instance field (log) was passed null during construction of 'this' instance.
        Code:
        Exact Method Body:
         return this.log.append(I16).append(s);

      • levelEQ

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean levelEQ​(int level)
        Quick check that can be used to test whether or not to print to a log. The purpose of an instance of Verbosity is that logging information is only printed to an output log if the user has requested a certain level of verbosity.

        This method will return TRUE if the user has requested logging, and this instance' internal level field is equal to parameter 'level'.
        Parameters:
        level - An integer that should correspond to the enum Verbosity internal field Verbosity.level.
        Returns:
        TRUE if -

        • hasLog is also TRUE
        • level equals value passed to parameter 'level'

        Returns FALSE otherwise
        Code:
        Exact Method Body:
         if (hasLog) return (this.level == level);
 return false;

      • levelGTEQ

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean levelGTEQ​(int level)
        Quick check that can be used to test whether or not to print to a log. The purpose of an instance of Verbosity is that logging information is only printed to an output log if the user has requested a certain level of verbosity.

        This method will return TRUE if the user has requested logging, and this instance' internal level field is greater than or equal to parameter 'level'.
        Parameters:
        level - An integer that should correspond to the enum Verbosity internal field Verbosity.level.
        Returns:
        TRUE if -

        • Field hasLog is also TRUE
        • Field level is greater than or equal to value passed to parameter 'level'

        Returns FALSE otherwise
        Code:
        Exact Method Body:
         if (hasLog) return (this.level >= level);
 return false;