Package com.google.common.io

Class ByteSource

  • @GwtIncompatible
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.

    Note: In general, ByteSource is intended to be used for "file-like" sources that provide streams that are:

    • Finite: Many operations, such as size() and read(), will either block indefinitely or fail if the source creates an infinite stream.
    • Non-destructive: A destructive stream will consume or otherwise alter the bytes of the source as they are read from it. A source that provides such streams will not be reusable, and operations that read from the stream (including size(), in some implementations) will prevent further operations from completing as expected.
    Since:
    14.0
    Author:
    Colin Decker

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected ByteSource()
      Constructor for use by subclasses.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method 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 extends @Nullable java.lang.Object>
      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.

        If CharSource.asByteSource(java.nio.charset.Charset) is called on the returned source with the same charset, the default implementation of this method will ensure that the original ByteSource is returned, rather than round-trip encoding. Subclasses that override this method should behave the same way.

      • openStream

        public abstract java.io.InputStream openStream()
                                        throws java.io.IOException
        Opens a new InputStream for reading from this source. This method returns 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 while 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 returns 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 while 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 first checks sizeIfKnown(), returning true if it's known to be zero and false if it's known to be non-zero. If the size is not known, it falls back to opening a stream and checking for EOF.

        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

        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 while reading the size of this source

      • copyTo

        @CanIgnoreReturnValue
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.
        Returns:
        the number of bytes copied
        Throws:
        java.io.IOException - if an I/O error occurs while reading from this source or writing to output

      • copyTo

        @CanIgnoreReturnValue
public long copyTo​(ByteSink sink)
            throws java.io.IOException
        Copies the contents of this byte source to the given ByteSink.
        Returns:
        the number of bytes copied
        Throws:
        java.io.IOException - if an I/O error occurs while 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 while reading from this source

      • read

        @CanIgnoreReturnValue
public <T extends @Nullable java.lang.Object> 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 while 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 while 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 while 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).

        Note that the given byte array may be passed directly to methods on, for example, OutputStream (when copyTo(OutputStream) is called on the resulting ByteSource). This could allow a malicious OutputStream implementation to modify the contents of the array, but provides better performance in the normal case.

        Since:
        15.0 (since 14.0 as ByteStreams.asByteSource(byte[])).