Class AppendableTap

  • All Implemented Interfaces:
    java.lang.Appendable
    public class AppendableTap
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:
    This class allows a user to 'wrap' another Appendable, and copy the output that it receives in it's append(...) method invocations to an internal storage buffer. That internal storage may be retrieved whenever the need arises.
    An implementation of the standard Java 'Appendable' interface that keeps an internal log of all text-data that 'passes through' the Appendable. This class can be used as a wrapper another (user-provided) Appendable, so that this class may "listen" or "record" all append(...) messages which are being sent to the wrapped (the other, user-provided) Appendable. The original instance of Appendable will still continue to receive all of its 'append' text & character data, as it normally would. However, this wrapper class will be recording the character-data in a buffer.

    All messages sent to the wrapped Appendable will, first, 'pass through' this AppendableTap instance. The character data received shall be saved inside an internal instance of StringBuffer, so that it may later be retrieved.


    RECORDED MESSAGES:
    The recorded-message(s) may be obtained, at any time, using the method AppendableTap.getString().


    SYNCHRONIZED METHODS:
    This class' methods are synchronized. Text and messaging data sent in a multi-threaded environment / application is quite common. This means that the methods any messages which would be sent to this class (AppendableTap) will force the JVM to lock the instance of this Object, and prevent other threads from accessing this class, until this class' operations have completed. (This is what the Java-Keyword 'synchronized' means).

    This was an early decision decision made solely because of the original use for this class in the multi-threaded OSResponse and OSCommands classes. Class AppendableTap was eventually replaced by the classes TriAppendable and is no longer regularly used in that set of tools.


    • Constructor Summary

      Constructors 
      Constructor Description
      AppendableTap​(Appendable appendable)
      Builds an instance of this class.

    • Method Summary

       
      Methods: interface java.lang.Appendable
      Modifier and Type Method
      Appendable append​(char c)
      Appendable append​(CharSequence s)
      Appendable append​(CharSequence s, int start, int end)
       
      Retrieve Tap's Contents, as a java.lang.String
      Modifier and Type Method
      String getString()
       
      Retrieve Tap's Contents, and Reset / Empty the Tap
      Modifier and Type Method
      String poll()
       
      Reset / Empty the Tap
      Modifier and Type Method
      void clear()

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • AppendableTap

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public AppendableTap​(java.lang.Appendable appendable)
        Builds an instance of this class. The provided instance of Appendable will receive all append() invocations that are sent to 'this' instance of AppendTap. It is important to note that only the append() calls sent to this class first will be 'tapped' (logged and kept in an internal StringBuffer instance). Any invocations that are made independently on the provided Appendable will not be saved by this class.
        Parameters:
        appendable - This may be any java Appendable. Any messages sent to this class will be sent to this input Appendable as well.

    • Method Detail

      • append

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.Appendable append​(char c)
                            throws java.io.IOException
        Logs input-parameter character 'c' to an internal StringBuffer, and then subsequently sends 'c' to the user-provided Appendable.
        Specified by:
        append in interface java.lang.Appendable
        Parameters:
        c - Any character data.
        Returns:
        'this' instance of AppendableTap shall be returned, for convenience.
        Throws:
        java.io.IOException
        Code:
        Exact Method Body:
         sb.append(c); 
 return outputAppendable.append(c);

      • append

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.Appendable append​(java.lang.CharSequence s)
                            throws java.io.IOException
        Logs input-parameter CharSequence 's' to an internal StringBuffer, and then subsequently sends 's' to the user-provided Appendable.
        Specified by:
        append in interface java.lang.Appendable
        Parameters:
        s - Any String data.
        Returns:
        'this' instance of AppendableTap shall be returned, for convenience.
        Throws:
        java.io.IOException
        Code:
        Exact Method Body:
         sb.append(s);
 return outputAppendable.append(s);

      • append

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.Appendable append​(java.lang.CharSequence s,
                                   int start,
                                   int end)
                            throws java.io.IOException
        Logs a substring of input-parameter CharSequence 's' defined by the int parameters 'start' and 'end'. This operation would be equivalent to calling the String method String.substring(start, end) on the input CharSequence prior to logging this character data, and sending it to the user-provided Appendable.
        Specified by:
        append in interface java.lang.Appendable
        Parameters:
        s - This may be any Java CharSequence
        start - The first character (inclusive) in the sub-string / sub-sequence of the input CharSequence to log, and pass-on.
        end - The last character (exclusive) of the input sub-string / sub-sequence of the CharSequence to log, and pass-on.
        Returns:
        'this' instance of AppendableTap shall be returned, for convenience.
        Throws:
        java.io.IOException
        Code:
        Exact Method Body:
         sb.append(s, start, end); 
 return outputAppendable.append(s, start, end);

      • getString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String getString()
        Retrieves the text-data that has been sent to this AppendableTap

        NOTE: Invoking this method has no effect on the underlying output (user-provided - at construction time) Appendable.
        Returns:
        Any character or text data that has been received by 'this' instance of AppendableTap through any of its append(...) methods.
        Code:
        Exact Method Body:
         String s = sb.toString();
 sb.setLength(0);
 sb.append(s);
 return s;

      • poll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String poll()
        Resets or 'clears' the contents of the internal StringBuffer 'tap', and returns the contents that were saved.
        Returns:
        Returns the contents of the internal storage, and clears the contents.
        Code:
        Exact Method Body:
         String s = sb.toString();
 sb.setLength(0);
 return s;