CharStreamSource
Date: 2016-12-04

net.htmlparser.jericho

## Interface CharStreamSource

- All Known Subinterfaces:
    OutputSegment
  All Known Implementing Classes:
    OutputDocument, Renderer, SourceCompactor, SourceFormatter, TextExtractor

      public interface CharStreamSource

  Represents a character stream source. The purpose of a class that implements this interface is to output text.

  For small amounts of data, or when memory usage isn't a prime concern (e.g. in client-side applications), the simplest way to obtain the data is by calling the `toString()` method. If the character stream might contain a large amount of data it is recommended to use the `writeTo(Writer)` method to access the data, especially if running in a multi-user server environment.

  The advantage of providing textual data via this interface is that it gives the user the choice as to whether they would like to receive the data as a stream of characters, or all as a single string. Furthermore, it allows the "active" stream source (see below) to be easily converted into a "passive" stream source if required.

  An active stream source is a stream source that actively outputs to a passive receiver ("sink"). The `writeTo(Writer)` method in this interface signifies an active source as the transmission of the entire data stream takes place when this method is executed. In this case the sink is the object that supplies the `Writer` object, and would typically contain a `getWriter()` method. The sink is passive because it just supplies a `Writer` object to be written to by the code in some other class.

  A passive stream source is a stream source that is read from by an active sink. For character streams, a passive stream source simply supplies a `Reader` object. The active sink would typically contain a `readFrom(Reader)` method which actively reads the entire data stream from the `Reader` object.

  The `CharStreamSourceUtil.getReader(CharStreamSource)` method converts a `CharStreamSource` into a `Reader`, allowing the data from the active `CharStreamSource` to be consumed by an active sink with a `readFrom(Reader)` method.

  Every implementing class must override the `toString()` method to return the output as a string.

  An easy way to implement this is by calling the `CharStreamSourceUtil.toString(this)` method, which buffers the output from the `writeTo(Writer)` method into a string.

  See Also:
    `OutputDocument`, `SourceFormatter`, `Renderer`, `TextExtractor`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendTo(java.lang.Appendable appendable)` Appends the output to the specified `Appendable` object.
    `long` | `getEstimatedMaximumOutputLength()` Returns the estimated maximum number of characters in the output, or `-1` if no estimate is available.
    `java.lang.String` | `toString()` Returns the output as a string.
    `void` | `writeTo(java.io.Writer writer)` Writes the output to the specified `Writer`.

- - ### Method Detail

    - #### writeTo

          void writeTo(java.io.Writer writer)
                       throws java.io.IOException

      Writes the output to the specified `Writer`.
      Parameters:
        `writer` - the destination `java.io.Writer` for the output.
      Throws:
        `java.io.IOException` - if an I/O exception occurs.

    - #### appendTo

          void appendTo(java.lang.Appendable appendable)
                        throws java.io.IOException

      Appends the output to the specified `Appendable` object.
      Parameters:
        `appendable` - the destination `java.lang.Appendable` object for the output.
      Throws:
        `java.io.IOException` - if an I/O exception occurs.

    - #### getEstimatedMaximumOutputLength

          long getEstimatedMaximumOutputLength()

      Returns the estimated maximum number of characters in the output, or `-1` if no estimate is available.

      The returned value should be used as a guide for efficiency purposes only, for example to set an initial `StringBuilder` capacity. There is no guarantee that the length of the output is indeed less than this value, as classes implementing this method often use assumptions based on typical usage to calculate the estimate.

      Although implementations of this method should never return a value less than -1, users of this method must not assume that this will always be the case. Standard practice is to interpret any negative value as meaning that no estimate is available.

      Returns:
        the estimated maximum number of characters in the output, or `-1` if no estimate is available.

    - #### toString

          java.lang.String toString()

      Returns the output as a string.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the output as a string.