Class ByteSource
- java.lang.Object
-
- com.google.common.io.ByteSource
-
@GwtIncompatible public abstract class ByteSource extends java.lang.Object
A readable source of bytes, such as a file. Unlike anInputStream
, aByteSource
is not an open, stateful stream for input that can be read and closed. Instead, it is an immutable supplier ofInputStream
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()
andread()
, 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 aCharSource
view of this byte source that decodes bytes read from this source as characters using the givenCharset
.static ByteSource
concat(ByteSource... sources)
Concatenates multipleByteSource
instances into a single source.static ByteSource
concat(java.lang.Iterable<? extends ByteSource> sources)
Concatenates multipleByteSource
instances into a single source.static ByteSource
concat(java.util.Iterator<? extends ByteSource> sources)
Concatenates multipleByteSource
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 givenByteSink
.long
copyTo(java.io.OutputStream output)
Copies the contents of this byte source to the givenOutputStream
.static ByteSource
empty()
Returns an immutableByteSource
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 bufferedInputStream
for reading from this source.abstract java.io.InputStream
openStream()
Opens a newInputStream
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>
Tread(ByteProcessor<T> processor)
Reads the contents of this byte source using the givenprocessor
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 mostlength
bytes long starting at the givenoffset
.static ByteSource
wrap(byte[] b)
Returns a view of the given byte array as aByteSource
.
-
-
-
Constructor Detail
-
ByteSource
protected ByteSource()
Constructor for use by subclasses.
-
-
Method Detail
-
asCharSource
public CharSource asCharSource(java.nio.charset.Charset charset)
Returns aCharSource
view of this byte source that decodes bytes read from this source as characters using the givenCharset
.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 originalByteSource
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 newInputStream
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 bufferedInputStream
for reading from this source. The returned stream is not required to be aBufferedInputStream
in order to allow implementations to simply delegate toopenStream()
when the stream returned by that method does not benefit from additional buffering (for example, aByteArrayInputStream
). 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 mostlength
bytes long starting at the givenoffset
. Ifoffset
is greater than the size of this source, the returned source will be empty. Ifoffset + length
is greater than the size of this source, the returned source will contain the slice starting atoffset
and ending at the end of this source.- Throws:
java.lang.IllegalArgumentException
- ifoffset
orlength
is negative
-
isEmpty
public boolean isEmpty() throws java.io.IOException
Returns whether the source has zero bytes. The default implementation first checkssizeIfKnown()
, 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 returntrue
fromisEmpty()
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, seesizeIfKnown()
.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 (orskip
, 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 givenOutputStream
. Does not closeoutput
.- Returns:
- the number of bytes copied
- Throws:
java.io.IOException
- if an I/O error occurs while reading from this source or writing tooutput
-
copyTo
@CanIgnoreReturnValue public long copyTo(ByteSink sink) throws java.io.IOException
Copies the contents of this byte source to the givenByteSink
.- Returns:
- the number of bytes copied
- Throws:
java.io.IOException
- if an I/O error occurs while reading from this source or writing tosink
-
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 givenprocessor
to process bytes as they are read. Stops when all bytes have been read or the consumer returnsfalse
. Returns the result produced by the processor.- Throws:
java.io.IOException
- if an I/O error occurs while reading from this source or ifprocessor
throws anIOException
- 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 orother
-
concat
public static ByteSource concat(java.lang.Iterable<? extends ByteSource> sources)
Concatenates multipleByteSource
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 multipleByteSource
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 anImmutableList
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 theconcat(Iterable)
overload if possible.- Parameters:
sources
- the sources to concatenate- Returns:
- a
ByteSource
containing the concatenated data - Throws:
java.lang.NullPointerException
- if any ofsources
isnull
- Since:
- 15.0
-
concat
public static ByteSource concat(ByteSource... sources)
Concatenates multipleByteSource
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 ofsources
isnull
- Since:
- 15.0
-
wrap
public static ByteSource wrap(byte[] b)
Returns a view of the given byte array as aByteSource
. To view only a specific range in the array, useByteSource.wrap(b).slice(offset, length)
.Note that the given byte array may be passed directly to methods on, for example,
OutputStream
(whencopyTo(OutputStream)
is called on the resultingByteSource
). This could allow a maliciousOutputStream
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[])
).
-
empty
public static ByteSource empty()
Returns an immutableByteSource
that contains no bytes.- Since:
- 15.0
-
-