ByteSink
Date: 2016-05-24

com.google.common.io

## Class ByteSink

- java.lang.Object
- - com.google.common.io.ByteSink

-     public abstract class ByteSink
      extends java.lang.Object

  A destination to which bytes can be written, such as a file. Unlike an `OutputStream`, a `ByteSink` is not an open, stateful stream that can be written to and closed. Instead, it is an immutable supplier of `OutputStream` instances.

  `ByteSink` provides two kinds of methods:

  - Methods that return a stream: These methods should return a new, independent instance each time they are called. The caller is responsible for ensuring that the returned stream is closed.
  - Convenience methods: These are implementations of common operations that are typically implemented by opening a stream using one of the methods in the first category, doing something and finally closing the stream or channel that was opened.
  Since:
    14.0

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ByteSink()` Constructor for use by subclasses.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `CharSink` | `asCharSink(java.nio.charset.Charset charset)` Returns a `CharSink` view of this `ByteSink` that writes characters to this sink as bytes encoded with the given `charset`.
    `java.io.OutputStream` | `openBufferedStream()` Opens a new buffered `OutputStream` for writing to this sink.
    `abstract java.io.OutputStream` | `openStream()` Opens a new `OutputStream` for writing to this sink.
    `void` | `write(byte[] bytes)` Writes all the given bytes to this sink.
    `long` | `writeFrom(java.io.InputStream input)` Writes all the bytes from the given `InputStream` to this sink.

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

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

- - ### Constructor Detail

    - #### ByteSink

          protected ByteSink()

      Constructor for use by subclasses.

  - ### Method Detail

    - #### asCharSink

          public CharSink asCharSink(java.nio.charset.Charset charset)

      Returns a `CharSink` view of this `ByteSink` that writes characters to this sink as bytes encoded with the given `charset`.

    - #### openStream

          public abstract java.io.OutputStream openStream()
                                                   throws java.io.IOException

      Opens a new `OutputStream` for writing to this sink. This method should return a new, independent stream each time it is called.

      The caller is responsible for ensuring that the returned stream is closed.

      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of opening the stream

    - #### openBufferedStream

          public java.io.OutputStream openBufferedStream()
                                                  throws java.io.IOException

      Opens a new buffered `OutputStream` for writing to this sink. The returned stream is not required to be a `BufferedOutputStream` in order to allow implementations to simply delegate to `openStream()` when the stream returned by that method does not benefit from additional buffering (for example, a `ByteArrayOutputStream`). This method should return a new, independent stream each time it is called.

      The caller is responsible for ensuring that the returned stream is closed.

      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of opening the stream
      Since:
        15.0 (in 14.0 with return type `BufferedOutputStream`)

    - #### write

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

      Writes all the given bytes to this sink.
      Throws:
        `java.io.IOException` - if an I/O occurs in the process of writing to this sink

    - #### writeFrom

          public long writeFrom(java.io.InputStream input)
                         throws java.io.IOException

      Writes all the bytes from the given `InputStream` to this sink. Does not close `input`.
      Throws:
        `java.io.IOException` - if an I/O occurs in the process of reading from `input` or writing to this sink