commonMain.okio.Source.kt Maven / Gradle / Ivy
/*
* Copyright (C) 2019 Square, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package okio
/**
* 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()][java.io.InputStream.available] method.
* Instead callers specify how many bytes they [require][BufferedSource.require].
*
* Source omits the unsafe-to-compose [mark and reset][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 [read()][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`.
*/
interface Source : Closeable {
/**
* 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.
*/
@Throws(IOException::class)
fun read(sink: Buffer, byteCount: Long): Long
/** Returns the timeout for this source. */
fun timeout(): Timeout
/**
* 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.
*/
@Throws(IOException::class)
override fun close()
}