ByteSource
Date: 2016-05-24

com.google.common.io

## Class ByteSource

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

-     public abstract class ByteSource
      extends java.lang.Object

  A readable source of bytes, such as a file. Unlike an `InputStream`, a `ByteSource` is not an open, stateful stream for input that can be read and closed. Instead, it is an immutable supplier of `InputStream` instances.

  `ByteSource` 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 that was opened.
  Since:
    14.0

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `CharSource` | `asCharSource(java.nio.charset.Charset charset)` Returns a `CharSource` view of this byte source that decodes bytes read from this source as characters using the given `Charset`.
    `static ByteSource` | `concat(ByteSource... sources)` Concatenates multiple `ByteSource` instances into a single source.
    `static ByteSource` | `concat(java.lang.Iterable<? extends ByteSource> sources)` Concatenates multiple `ByteSource` instances into a single source.
    `static ByteSource` | `concat(java.util.Iterator<? extends ByteSource> sources)` Concatenates multiple `ByteSource` instances into a single source.
    `boolean` | `contentEquals(ByteSource other)` Checks that the contents of this byte source are equal to the contents of the given byte source.
    `long` | `copyTo(ByteSink sink)` Copies the contents of this byte source to the given `ByteSink`.
    `long` | `copyTo(java.io.OutputStream output)` Copies the contents of this byte source to the given `OutputStream`.
    `static ByteSource` | `empty()` Returns an immutable `ByteSource` that contains no bytes.
    `HashCode` | `hash(HashFunction hashFunction)` Hashes the contents of this byte source using the given hash function.
    `boolean` | `isEmpty()` Returns whether the source has zero bytes.
    `java.io.InputStream` | `openBufferedStream()` Opens a new buffered `InputStream` for reading from this source.
    `abstract java.io.InputStream` | `openStream()` Opens a new `InputStream` for reading from this source.
    `byte[]` | `read()` Reads the full contents of this byte source as a byte array.
    `<T> T` | `read(ByteProcessor<T> processor)` Reads the contents of this byte source using the given `processor` to process bytes as they are read.
    `long` | `size()` Returns the size of this source in bytes, even if doing so requires opening and traversing an entire stream.
    `Optional<java.lang.Long>` | `sizeIfKnown()` Returns the size of this source in bytes, if the size can be easily determined without actually opening the data stream.
    `ByteSource` | `slice(long offset, long length)` Returns a view of a slice of this byte source that is at most `length` bytes long starting at the given `offset`.
    `static ByteSource` | `wrap(byte[] b)` Returns a view of the given byte array as a `ByteSource`.

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

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

