tessl/maven-com-squareup-okio--okio-jvm
A modern I/O library that complements java.io and java.nio to make it much easier to access, store, and process your data.
—
Pending
sources-sinks.mddocs/
Source and Sink Streaming
Source and Sink are Okio's streaming I/O abstractions. Sources supply bytes while Sinks receive bytes. Their buffered variants provide convenient methods for reading and writing common data types with automatic buffering for efficiency.
Capabilities
Source Interface
Basic interface for reading streams of bytes.
/**
* Supplies a stream of bytes
* Similar to InputStream but simpler and more efficient
*/
interface Source : Closeable {
/**
* Reads bytes from this source into the sink buffer
* @param sink Buffer to read bytes into
* @param byteCount Number of bytes to attempt to read
* @return Number of bytes actually read, or -1 if exhausted
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun read(sink: Buffer, byteCount: Long): Long
/**
* Returns the timeout policy for this source
* @return The timeout instance controlling read operations
*/
fun timeout(): Timeout
/**
* Closes this source and releases resources
* @throws IOException if an error occurs during closing
*/
@Throws(IOException::class)
override fun close()
}Sink Interface
Basic interface for writing streams of bytes.
/**
* Receives a stream of bytes
* Similar to OutputStream but simpler and more efficient
*/
interface Sink : Closeable {
/**
* Writes bytes from the source buffer to this sink
* @param source Buffer containing bytes to write
* @param byteCount Number of bytes to write
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun write(source: Buffer, byteCount: Long)
/**
* Flushes any buffered bytes to the underlying sink
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun flush()
/**
* Returns the timeout policy for this sink
* @return The timeout instance controlling write operations
*/
fun timeout(): Timeout
/**
* Closes this sink and releases resources
* @throws IOException if an error occurs during closing
*/
@Throws(IOException::class)
override fun close()
}BufferedSource Interface
Source with internal buffering for efficient reading operations.
/**
* Source with an internal buffer for efficient reading
* Provides convenient methods for reading common data types
*/
interface BufferedSource : Source {
/**
* Internal buffer used for buffering operations
*/
val buffer: Buffer
/**
* Checks if this source is exhausted (no more bytes available)
* @return true if no more bytes can be read
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun exhausted(): Boolean
/**
* Ensures at least byteCount bytes are buffered
* @param byteCount Minimum number of bytes to buffer
* @throws EOFException if insufficient bytes are available
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun require(byteCount: Long)
/**
* Attempts to buffer at least byteCount bytes
* @param byteCount Number of bytes to attempt to buffer
* @return true if the requested bytes are available
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun request(byteCount: Long): Boolean
/**
* Reads and removes a single byte
* @return Byte value
* @throws EOFException if source is exhausted
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readByte(): Byte
/**
* Reads and removes a 16-bit integer in big-endian format
* @return Short value
* @throws EOFException if insufficient bytes available
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readShort(): Short
/**
* Reads and removes a 16-bit integer in little-endian format
* @return Short value
* @throws EOFException if insufficient bytes available
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readShortLe(): Short
/**
* Reads and removes a 32-bit integer in big-endian format
* @return Int value
* @throws EOFException if insufficient bytes available
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readInt(): Int
/**
* Reads and removes a 32-bit integer in little-endian format
* @return Int value
* @throws EOFException if insufficient bytes available
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readIntLe(): Int
/**
* Reads and removes a 64-bit integer in big-endian format
* @return Long value
* @throws EOFException if insufficient bytes available
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readLong(): Long
/**
* Reads and removes a 64-bit integer in little-endian format
* @return Long value
* @throws EOFException if insufficient bytes available
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readLongLe(): Long
/**
* Reads all remaining bytes as UTF-8 string
* @return String representation of remaining bytes
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readUtf8(): String
/**
* Reads and removes the specified number of UTF-8 bytes
* @param byteCount Number of bytes to read
* @return String representation of the bytes
* @throws EOFException if insufficient bytes available
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readUtf8(byteCount: Long): String
/**
* Reads a UTF-8 line, ending with \n or \r\n
* @return String line without line terminator, or null if exhausted
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readUtf8Line(): String?
/**
* Reads a UTF-8 line, requiring a line terminator
* @param limit Maximum line length to prevent excessive memory usage
* @return String line without line terminator
* @throws EOFException if no line terminator found within limit
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readUtf8LineStrict(limit: Long = Long.MAX_VALUE): String
/**
* Skips the specified number of bytes
* @param byteCount Number of bytes to skip
* @throws EOFException if insufficient bytes to skip
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun skip(byteCount: Long)
/**
* Reads all remaining bytes as ByteString
* @return ByteString containing all remaining bytes
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readByteString(): ByteString
/**
* Reads the specified number of bytes as ByteString
* @param byteCount Number of bytes to read
* @return ByteString containing the specified bytes
* @throws EOFException if insufficient bytes available
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readByteString(byteCount: Long): ByteString
/**
* Selects from the given options, consuming the selected option from this source
* @param options Options containing ByteStrings to match against
* @return Index of the selected option, or -1 if none match
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun select(options: Options): Int
/**
* Selects from the given typed options, consuming the selected option from this source
* @param options TypedOptions containing values to match against
* @return The selected value, or null if none match
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun <T : Any> select(options: TypedOptions<T>): T?
/**
* Reads all remaining bytes into a byte array
* @return Byte array containing all remaining bytes
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readByteArray(): ByteArray
/**
* Reads the specified number of bytes into a byte array
* @param byteCount Number of bytes to read
* @return Byte array containing the specified bytes
* @throws EOFException if insufficient bytes available
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun readByteArray(byteCount: Long): ByteArray
/**
* Creates a new source that reads a subset of bytes from this source
* Does not consume bytes from this source until the returned source is read
* @return New BufferedSource for peeking ahead
*/
fun peek(): BufferedSource
}BufferedSink Interface
Sink with internal buffering for efficient writing operations.
/**
* Sink with an internal buffer for efficient writing
* Provides convenient methods for writing common data types
*/
interface BufferedSink : Sink {
/**
* Internal buffer used for buffering operations
*/
val buffer: Buffer
/**
* Writes a ByteString to this sink
* @param byteString ByteString to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun write(byteString: ByteString): BufferedSink
/**
* Writes a portion of a ByteString to this sink
* @param byteString ByteString to write from
* @param offset Starting position in ByteString
* @param byteCount Number of bytes to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun write(byteString: ByteString, offset: Int, byteCount: Int): BufferedSink
/**
* Writes a byte array to this sink
* @param source Byte array to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun write(source: ByteArray): BufferedSink
/**
* Writes a portion of a byte array to this sink
* @param source Byte array to write from
* @param offset Starting position in array
* @param byteCount Number of bytes to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun write(source: ByteArray, offset: Int, byteCount: Int): BufferedSink
/**
* Writes all bytes from a source to this sink
* @param source Source to read all bytes from
* @return Number of bytes written
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeAll(source: Source): Long
/**
* Writes bytes from a source to this sink
* @param source Source to read bytes from
* @param byteCount Number of bytes to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun write(source: Source, byteCount: Long): BufferedSink
/**
* Writes a single byte
* @param b Byte value to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeByte(b: Int): BufferedSink
/**
* Writes a 16-bit integer in big-endian format
* @param s Short value to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeShort(s: Int): BufferedSink
/**
* Writes a 16-bit integer in little-endian format
* @param s Short value to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeShortLe(s: Int): BufferedSink
/**
* Writes a 32-bit integer in big-endian format
* @param i Int value to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeInt(i: Int): BufferedSink
/**
* Writes a 32-bit integer in little-endian format
* @param i Int value to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeIntLe(i: Int): BufferedSink
/**
* Writes a 64-bit integer in big-endian format
* @param v Long value to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeLong(v: Long): BufferedSink
/**
* Writes a 64-bit integer in little-endian format
* @param v Long value to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeLongLe(v: Long): BufferedSink
/**
* Writes a string as UTF-8 bytes
* @param string String to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeUtf8(string: String): BufferedSink
/**
* Writes a portion of a string as UTF-8 bytes
* @param string String to write from
* @param beginIndex Starting character index
* @param endIndex Ending character index
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeUtf8(string: String, beginIndex: Int, endIndex: Int): BufferedSink
/**
* Writes a UTF-8 code point
* @param codePoint Unicode code point to write
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeUtf8CodePoint(codePoint: Int): BufferedSink
/**
* Writes a long as decimal ASCII digits
* @param v Long value to write as decimal
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeDecimalLong(v: Long): BufferedSink
/**
* Writes a long as hexadecimal ASCII digits
* @param v Long value to write as hexadecimal
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun writeHexadecimalUnsignedLong(v: Long): BufferedSink
/**
* Emits buffered bytes to the underlying sink
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun emit(): BufferedSink
/**
* Emits complete segments to the underlying sink
* @return This sink for method chaining
* @throws IOException if an I/O error occurs
*/
@Throws(IOException::class)
fun emitCompleteSegments(): BufferedSink
}Options for Selection
Classes for efficient byte string selection from buffered sources.
/**
* An indexed set of byte strings for efficient selection
* Used with BufferedSource.select() for pattern matching
*/
class Options private constructor() : AbstractList<ByteString>, RandomAccess {
override val size: Int
override fun get(index: Int): ByteString
companion object {
/**
* Creates Options from a list of ByteStrings
* @param byteStrings ByteStrings to select from
* @return Options instance for selection
*/
fun of(vararg byteStrings: ByteString): Options
}
}
/**
* A typed set of values that may be selected from buffered sources
* Maps ByteString patterns to typed values
*/
class TypedOptions<T : Any> private constructor() : AbstractList<T>, RandomAccess {
override val size: Int
override fun get(index: Int): T
companion object {
/**
* Creates TypedOptions from values and an encoding function
* @param values Collection of values to select from
* @param encode Function to convert values to ByteStrings
* @return TypedOptions instance for typed selection
*/
inline fun <T : Any> of(
values: Iterable<T>,
encode: (T) -> ByteString
): TypedOptions<T>
}
}Creating Buffered Sources and Sinks
Utility functions for creating buffered sources and sinks.
/**
* Wraps a Source with buffering
* @return BufferedSource that buffers reads from this source
*/
fun Source.buffer(): BufferedSource
/**
* Wraps a Sink with buffering
* @return BufferedSink that buffers writes to this sink
*/
fun Sink.buffer(): BufferedSink
/**
* Creates a sink that discards all bytes written to it
* @return Sink that ignores all data
*/
fun blackholeSink(): Sink
/**
* Execute block then close this resource. This will be closed even if block throws.
* This is similar to Java's try-with-resources but more concise.
* @param block Function to execute with this resource
* @return Result of executing the block
* @throws Exception any exception thrown by block or during closing
*/
inline fun <T : Closeable?, R> T.use(block: (T) -> R): RUsage Examples:
// Basic source/sink usage
val buffer = Buffer()
val source: Source = buffer
val sink: Sink = buffer
// Write data
sink.write(Buffer().writeUtf8("Hello"), 5)
sink.flush()
// Read data
val readBuffer = Buffer()
val bytesRead = source.read(readBuffer, 1024)
println(readBuffer.readUtf8())
// Buffered operations
val bufferedSource = source.buffer()
val line = bufferedSource.readUtf8Line()
val number = bufferedSource.readInt()
val bufferedSink = sink.buffer()
bufferedSink.writeUtf8("Hello World")
.writeInt(42)
.writeLong(123456789L)
.flush()
// Resource management with use
FileSystem.SYSTEM.source("/tmp/file.txt".toPath()).use { source ->
val bufferedSource = source.buffer()
return bufferedSource.readUtf8()
}
// Chaining use with buffer
FileSystem.SYSTEM.sink("/tmp/output.txt".toPath()).buffer().use { sink ->
sink.writeUtf8("Hello World")
sink.writeInt(42)
}
// Using Options for selection
val options = Options.of("GET".encodeUtf8(), "POST".encodeUtf8(), "PUT".encodeUtf8())
val buffer = Buffer().writeUtf8("POST /api/users")
val selected = buffer.select(options)
when (selected) {
0 -> println("GET request")
1 -> println("POST request") // This will be selected
2 -> println("PUT request")
-1 -> println("No match")
}
// Using TypedOptions for typed selection
enum class HttpMethod { GET, POST, PUT }
val typedOptions = TypedOptions.of(
listOf(HttpMethod.GET, HttpMethod.POST, HttpMethod.PUT)
) { it.name.encodeUtf8() }
val method = buffer.select(typedOptions)
println("Selected method: $method")Install with Tessl CLI
npx tessl i tessl/maven-com-squareup-okio--okio-jvm