Source

interface Source : Closeable

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.

Functions

close
Link copied to clipboard
common
abstract override fun close()
Closes this source and releases the resources held by this source.
read
Link copied to clipboard
common
abstract fun read(sink: Buffer, byteCount: Long): Long
Removes at least 1, and up to byteCount bytes from this and appends them to sink.
timeout
Link copied to clipboard
common
abstract fun timeout(): Timeout
Returns the timeout for this source.

Inheritors

BufferedSource
Link copied to clipboard
HashingSource
Link copied to clipboard
CipherSource
Link copied to clipboard
ForwardingSource
Link copied to clipboard
GzipSource
Link copied to clipboard
InflaterSource
Link copied to clipboard

Extensions

buffer
Link copied to clipboard
common
fun Source.buffer(): BufferedSource
Returns a new source that buffers reads from source.
cipherSource
Link copied to clipboard
fun Source.cipherSource(cipher: Cipher): CipherSource
Returns a source that uses cipher to encrypt or decrypt this.
gzip
Link copied to clipboard
inline fun Source.gzip(): GzipSource
Returns a GzipSource that gzip-decompresses this Source while reading.
hashingSource
Link copied to clipboard
fun Source.hashingSource(mac: Mac): HashingSource
Returns a source that uses mac to hash this.
fun Source.hashingSource(digest: MessageDigest): HashingSource
Returns a source that uses digest to hash this.
inflate
Link copied to clipboard
inline fun Source.inflate(inflater: Inflater = Inflater()): InflaterSource
Returns an InflaterSource that DEFLATE-decompresses this Source while reading.