Source
Supplies a stream of bytes. Use this interface to read data from wherever it's located: from the network, storage, or a buffer in memory. Sources may be layered to transform supplied data, such as to decompress, decrypt, or remove protocol framing.
Most applications shouldn't operate on a source directly, but rather on a BufferedSource which is both more efficient and more convenient. Use buffer to wrap any source with a buffer.
Sources are easy to test: just use a Buffer in your tests, and fill it with the data your application is to read.
Comparison with InputStream
This interface is functionally equivalent to java.io.InputStream.
InputStream
requires multiple layers when consumed data is heterogeneous: a DataInputStream
for primitive values, a BufferedInputStream
for buffering, and InputStreamReader
for strings. This library uses BufferedSource
for all of the above.
Source avoids the impossible-to-implement java.io.InputStream.available method. Instead callers specify how many bytes they require.
Source omits the unsafe-to-compose java.io.InputStream.mark state that's tracked by InputStream
; instead, callers just buffer what they need.
When implementing a source, you don't need to worry about the java.io.InputStream.read method that is awkward to implement efficiently and returns one of 257 possible values.
And source has a stronger skip
method: BufferedSource.skip won't return prematurely.
Interop with InputStream
Use source to adapt an InputStream
to a source. Use BufferedSource.inputStream to adapt a source to an InputStream
.