@GwtIncompatible public abstract class ByteSource extends Object
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:
Modifier | Constructor and Description |
---|---|
protected |
ByteSource()
Constructor for use by subclasses.
|
Modifier and Type | Method and Description |
---|---|
CharSource |
asCharSource(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(Iterable<? extends ByteSource> sources)
Concatenates multiple
ByteSource instances into a single source. |
static ByteSource |
concat(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(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.
|
InputStream |
openBufferedStream()
Opens a new buffered
InputStream for reading from this source. |
abstract 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<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 . |
protected ByteSource()
public CharSource asCharSource(Charset charset)
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.
public abstract InputStream openStream() throws IOException
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.
IOException
- if an I/O error occurs while opening the streampublic InputStream openBufferedStream() throws IOException
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.
IOException
- if an I/O error occurs while opening the streamBufferedInputStream
)public ByteSource slice(long offset, long length)
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.IllegalArgumentException
- if offset
or length
is negativepublic boolean isEmpty() throws IOException
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.
IOException
- if an I/O error occurs@Beta public Optional<Long> sizeIfKnown()
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.
public long size() throws IOException
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.
IOException
- if an I/O error occurs while reading the size of this source@CanIgnoreReturnValue public long copyTo(OutputStream output) throws IOException
OutputStream
. Does not close
output
.IOException
- if an I/O error occurs while reading from this source or writing to output
@CanIgnoreReturnValue public long copyTo(ByteSink sink) throws IOException
ByteSink
.IOException
- if an I/O error occurs while reading from this source or writing to sink
public byte[] read() throws IOException
IOException
- if an I/O error occurs while reading from this source@Beta @CanIgnoreReturnValue public <T> T read(ByteProcessor<T> processor) throws IOException
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.IOException
- if an I/O error occurs while reading from this source or if processor
throws an IOException
public HashCode hash(HashFunction hashFunction) throws IOException
IOException
- if an I/O error occurs while reading from this sourcepublic boolean contentEquals(ByteSource other) throws IOException
IOException
- if an I/O error occurs while reading from this source or other
public static ByteSource concat(Iterable<? extends ByteSource> sources)
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.
sources
- the sources to concatenateByteSource
containing the concatenated datapublic static ByteSource concat(Iterator<? extends ByteSource> sources)
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.
sources
- the sources to concatenateByteSource
containing the concatenated dataNullPointerException
- if any of sources
is null
public static ByteSource concat(ByteSource... sources)
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.
sources
- the sources to concatenateByteSource
containing the concatenated dataNullPointerException
- if any of sources
is null
public static ByteSource wrap(byte[] b)
ByteSource
. To view only a specific range
in the array, use ByteSource.wrap(b).slice(offset, length)
.ByteStreams.asByteSource(byte[])
).public static ByteSource empty()
ByteSource
that contains no bytes.Copyright © 2010–2019. All rights reserved.