Package okio

Interface Source

  • All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable
    All Known Subinterfaces:
    BufferedSource
    All Known Implementing Classes:
    Buffer, ForwardingSource, GzipSource, HashingSource, InflaterSource

    public interface Source
    extends java.io.Closeable
    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 Okio.buffer(Source) 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 InputStream.

    InputStream requires multiple layers when consumed data is heterogeneous: a DataInputStream for primitive values, a BufferedInputStream for buffering, and InputStreamReader for strings. This class uses BufferedSource for all of the above.

    Source avoids the impossible-to-implement available() method. Instead callers specify how many bytes they require.

    Source omits the unsafe-to-compose mark and reset 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 single-byte read method that is awkward to implement efficiently and returns one of 257 possible values.

    And source has a stronger skip method: BufferedSource.skip(long) won't return prematurely.

    Interop with InputStream

    Use Okio.source(java.io.InputStream) to adapt an InputStream to a source. Use BufferedSource.inputStream() to adapt a source to an InputStream.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void close()
      Closes this source and releases the resources held by this source.
      long read​(Buffer sink, long byteCount)
      Removes at least 1, and up to byteCount bytes from this and appends them to sink.
      Timeout timeout()
      Returns the timeout for this source.
    • Method Detail

      • read

        long read​(Buffer sink,
                  long byteCount)
           throws java.io.IOException
        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:
        java.io.IOException
      • timeout

        Timeout timeout()
        Returns the timeout for this source.
      • close

        void close()
            throws java.io.IOException
        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.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        java.io.IOException