From e2d95bfaf2f3e3623bbae8937b79306767d5af78 Mon Sep 17 00:00:00 2001 From: Jesse Wilson Date: Mon, 3 Mar 2014 02:16:05 -0500 Subject: [PATCH] Docs for Source and Sink. --- okio/src/main/java/okio/BufferedSink.java | 5 +++ okio/src/main/java/okio/BufferedSource.java | 1 + okio/src/main/java/okio/Sink.java | 28 ++++++++++++++- okio/src/main/java/okio/Source.java | 40 ++++++++++++++++++++- 4 files changed, 72 insertions(+), 2 deletions(-) diff --git a/okio/src/main/java/okio/BufferedSink.java b/okio/src/main/java/okio/BufferedSink.java index ac3449b73..e5cc42d20 100644 --- a/okio/src/main/java/okio/BufferedSink.java +++ b/okio/src/main/java/okio/BufferedSink.java @@ -23,6 +23,7 @@ import java.io.OutputStream; * without a performance penalty. */ public interface BufferedSink extends Sink { + /** Returns this sink's internal buffer. */ OkBuffer buffer(); BufferedSink write(ByteString byteString) throws IOException; @@ -39,12 +40,16 @@ public interface BufferedSink extends Sink { */ BufferedSink write(byte[] source, int offset, int byteCount) throws IOException; + /** Encodes {@code string} in UTF-8 and writes it to this sink. */ BufferedSink writeUtf8(String string) throws IOException; + /** Writes byte to the end of this sink. */ BufferedSink writeByte(int b) throws IOException; + /** Writes a Big-Endian short to the end of this sink. */ BufferedSink writeShort(int s) throws IOException; + /** Writes a Big-Endian int to the end of this sink. */ BufferedSink writeInt(int i) throws IOException; /** Writes complete segments to the sink. Like {@link #flush}, but weaker. */ diff --git a/okio/src/main/java/okio/BufferedSource.java b/okio/src/main/java/okio/BufferedSource.java index 84d079265..678721b09 100644 --- a/okio/src/main/java/okio/BufferedSource.java +++ b/okio/src/main/java/okio/BufferedSource.java @@ -24,6 +24,7 @@ import java.io.InputStream; * buffering as much as necessary before consuming input. */ public interface BufferedSource extends Source { + /** Returns this source's internal buffer. */ OkBuffer buffer(); /** diff --git a/okio/src/main/java/okio/Sink.java b/okio/src/main/java/okio/Sink.java index 8510ceb56..402aa0fc3 100644 --- a/okio/src/main/java/okio/Sink.java +++ b/okio/src/main/java/okio/Sink.java @@ -19,7 +19,33 @@ import java.io.Closeable; import java.io.IOException; /** - * An alternative to OutputStream. + * Receives a stream of bytes. Use this interface to write data wherever it's + * needed: to the network, storage, or a buffer in memory. Sinks may be layered + * to transform received data, such as to compress, encrypt, throttle, or add + * protocol framing. + * + *

Most application code shouldn't operate on a sink directly, but rather + * {@link BufferedSink} which is both more efficient and more convenient. Use + * {@link Okio#buffer(Sink)} to wrap any sink with a buffer. + * + *

Sinks are easy to test: just use an {@link OkBuffer} in your tests, and + * read from it to confirm it received the data that was expected. + * + *

Comparison with OutputStream

+ * This interface is functionally equivalent to {@link java.io.OutputStream}. + * + *

{@code OutputStream} requires multiple layers when emitted data is + * heterogeneous: a {@code DataOutputStream} for primitive values, a {@code + * BufferedOutputStream} for buffering, and {@code OutputStreamWriter} for + * charset encoding. This class uses {@code BufferedSink} for all of the above. + * + *

Sink is also easier to layer: there is no {@link + * java.io.OutputStream#write(int) single-byte write} method that is awkward to + * implement efficiently. + * + *

Interop with OutputStream

+ * Use {@link Okio#sink} to adapt an {@code OutputStream} to a sink. Use {@link + * BufferedSink#outputStream} to adapt a sink to an {@code OutputStream}. */ public interface Sink extends Closeable { /** Removes {@code byteCount} bytes from {@code source} and appends them to this. */ diff --git a/okio/src/main/java/okio/Source.java b/okio/src/main/java/okio/Source.java index bd73c04dc..d402beed3 100644 --- a/okio/src/main/java/okio/Source.java +++ b/okio/src/main/java/okio/Source.java @@ -19,7 +19,45 @@ import java.io.Closeable; import java.io.IOException; /** - * An alternative to InputStream. + * 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 + * {@link BufferedSource} which is both more efficient and more convenient. Use + * {@link Okio#buffer(Source)} to wrap any source with a buffer. + * + *

Sources are easy to test: just use an {@link OkBuffer} in your tests, and + * fill it with the data your application is to read. + * + *

Comparison with InputStream

+ * This interface is functionally equivalent to {@link java.io.InputStream}. + * + *

{@code InputStream} requires multiple layers when consumed data is + * heterogeneous: a {@code DataOutputStream} for primitive values, a {@code + * BufferedInputStream} for buffering, and {@code InputStreamReader} for + * strings. This class uses {@code BufferedSource} for all of the above. + * + *

Source avoids the impossible-to-implement {@link + * java.io.InputStream#available available()} method. Instead callers specify + * how many bytes they {@link BufferedSource#require require}. + * + *

Source omits the unsafe-to-compose {@link java.io.InputStream#mark mark + * and reset} state that's tracked by {@code InputStream}; callers instead just + * buffer what they need. + * + *

When implementing a source, you need not worry about the {@link + * java.io.InputStream#read single-byte read} method that is awkward to + * implement efficiently and that returns one of 257 possible values. + * + *

And source has a stronger {@code skip} method: {@link BufferedSource#skip} + * won't return prematurely. + * + *

Interop with InputStream

+ * Use {@link Okio#source} to adapt an {@code InputStream} to a source. Use + * {@link BufferedSource#inputStream} to adapt a source to an {@code + * InputStream}. */ public interface Source extends Closeable { /**