1Okio 2==== 3 4Okio is a library that complements `java.io` and `java.nio` to make it much 5easier to access, store, and process your data. It started as a component of 6[OkHttp][1], the capable HTTP client included in Android. It's well-exercised 7and ready to solve new problems. 8 9ByteStrings and Buffers 10----------------------- 11 12Okio is built around two types that pack a lot of capability into a 13straightforward API: 14 15 * [**ByteString**][3] is an immutable sequence of bytes. For character data, `String` 16 is fundamental. `ByteString` is String's long-lost brother, making it easy to 17 treat binary data as a value. This class is ergonomic: it knows how to encode 18 and decode itself as hex, base64, and UTF-8. 19 20 * [**Buffer**][4] is a mutable sequence of bytes. Like `ArrayList`, you don't need 21 to size your buffer in advance. You read and write buffers as a queue: write 22 data to the end and read it from the front. There's no obligation to manage 23 positions, limits, or capacities. 24 25Internally, `ByteString` and `Buffer` do some clever things to save CPU and 26memory. If you encode a UTF-8 string as a `ByteString`, it caches a reference to 27that string so that if you decode it later, there's no work to do. 28 29`Buffer` is implemented as a linked list of segments. When you move data from 30one buffer to another, it _reassigns ownership_ of the segments rather than 31copying the data across. This approach is particularly helpful for multithreaded 32programs: a thread that talks to the network can exchange data with a worker 33thread without any copying or ceremony. 34 35Sources and Sinks 36----------------- 37 38An elegant part of the `java.io` design is how streams can be layered for 39transformations like encryption and compression. Okio includes its own stream 40types called [`Source`][5] and [`Sink`][6] that work like `InputStream` and 41`OutputStream`, but with some key differences: 42 43 * **Timeouts.** The streams provide access to the timeouts of the underlying 44 I/O mechanism. Unlike the `java.io` socket streams, both `read()` and 45 `write()` calls honor timeouts. 46 47 * **Easy to implement.** `Source` declares three methods: `read()`, `close()`, 48 and `timeout()`. There are no hazards like `available()` or single-byte reads 49 that cause correctness and performance surprises. 50 51 * **Easy to use.** Although _implementations_ of `Source` and `Sink` have only 52 three methods to write, _callers_ are given a rich API with the 53 [`BufferedSource`][7] and [`BufferedSink`][8] interfaces. These interfaces give you 54 everything you need in one place. 55 56 * **No artificial distinction between byte streams and char streams.** It's all 57 data. Read and write it as bytes, UTF-8 strings, big-endian 32-bit integers, 58 little-endian shorts; whatever you want. No more `InputStreamReader`! 59 60 * **Easy to test.** The `Buffer` class implements both `BufferedSource` and 61 `BufferedSink` so your test code is simple and clear. 62 63Sources and sinks interoperate with `InputStream` and `OutputStream`. You can 64view any `Source` as an `InputStream`, and you can view any `InputStream` as a 65`Source`. Similarly for `Sink` and `OutputStream`. 66 67 68Presentations 69------------- 70 71[A Few “Ok” Libraries][ok_libraries_talk] ([slides][ok_libraries_slides]): An introduction to Okio 72and three libraries written with it. 73 74[Decoding the Secrets of Binary Data][encoding_talk] ([slides][encoding_slides]): How data encoding 75works and how Okio does it. 76 77[Ok Multiplatform!][ok_multiplatform_talk] ([slides][ok_multiplatform_slides]): How we changed 78Okio’s implementation language from Java to Kotlin. 79 80[Nerding Out On Okio][apis_talk]: The story of the Okio APIs, their design and tradeoffs, as well 81as implementation notes with animated marbles diagrams. 82 83 84Requirements 85------------ 86 87Okio 2.x supports Android 4.0.3+ (API level 15+) and Java 7+. 88 89Okio 3.x supports Android 4.0.3+ (API level 15+) and Java 8+. 90 91Okio depends on the [Kotlin standard library][kotlin]. It is a small library with strong 92backward-compatibility. 93 94 95Releases 96-------- 97 98Our [change log][changelog] has release history. 99 100```kotlin 101implementation("com.squareup.okio:okio:3.7.0") 102``` 103 104<details> 105 <summary>Snapshot builds are also available</summary> 106 107```kotlin 108repositories { 109 maven("https://s01.oss.sonatype.org/content/repositories/snapshots/") 110} 111 112dependencies { 113 implementation("com.squareup.okio:okio:3.7.0") 114} 115``` 116 117</details> 118 119 120License 121-------- 122 123 Copyright 2013 Square, Inc. 124 125 Licensed under the Apache License, Version 2.0 (the "License"); 126 you may not use this file except in compliance with the License. 127 You may obtain a copy of the License at 128 129 http://www.apache.org/licenses/LICENSE-2.0 130 131 Unless required by applicable law or agreed to in writing, software 132 distributed under the License is distributed on an "AS IS" BASIS, 133 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 134 See the License for the specific language governing permissions and 135 limitations under the License. 136 137 [1]: https://github.com/square/okhttp 138 [3]: https://square.github.io/okio/3.x/okio/okio/okio/-byte-string/index.html 139 [4]: https://square.github.io/okio/3.x/okio/okio/okio/-buffer/index.html 140 [5]: https://square.github.io/okio/3.x/okio/okio/okio/-source/index.html 141 [6]: https://square.github.io/okio/3.x/okio/okio/okio/-sink/index.html 142 [7]: https://square.github.io/okio/3.x/okio/okio/okio/-buffered-source/index.html 143 [8]: https://square.github.io/okio/3.x/okio/okio/okio/-buffered-sink/index.html 144 [changelog]: http://square.github.io/okio/changelog/ 145 [javadoc]: https://square.github.io/okio/2.x/okio/okio/index.html 146 [kotlin]: https://kotlinlang.org/ 147 [ok_libraries_talk]: https://www.youtube.com/watch?v=WvyScM_S88c 148 [ok_libraries_slides]: https://speakerdeck.com/jakewharton/a-few-ok-libraries-droidcon-mtl-2015 149 [encoding_talk]: https://www.youtube.com/watch?v=T_p22jMZSrk 150 [encoding_slides]: https://speakerdeck.com/swankjesse/decoding-the-secrets-of-binary-data-droidcon-nyc-2016 151 [ok_multiplatform_talk]: https://www.youtube.com/watch?v=Q8B4eDirgk0 152 [ok_multiplatform_slides]: https://speakerdeck.com/swankjesse/ok-multiplatform 153 [apis_talk]: https://www.youtube.com/watch?v=Du7YXPAV1M8 154