Class AppendableSafe

  • All Implemented Interfaces:
    java.lang.Appendable
    public class AppendableSafe
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 AppendableSafe instance merely wraps an instance of Appendable to catch and prevent the sometimes messy, checked-exception IOException from cluttering what is often very simple log-code. This class allows a user to make it easy to choose what to do if a user-provided Appendable-instance does wind up throwing an IOException anyway!

    When writing code that uses an instance of AppendableSafe, there is no need to catch any checked-exceptions thrown by the Appendable's 'append(...)' methods, nor to include a throws IOException in the signature/header of the methods that employ AppendableSafe-instances.

    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.
    Identical to class java.lang.Appendable, but shunts the often problematic IOException that may be thrown by its append(...)-methods, and replaces it with either a user-customizable Throwable-class, or with (the default) java.io.UncheckedIOException.

    If a tool or application would like to simplify output logging by allows a user to simply pass a reference to a java.lang.Appendable instance, but worries that that interface's copious 'throws IOException' will over-complicate their logging-code, then this interface is for you!.

    The following five options are available for dealing with the dreaded Checked IOException that Java may throw when writing to an Appendable.

    • Wrap the checked IOException in a java.io.UncheckedIOException, and then pass it to the unchecked exception's constructor's 'cause' parameter. After construction, throw the newly constructed, unchecked, exception.

    • Wrap the checked IOException in an AppendableError, and then pass it to the error's constructor's 'cause' parameter. After construction, throw the newly constructed, unchecked, error.

    • Supress and Ignore the exception competely! After catching an IOException which has been accidentally generated by one of the underlying Appendable's 'append(...)' methods, simply ignore it and let it go out of scope.

    • Wrap the checked IOException in a User-Provided RuntimeException, and then pass it to the User-Provided exception's constructor's 'cause' parameter. After that constructor has finished, throw the newly constructted RuntimeException.

      Important: The Class provided to parameter classRTEX must actually have a constructor which accepts a 'cause'-Throwable. If the User-Provided, "alternate", RuntimeException cannot be constructed using a 'cause' Throwable, then the attempt to build this 'AppendableSafe' instance will fail.

      RuntimeException Constructor Expectations: The constructor for this variant of AppendableSafe will check for a constructor which accepts a Throwable 'cause' parameter, or a RuntimeException constructor which accepts a String 'message' and Throwable 'cause'.

    • Provide a Consumer<? extends IOException> 'handler' if-and-when the underlying Appendable's append(...) methods happen to throw an IOException.
    See Also:
    ImageScraper, AppendableLog


    • Constructor Summary

      Constructors 
      Constructor
      AppendableSafe​(Appendable appendable, byte throwDecision)
      AppendableSafe​(Appendable appendable, Class<? extends RuntimeException> classRTEX)
      AppendableSafe​(Appendable appendable, Consumer<? super IOException> ioeHandler)

    • Method Summary

       
      Methods: interface java.lang.Appendable
      Modifier and Type Method
      AppendableSafe append​(char c)
      AppendableSafe append​(CharSequence csq)
      AppendableSafe append​(CharSequence csq, int start, int end)

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • USE_UNCHECKED_IOEXCEPTION

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final byte USE_UNCHECKED_IOEXCEPTION
        Indicates that the user would like to have 'UncheckedIOException' thrown in place of the standard (checked) exception 'IOException'.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final byte USE_UNCHECKED_IOEXCEPTION = 1;

      • SUPPRESS_AND_IGNORE

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final byte SUPPRESS_AND_IGNORE
        Configures AppendableSafe to catch any IOException's that are thrown by the Appendable's method append(...), and suppress / ignore them.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final byte SUPPRESS_AND_IGNORE = 3;

      • exceptionMessage

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.lang.String exceptionMessage
        The message used by the 'wrapper' Throwable
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final String exceptionMessage =
         "The underlying Appendable instance has thrown an IOException upon invocation of one of " +
         "its append(...) methods.  Please see this Throwable's getCause() to review the " +
         "specifics of the cause IOException.";

      • appendable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.Appendable appendable
        This is the internally used java.lang.Appendable. Class AppendableSafe is nothing more than a wrapper class around a java.lang.Appendable instance. All that AppendableSafe does is to catch any potential IOException instances that may or may not be thrown by the Appendable's append(...) methods, and either suppress them, or re-wrap them in an "Un-Checked" type of Throwable.

        This public field provides access to the wrapped / internal Appendable.
        Code:
        Exact Field Declaration Expression:
         public final Appendable appendable;

      • throwDecision

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final byte throwDecision
        If one of the standard ways of avoiding IOException-throws by a Java Appendable has been chosen, this byte-constant will contain the value of one of the three static-constants defined at the top of this class.

        If the user has opted to provide a RuntimeException class to throw when an IOException is caught, this constant-field will be assigned '0' by the constructor.
        Code:
        Exact Field Declaration Expression:
         public final byte throwDecision;

      • classRTEX

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.Class<? extends java.lang.RuntimeException> classRTEX
        This may be null, and if it is - the value stored in throwDecision or the value of handler will be used for deciding what to do when the internal / wrapped Appendable throws an IOException while appending character-data.

        When this 'class' field-constant is non-null, the RuntimeException represented by the class will be thrown whenever the internal / wrapped Appendable throws a (Checked) IOException while writing character-data to it.
        Code:
        Exact Field Declaration Expression:
         public final Class<? extends RuntimeException> classRTEX;

    • Constructor Detail

      • AppendableSafe

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableSafe​(java.lang.Appendable appendable,
                      byte throwDecision)
        Constructs an instance of this class that wraps the provided java.lang.Appendable. The instance that is created will catch any and all IOException's that are thrown by the input 'appendable'-parameter's append(...) methods.

        If invoking an append(...) method does cause an IOException to throw, then the AppendableSafe instance that is built right here will be one that, in turn, throws the Throwable indicated by the 'throwDecision' parameter.

        If 'throwDecision' is passed the byte-value for SUPPRESS_AND_IGNORE, then when / if an append(...) throws IOException, that exception, instead, will simply be caught and ignored.
        Parameters:
        appendable - Any instance of java.lang.Appendable.
        throwDecision - Allows a user to decide what happens when / if the provided Appendable's methods for accepting character-data throw an IOException.

        The allowed values are all byte-constants, and they are listed at the top of this class:

        1. USE_UNCHECKED_IOEXCEPTION
        2. USE_APPENDABLE_ERROR
        3. SUPPRESS_AND_IGNORE
        Throws:
        java.lang.NullPointerException - If null is passed to the 'apendable' parameter.
        java.lang.IllegalArgumentException - If parameter 'throwDecision' is not passed one of the three byte-value constants provided at the top of this class.

      • AppendableSafe

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableSafe​
            (java.lang.Appendable appendable,
             java.lang.Class<? extends java.lang.RuntimeException> classRTEX)
        throws java.lang.NoSuchMethodException
        Constructs an instance of this class, where any potential IOException's that are thrown when appending character data to this Appendable are wrapped into the specified-Throwable.
        Parameters:
        appendable - This may be any implementation of java.lang.Appendable. This class will supercede calls to this Appendable, and prevent or catch any exceptions which may or may not throw.

        If this instance / this parameter 'appendable' does happen to throw an exception when utilizing one it's append(...) methods, then that exception will be caught, wrapped, and re-thrown as an instance of the specified Throwable-=class.
        classRTEX - This is the class of RuntimeException that should be expected to throw when the underlying Appendable throws an IOException during one of its append(...) method invocations.

        This parameter may not be null, because otherwise a NullPointerException will ensue. The class that is passed here must be an instance or decendant of java.lang.RuntimeException, and one having a constructor which accepts a String ('message') parameter, and a Throwable ('cause') parameter.
        Throws:
        java.lang.NoSuchMethodException - - This exception will throw if the parameter 'classRTEX' is a class which does not have a two-argument constructor - one of which is a String, and the other of which is a Throwable.
        java.lang.SecurityException - - If a security manager, 's', is present and the caller's class loader is not the same as or an ancestor of the class loader for the current class and invocation of s.checkPackageAccess() denies access to the package of this class.
        java.lang.NullPointerException - if either parameter 'appendable' or parameter 'classRTEX' are null.

      • AppendableSafe

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableSafe​
            (java.lang.Appendable appendable,
             java.util.function.Consumer<? super java.io.IOException> ioeHandler)
        Constructs an instance of this class, where any potential IOException's that are thrown when appending character data to this Appendable are first suppressed, and then passed as parameters to the handler parameter received by this constructor.
        Parameters:
        appendable - This may be any implementation of java.lang.Appendable. This class will supercede calls to this Appendable, and prevent or catch any exceptions which may or may not throw.

        If this instance / this parameter 'appendable' does happen to throw an exception when utilizing one it's append(...) methods, then that exception will be caught and provided to the handler provided this constructor.
        ioeHandler - A Java Consumer which accepts an IOException parameter, and performs whatever User-Decided functions if-and-when an IOException happens to be thrown by the 'append(...)' methods which wrap by the internal 'Appendable' instance.

    • 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.RuntimeException - If the underlying / wrapped java.lang.Appendable throws an IOException while attempting to write charcter data using one of it's append(...) methods, and if the user has provided a RuntimeException to field classRTEX then an instance of that exception will be thrown after catching the wrapped Appendable's IOException.
        java.io.UncheckedIOException - If the underlying / wrapped java.lang.Appendable throws an IOException while attempting to write charcter data using one of it's append(...) methods, and if the user has configured the field throwDecision using the constant USE_UNCHECKED_IOEXCEPTION then an instance of java.io.UncheckedIOException will be thrown after catching the wrapped Appendable's IOException.
        AppendableError - If the underlying / wrapped java.lang.Appendable throws an IOException while attempting to write charcter data using one of it's append(...) methods, and if the user has configured the field throwDecision using the constant USE_APPENDABLE_ERROR then an instance of Torello.Java.Additional.AppendableError will be thrown after catching the wrapped Appendable's IOException.
        Code:
        Exact Method Body:
         try
     { appendable.append(c); }

 catch (IOException ioe) { handler.accept(ioe); }

 return this;

      • 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.RuntimeException - If the underlying / wrapped java.lang.Appendable throws an IOException while attempting to write charcter data using one of it's append(...) methods, and if the user has provided a RuntimeException to field classRTEX then an instance of that exception will be thrown after catching the wrapped Appendable's IOException.
        java.io.UncheckedIOException - If the underlying / wrapped java.lang.Appendable throws an IOException while attempting to write charcter data using one of it's append(...) methods, and if the user has configured the field throwDecision using the constant USE_UNCHECKED_IOEXCEPTION then an instance of java.io.UncheckedIOException will be thrown after catching the wrapped Appendable's IOException.
        AppendableError - If the underlying / wrapped java.lang.Appendable throws an IOException while attempting to write charcter data using one of it's append(...) methods, and if the user has configured the field throwDecision using the constant USE_APPENDABLE_ERROR then an instance of Torello.Java.Additional.AppendableError will be thrown after catching the wrapped Appendable's IOException.
        Code:
        Exact Method Body:
         try
     { appendable.append(csq); }

 catch (IOException ioe) { handler.accept(ioe); }

 return this;

      • 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.RuntimeException - If the underlying / wrapped java.lang.Appendable throws an IOException while attempting to write charcter data using one of it's append(...) methods, and if the user has provided a RuntimeException to field classRTEX then an instance of that exception will be thrown after catching the wrapped Appendable's IOException.
        java.io.UncheckedIOException - If the underlying / wrapped java.lang.Appendable throws an IOException while attempting to write charcter data using one of it's append(...) methods, and if the user has configured the field throwDecision using the constant USE_UNCHECKED_IOEXCEPTION then an instance of java.io.UncheckedIOException will be thrown after catching the wrapped Appendable's IOException.
        AppendableError - If the underlying / wrapped java.lang.Appendable throws an IOException while attempting to write charcter data using one of it's append(...) methods, and if the user has configured the field throwDecision using the constant USE_APPENDABLE_ERROR then an instance of Torello.Java.Additional.AppendableError will be thrown after catching the wrapped Appendable's IOException.
        Code:
        Exact Method Body:
         try
     { appendable.append(csq); }

 catch (IOException ioe) { handler.accept(ioe); }

 return this;