uk.ac.starlink.util

## Class BufferedBase64OutputStream

- java.lang.Object
- - java.io.OutputStream
  - - java.io.FilterOutputStream
    - - uk.ac.starlink.util.BufferedBase64OutputStream

- All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

      public class BufferedBase64OutputStream
      extends java.io.FilterOutputStream

  OutputStream that encodes to Base64 with buffering. Considerably faster than unbuffered implementations.

  Note that the `endBase64()` method should be called once at the end of writing to flush the input and ensure that the output is ended correctly. Closing the stream will call this if it has not been called already.

  Since:
    31 Mar 2022

- - ### Field Summary

    - ### Fields inherited from class java.io.FilterOutputStream

      `out`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BufferedBase64OutputStream(java.io.OutputStream out)` Constructor with default characteristics.
    `BufferedBase64OutputStream(java.io.OutputStream out, int quadsPerLine, byte[] lineEnd, int linesPerBuf)` Custom constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Calls `endBase64()` if required before closing.
    `void` | `endBase64()` Flushes any data in the buffer and terminates the Base64 output correctly.
    `void` | `flush()` This calls flush on the underlying stream, but does not flush this stream itself.
    `int` | `getOutputBufferSize()` Returns the size of the output buffer; output will be written to the underlying stream in chunks of this size.
    `void` | `write(byte[] b)`
    `void` | `write(byte[] b, int off, int len)`
    `void` | `write(int b)`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### BufferedBase64OutputStream

          public BufferedBase64OutputStream(java.io.OutputStream out)

      Constructor with default characteristics.
      Parameters:
        `out` - underlying output stream, doesn't need to be buffered

    - #### BufferedBase64OutputStream

          public BufferedBase64OutputStream(java.io.OutputStream out,
                                            int quadsPerLine,
                                            byte[] lineEnd,
                                            int linesPerBuf)

      Custom constructor.
      Parameters:
        `out` - underlying output stream, doesn't need to be buffered
        `quadsPerLine` - number of 4-byte groups per output line
        `lineEnd` - sequence of bytes to be written after each output line
        `linesPerBuf` - number of lines buffered before an actual write to the underlying stream is performed

  - ### Method Detail

    - #### write

          public void write(int b)
                     throws java.io.IOException

      Overrides:
        `write` in class `java.io.FilterOutputStream`
      Throws:
        `java.io.IOException`

    - #### write

          public void write(byte[] b,
                            int off,
                            int len)
                     throws java.io.IOException

      Overrides:
        `write` in class `java.io.FilterOutputStream`
      Throws:
        `java.io.IOException`

    - #### write

          public void write(byte[] b)
                     throws java.io.IOException

      Overrides:
        `write` in class `java.io.FilterOutputStream`
      Throws:
        `java.io.IOException`

    - #### endBase64

          public void endBase64()
                         throws java.io.IOException

      Flushes any data in the buffer and terminates the Base64 output correctly. This method must be called, once, after all writes have been completed, otherwise the output will likely not be valid base64. This method will be called by `close()` if it has not been done already. The effect of further writes to this stream following a call to this method is undefined.
      Throws:
        `java.io.IOException`

    - #### getOutputBufferSize

          public int getOutputBufferSize()

      Returns the size of the output buffer; output will be written to the underlying stream in chunks of this size.
      Returns:
        output buffer length in bytes

    - #### flush

          public void flush()
                     throws java.io.IOException

      This calls flush on the underlying stream, but does not flush this stream itself. The `endBase64()` method must be called to do that.
      Specified by:
        `flush` in interface `java.io.Flushable`
      Overrides:
        `flush` in class `java.io.FilterOutputStream`
      Throws:
        `java.io.IOException`

    - #### close

          public void close()
                     throws java.io.IOException

      Calls `endBase64()` if required before closing.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Overrides:
        `close` in class `java.io.FilterOutputStream`
      Throws:
        `java.io.IOException`