Home | History | Annotate | only in /external/okhttp/okio
Up to higher level directory
NameDateSize
benchmarks/21-Oct-2016
BUG-BOUNTY.md21-Oct-2016364
CHANGELOG.md21-Oct-20164.4K
checkstyle.xml21-Oct-20164.6K
CONTRIBUTING.md21-Oct-2016730
deploy_javadoc.sh21-Oct-2016782
LICENSE.txt21-Oct-201611.1K
MODULE_LICENSE_APACHE221-Oct-20160
okio/21-Oct-2016
pom.xml21-Oct-20163.1K
README.android21-Oct-2016467
README.md21-Oct-20165.1K

README.android

      1 URL: https://github.com/square/okio
      2 License: Apache 2
      3 Description: "A modern I/O API for Java"
      4 
      5 Local patches
      6 -------------
      7 
      8 All source changes (besides imports) marked with ANDROID-BEGIN and ANDROID-END:
      9   - Removal of reference to a codehause annotation used in
     10     okio/src/main/java/okio/DeflaterSink.java
     11   - Commenting of code that references APIs not present on Android.
     12   - Removal of test code that uses JUnit 4.11 features such as @Parameterized.Parameters
     13

README.md

      1 Okio
      2 ====
      3 
      4 Okio is a new library that complements `java.io` and `java.nio` to make it much
      5 easier to access, store, and process your data.
      6 
      7 ByteStrings and Buffers
      8 -----------------------
      9 
     10 Okio is built around two types that pack a lot of capability into a
     11 straightforward API:
     12 
     13  * [**ByteString**][3] is an immutable sequence of bytes. For character data, `String`
     14    is fundamental. `ByteString` is String's long-lost brother, making it easy to
     15    treat binary data as a value. This class is ergonomic: it knows how to encode
     16    and decode itself as hex, base64, and UTF-8.
     17 
     18  * [**Buffer**][4] is a mutable sequence of bytes. Like `ArrayList`, you don't need
     19    to size your buffer in advance. You read and write buffers as a queue: write
     20    data to the end and read it from the front. There's no obligation to manage
     21    positions, limits, or capacities.
     22 
     23 Internally, `ByteString` and `Buffer` do some clever things to save CPU and
     24 memory. If you encode a UTF-8 string as a `ByteString`, it caches a reference to
     25 that string so that if you decode it later, there's no work to do.
     26 
     27 `Buffer` is implemented as a linked list of segments. When you move data from
     28 one buffer to another, it _reassigns ownership_ of the segments rather than
     29 copying the data across. This approach is particularly helpful for multithreaded
     30 programs: a thread that talks to the network can exchange data with a worker
     31 thread without any copying or ceremony.
     32 
     33 Sources and Sinks
     34 -----------------
     35 
     36 An elegant part of the `java.io` design is how streams can be layered for
     37 transformations like encryption and compression. Okio includes its own stream
     38 types called [`Source`][5] and [`Sink`][6] that work like `InputStream` and
     39 `OutputStream`, but with some key differences:
     40 
     41  * **Timeouts.** The streams provide access to the timeouts of the underlying
     42    I/O mechanism. Unlike the `java.io` socket streams, both `read()` and
     43    `write()` calls honor timeouts.
     44 
     45  * **Easy to implement.** `Source` declares three methods: `read()`, `close()`,
     46    and `timeout()`. There are no hazards like `available()` or single-byte reads
     47    that cause correctness and performance surprises.
     48 
     49  * **Easy to use.** Although _implementations_ of `Source` and `Sink` have only
     50    three methods to write, _callers_ are given a rich API with the
     51    [`BufferedSource`][7] and [`BufferedSink`][8] interfaces. These interfaces give you
     52    everything you need in one place.
     53 
     54  * **No artificial distinction between byte streams and char streams.** It's all
     55    data. Read and write it as bytes, UTF-8 strings, big-endian 32-bit integers,
     56    little-endian shorts; whatever you want. No more `InputStreamReader`!
     57 
     58  * **Easy to test.** The `Buffer` class implements both `BufferedSource` and
     59    `BufferedSink` so your test code is simple and clear.
     60 
     61 Sources and sinks interoperate with `InputStream` and `OutputStream`. You can
     62 view any `Source` as an `InputStream`, and you can view any `InputStream` as a
     63 `Source`. Similarly for `Sink` and `OutputStream`.
     64 
     65 Dependable
     66 ----------
     67 
     68 Okio started as a component of [OkHttp][1], the capable HTTP+SPDY client
     69 included in Android. It's well-exercised and ready to solve new problems.
     70 
     71 
     72 Example: a PNG decoder
     73 ----------------------
     74 
     75 Decoding the chunks of a PNG file demonstrates Okio in practice.
     76 
     77 ```java
     78 private static final ByteString PNG_HEADER = ByteString.decodeHex("89504e470d0a1a0a");
     79 
     80 public void decodePng(InputStream in) throws IOException {
     81   BufferedSource pngSource = Okio.buffer(Okio.source(in));
     82 
     83   ByteString header = pngSource.readByteString(PNG_HEADER.size());
     84   if (!header.equals(PNG_HEADER)) {
     85     throw new IOException("Not a PNG.");
     86   }
     87 
     88   while (true) {
     89     Buffer chunk = new Buffer();
     90 
     91     // Each chunk is a length, type, data, and CRC offset.
     92     int length = pngSource.readInt();
     93     String type = pngSource.readUtf8(4);
     94     pngSource.readFully(chunk, length);
     95     int crc = pngSource.readInt();
     96 
     97     decodeChunk(type, chunk);
     98     if (type.equals("IEND")) break;
     99   }
    100 
    101   pngSource.close();
    102 }
    103 
    104 private void decodeChunk(String type, Buffer chunk) {
    105   if (type.equals("IHDR")) {
    106     int width = chunk.readInt();
    107     int height = chunk.readInt();
    108     System.out.printf("%08x: %s %d x %d%n", chunk.size(), type, width, height);
    109   } else {
    110     System.out.printf("%08x: %s%n", chunk.size(), type);
    111   }
    112 }
    113 ```
    114 
    115 Download
    116 --------
    117 
    118 Download [the latest JAR][2] or grab via Maven:
    119 ```xml
    120 <dependency>
    121     <groupId>com.squareup.okio</groupId>
    122     <artifactId>okio</artifactId>
    123     <version>1.6.0</version>
    124 </dependency>
    125 ```
    126 or Gradle:
    127 ```groovy
    128 compile 'com.squareup.okio:okio:1.6.0'
    129 ```
    130 
    131 Snapshots of the development version are available in [Sonatype's `snapshots` repository][snap].
    132 
    133 
    134  [1]: https://github.com/square/okhttp
    135  [2]: https://search.maven.org/remote_content?g=com.squareup.okio&a=okio&v=LATEST
    136  [3]: http://square.github.io/okio/okio/ByteString.html
    137  [4]: http://square.github.io/okio/okio/Buffer.html
    138  [5]: http://square.github.io/okio/okio/Source.html
    139  [6]: http://square.github.io/okio/okio/Sink.html
    140  [7]: http://square.github.io/okio/okio/BufferedSource.html
    141  [8]: http://square.github.io/okio/okio/BufferedSink.html
    142  [snap]: https://oss.sonatype.org/content/repositories/snapshots/
    143