- - ### Constructor Detail

    - #### ByteSource

          protected ByteSource()

      Constructor for use by subclasses.

  - ### Method Detail

    - #### asCharSource

          public CharSource asCharSource(java.nio.charset.Charset charset)

      Returns a `CharSource` view of this byte source that decodes bytes read from this source as characters using the given `Charset`.

    - #### openStream

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

      Opens a new `InputStream` for reading from this source. 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.InputStream openBufferedStream()
                                                 throws java.io.IOException

      Opens a new buffered `InputStream` for reading from this source. The returned stream is not required to be a `BufferedInputStream` 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 `ByteArrayInputStream`). 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 `BufferedInputStream`)

    - #### slice

          public ByteSource slice(long offset,
                         long length)

      Returns a view of a slice of this byte source that is at most `length` bytes long starting at the given `offset`. If `offset` is greater than the size of this source, the returned source will be empty. If `offset + length` is greater than the size of this source, the returned source will contain the slice starting at `offset` and ending at the end of this source.
      Throws:
        `java.lang.IllegalArgumentException` - if `offset` or `length` is negative

    - #### isEmpty

          public boolean isEmpty()
                          throws java.io.IOException

      Returns whether the source has zero bytes. The default implementation returns true if `sizeIfKnown()` returns zero, falling back to opening a stream and checking for EOF if the size is not known.

      Note that, in cases where `sizeIfKnown` returns zero, it is possible that bytes are actually available for reading. (For example, some special files may return a size of 0 despite actually having content when read.) This means that a source may return `true` from `isEmpty()` despite having readable content.

      Throws:
        `java.io.IOException` - if an I/O error occurs
      Since:
        15.0

    - #### sizeIfKnown

          @Beta
          public Optional<java.lang.Long> sizeIfKnown()

      Returns the size of this source in bytes, if the size can be easily determined without actually opening the data stream.

      The default implementation returns `Optional.absent()`. Some sources, such as a file, may return a non-absent value. Note that in such cases, it is possible that this method will return a different number of bytes than would be returned by reading all of the bytes (for example, some special files may return a size of 0 despite actually having content when read).

      Additionally, for mutable sources such as files, a subsequent read may return a different number of bytes if the contents are changed.

      Since:
        19.0

    - #### size

          public long size()
                    throws java.io.IOException

      Returns the size of this source in bytes, even if doing so requires opening and traversing an entire stream. To avoid a potentially expensive operation, see `sizeIfKnown()`.

      The default implementation calls `sizeIfKnown()` and returns the value if present. If absent, it will fall back to a heavyweight operation that will open a stream, read (or `skip`, if possible) to the end of the stream and return the total number of bytes that were read.

      Note that for some sources that implement `sizeIfKnown()` to provide a more efficient implementation, it is possible that this method will return a different number of bytes than would be returned by reading all of the bytes (for example, some special files may return a size of 0 despite actually having content when read).

      In either case, for mutable sources such as files, a subsequent read may return a different number of bytes if the contents are changed.

      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading the size of this source

    - #### copyTo

          public long copyTo(java.io.OutputStream output)
                      throws java.io.IOException

      Copies the contents of this byte source to the given `OutputStream`. Does not close `output`.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source or writing to `output`

    - #### copyTo

          public long copyTo(ByteSink sink)
                      throws java.io.IOException

      Copies the contents of this byte source to the given `ByteSink`.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source or writing to `sink`

    - #### read

          public byte[] read()
                      throws java.io.IOException

      Reads the full contents of this byte source as a byte array.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source

    - #### read

          @Beta
          public <T> T read(ByteProcessor<T> processor)
                 throws java.io.IOException

      Reads the contents of this byte source using the given `processor` to process bytes as they are read. Stops when all bytes have been read or the consumer returns `false`. Returns the result produced by the processor.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source or if `processor` throws an `IOException`
      Since:
        16.0

    - #### hash

          public HashCode hash(HashFunction hashFunction)
                        throws java.io.IOException

      Hashes the contents of this byte source using the given hash function.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source

    - #### contentEquals

          public boolean contentEquals(ByteSource other)
                                throws java.io.IOException

      Checks that the contents of this byte source are equal to the contents of the given byte source.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source or `other`

    - #### concat

          public static ByteSource concat(java.lang.Iterable<? extends ByteSource> sources)

      Concatenates multiple `ByteSource` instances into a single source. Streams returned from the source will contain the concatenated data from the streams of the underlying sources.

      Only one underlying stream will be open at a time. Closing the concatenated stream will close the open underlying stream.

      Parameters:
        `sources` - the sources to concatenate
      Returns:
        a `ByteSource` containing the concatenated data
      Since:
        15.0

    - #### concat

          public static ByteSource concat(java.util.Iterator<? extends ByteSource> sources)

      Concatenates multiple `ByteSource` instances into a single source. Streams returned from the source will contain the concatenated data from the streams of the underlying sources.

      Only one underlying stream will be open at a time. Closing the concatenated stream will close the open underlying stream.

      Note: The input `Iterator` will be copied to an `ImmutableList` when this method is called. This will fail if the iterator is infinite and may cause problems if the iterator eagerly fetches data for each source when iterated (rather than producing sources that only load data through their streams). Prefer using the `concat(Iterable)` overload if possible.

      Parameters:
        `sources` - the sources to concatenate
      Returns:
        a `ByteSource` containing the concatenated data
      Throws:
        `java.lang.NullPointerException` - if any of `sources` is `null`
      Since:
        15.0

    - #### concat

          public static ByteSource concat(ByteSource... sources)

      Concatenates multiple `ByteSource` instances into a single source. Streams returned from the source will contain the concatenated data from the streams of the underlying sources.

      Only one underlying stream will be open at a time. Closing the concatenated stream will close the open underlying stream.

      Parameters:
        `sources` - the sources to concatenate
      Returns:
        a `ByteSource` containing the concatenated data
      Throws:
        `java.lang.NullPointerException` - if any of `sources` is `null`
      Since:
        15.0

    - #### wrap

          public static ByteSource wrap(byte[] b)

      Returns a view of the given byte array as a `ByteSource`. To view only a specific range in the array, use `ByteSource.wrap(b).slice(offset, length)`.
      Since:
        15.0 (since 14.0 as `ByteStreams.asByteSource(byte[])`).

    - #### empty

          public static ByteSource empty()

      Returns an immutable `ByteSource` that contains no bytes.
      Since:
        15.0