Skip to content

okio / okio / Source

Source

(js, jvm, native) interface Source(js)

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 available() method. Instead callers specify how many bytes they require.

Source omits the unsafe-to-compose mark and reset 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 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.

(jvm)

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 available() method. Instead callers specify how many bytes they require.

Source omits the unsafe-to-compose mark and reset 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 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

Name Summary
(js, jvm, native) close Closes this source and releases the resources held by this source. It is an error to read a closed source. It is safe to close a source more than once.abstract fun close():Unit
(js, jvm, native) read Removes at least 1, and up to byteCount bytes from this and appends them to sink. Returns the number of bytes read, or -1 if this source is exhausted.abstract fun read(sink:Buffer, byteCount:Long):Long
(js, jvm, native) timeout Returns the timeout for this source.abstract fun timeout():Timeout

Extension Functions

Name Summary
(jvm) gzip Returns a GzipSource that gzip-decompresses this Source while reading.funSource.gzip():GzipSource
(jvm) inflate Returns an InflaterSource that DEFLATE-decompresses this Source while reading.funSource.inflate(inflater:Inflater= Inflater()):InflaterSource

Inheritors

Name Summary
(js, jvm, native) BufferedSource A source that keeps a buffer internally so that callers can do small reads without a performance penalty. It also allows clients to read ahead, buffering as much as necessary before consuming input.interface BufferedSource :Source
(jvm) ForwardingSource A Source which forwards calls to another. Useful for subclassing.abstract class ForwardingSource :Source
(jvm) GzipSource A source that uses GZIP to decompress data read from another source.class GzipSource :Source
(jvm) InflaterSource A source that uses DEFLATE to decompress data read from another source.class InflaterSource :Source