Package: groovy.xml.streamingmarkupsupport

## [Java] Class StreamingMarkupWriter

- groovy.xml.streamingmarkupsupport.StreamingMarkupWriter

-     public class StreamingMarkupWriter
      extends Writer

  Writer used by streaming markup support to escape XML lazily while honoring output encoding limits.

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `protected CharsetEncoder` | `encoder` | Encoder used to decide when numeric character references are required.
    `protected String` | `encoding` | Normalized target encoding name.
    `protected boolean` | `encodingKnown` | Whether the target encoding was explicitly supplied or discovered from the wrapped writer.
    `protected boolean` | `haveHighSurrogate` | Whether a high surrogate is buffered awaiting its matching low surrogate.
    `protected StringBuilder` | `surrogatePair` | Temporary buffer for surrogate pair handling.
    `protected Writer` | `writer` | Underlying destination writer.
    `protected boolean` | `writingAttribute` | Whether output is currently inside an attribute value.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `StreamingMarkupWriter(Writer writer, String encoding)` Creates a streaming writer using the supplied encoding name and single-quote attribute escaping.
    `StreamingMarkupWriter(Writer writer, String encoding, boolean useDoubleQuotes)` Creates a streaming writer.
    `StreamingMarkupWriter(Writer writer)` Creates a streaming writer that infers its encoding from the wrapped writer when possible.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `close()` Closes the stream, flushing it first. Once the stream has been closed, further write() or flush() invocations will cause an IOException to be thrown. Closing a previously closed stream has no effect. throws: IOException If an I/O error occurs
    `` | `public Writer` | `escaped()` Returns a writer view that applies XML escaping before delegating here.
    `` | `public void` | `flush()` Flushes the stream. If the stream has saved any characters from the various write() methods in a buffer, write them immediately to their intended destination. Then, if that destination is another character or byte stream, flush it. Thus one flush() invocation will flush all the buffers in a chain of Writers and OutputStreams. If the intended destination of this stream is an abstraction provided by the underlying operating system, for example a file, then flushing the stream guarantees only that bytes previously written to the stream are passed to the operating system for writing; it does not guarantee that they are actually written to a physical device such as a disk drive. throws: IOException If an I/O error occurs
    `` | `public String` | `getEncoding()` Returns the normalized target encoding used for numeric escape decisions.
    `` | `public boolean` | `getEncodingKnown()` Returns whether the encoding came from an explicit or discoverable source.
    `` | `public void` | `setWritingAttribute(boolean writingAttribute)` Switches escaping rules between element text and attribute value output.
    `` | `public Writer` | `unescaped()` Returns a writer view that bypasses the additional escaping layer.
    `` | `public void` | `write(int c)` Writes a single character. The character to be written is contained in the 16 low-order bits of the given integer value; the 16 high-order bits are ignored. Subclasses that intend to support efficient single-character output should override this method. throws: IOException If an I/O error occurs Parameters: `c` - int specifying a character to be written
    `` | `public void` | `write(char[] cbuf, int off, int len)` Writes a portion of an array of characters. throws: IndexOutOfBoundsException Implementations should throw this exception if `off` is negative, or `len` is negative, or `off + len` is negative or greater than the length of the given array throws: IOException If an I/O error occurs Parameters: `cbuf` - Array of characters `off` - Offset from which to start writing characters `len` - Number of characters to write

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Writer` | `append, append, append, append, append, append, close, equals, flush, getClass, hashCode, notify, notifyAll, nullWriter, toString, wait, wait, wait, write, write, write, write, write`

- - ### Field Detail

    - #### protected final CharsetEncoder encoder

      Encoder used to decide when numeric character references are required.

    - #### protected final String encoding

      Normalized target encoding name.

    - #### protected boolean encodingKnown

      Whether the target encoding was explicitly supplied or discovered from the wrapped writer.

    - #### protected boolean haveHighSurrogate

      Whether a high surrogate is buffered awaiting its matching low surrogate.

    - #### protected StringBuilder surrogatePair

      Temporary buffer for surrogate pair handling.

    - #### protected final Writer writer

      Underlying destination writer.

    - #### protected boolean writingAttribute

      Whether output is currently inside an attribute value.

  - ### Constructor Detail

    - #### public StreamingMarkupWriter(Writer writer, String encoding)

      Creates a streaming writer using the supplied encoding name and single-quote attribute escaping.

      Parameters:
        `writer` - destination writer
        `encoding` - target encoding, or `null` to infer it

    - #### public StreamingMarkupWriter(Writer writer, String encoding, boolean useDoubleQuotes)

      Creates a streaming writer.

      Parameters:
        `writer` - destination writer
        `encoding` - target encoding, or `null` to infer it
        `useDoubleQuotes` - whether attribute escaping should target double quotes instead of single quotes

    - #### public StreamingMarkupWriter(Writer writer)

      Creates a streaming writer that infers its encoding from the wrapped writer when possible.

      Parameters:
        `writer` - destination writer

  - ### Method Detail

    - #### public void close()

      Closes the stream, flushing it first. Once the stream has been closed, further write() or flush() invocations will cause an IOException to be thrown. Closing a previously closed stream has no effect.

      throws:
        IOException If an I/O error occurs

    - #### public Writer escaped()

      Returns a writer view that applies XML escaping before delegating here.

      Returns:
        escaped writer view

    - #### public void flush()

      Flushes the stream. If the stream has saved any characters from the various write() methods in a buffer, write them immediately to their intended destination. Then, if that destination is another character or byte stream, flush it. Thus one flush() invocation will flush all the buffers in a chain of Writers and OutputStreams.

      If the intended destination of this stream is an abstraction provided by the underlying operating system, for example a file, then flushing the stream guarantees only that bytes previously written to the stream are passed to the operating system for writing; it does not guarantee that they are actually written to a physical device such as a disk drive.

      throws:
        IOException If an I/O error occurs

    - #### public String getEncoding()

      Returns the normalized target encoding used for numeric escape decisions.

      Returns:
        target encoding name

    - #### public boolean getEncodingKnown()

      Returns whether the encoding came from an explicit or discoverable source.

      Returns:
        `true` if the encoding is known precisely

    - #### public void setWritingAttribute(boolean writingAttribute)

      Switches escaping rules between element text and attribute value output.

      Parameters:
        `writingAttribute` - `true` when writing an attribute value

    - #### public Writer unescaped()

      Returns a writer view that bypasses the additional escaping layer.

      Returns:
        unescaped writer view

    - #### public void write(int c)

      Writes a single character. The character to be written is contained in the 16 low-order bits of the given integer value; the 16 high-order bits are ignored.

      Subclasses that intend to support efficient single-character output should override this method.

      throws:
        IOException If an I/O error occurs
      Parameters:
        `c` - int specifying a character to be written

    - #### public void write(char[] cbuf, int off, int len)

      Writes a portion of an array of characters.

      throws:
        IndexOutOfBoundsException Implementations should throw this exception if `off` is negative, or `len` is negative, or `off + len` is negative or greater than the length of the given array
      throws:
        IOException If an I/O error occurs
      Parameters:
        `cbuf` - Array of characters
        `off` - Offset from which to start writing characters
        `len` - Number of characters to write