13c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller/* 23c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Copyright (C) 2014 Square, Inc. 33c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 43c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Licensed under the Apache License, Version 2.0 (the "License"); 53c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * you may not use this file except in compliance with the License. 63c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * You may obtain a copy of the License at 73c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 83c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * http://www.apache.org/licenses/LICENSE-2.0 93c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 103c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Unless required by applicable law or agreed to in writing, software 113c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * distributed under the License is distributed on an "AS IS" BASIS, 123c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 133c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * See the License for the specific language governing permissions and 143c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * limitations under the License. 153c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 163c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerpackage okio; 173c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 183c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerimport java.io.Closeable; 193c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerimport java.io.IOException; 203c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 213c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller/** 223c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Supplies a stream of bytes. Use this interface to read data from wherever 233c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * it's located: from the network, storage, or a buffer in memory. Sources may 243c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * be layered to transform supplied data, such as to decompress, decrypt, or 253c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * remove protocol framing. 263c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 273c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <p>Most applications shouldn't operate on a source directly, but rather 283c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * {@link BufferedSource} which is both more efficient and more convenient. Use 293c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * {@link Okio#buffer(Source)} to wrap any source with a buffer. 303c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 313c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <p>Sources are easy to test: just use an {@link OkBuffer} in your tests, and 323c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * fill it with the data your application is to read. 333c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 343c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <h3>Comparison with InputStream</h3> 353c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * This interface is functionally equivalent to {@link java.io.InputStream}. 363c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 373c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <p>{@code InputStream} requires multiple layers when consumed data is 383c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * heterogeneous: a {@code DataOutputStream} for primitive values, a {@code 393c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * BufferedInputStream} for buffering, and {@code InputStreamReader} for 403c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * strings. This class uses {@code BufferedSource} for all of the above. 413c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 423c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <p>Source avoids the impossible-to-implement {@link 433c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * java.io.InputStream#available available()} method. Instead callers specify 443c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * how many bytes they {@link BufferedSource#require require}. 453c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 463c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <p>Source omits the unsafe-to-compose {@link java.io.InputStream#mark mark 473c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * and reset} state that's tracked by {@code InputStream}; callers instead just 483c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * buffer what they need. 493c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 503c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <p>When implementing a source, you need not worry about the {@link 513c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * java.io.InputStream#read single-byte read} method that is awkward to 523c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * implement efficiently and that returns one of 257 possible values. 533c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 543c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <p>And source has a stronger {@code skip} method: {@link BufferedSource#skip} 553c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * won't return prematurely. 563c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * 573c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * <h3>Interop with InputStream</h3> 583c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Use {@link Okio#source} to adapt an {@code InputStream} to a source. Use 593c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * {@link BufferedSource#inputStream} to adapt a source to an {@code 603c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * InputStream}. 613c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 623c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerpublic interface Source extends Closeable { 633c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** 643c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Removes at least 1, and up to {@code byteCount} bytes from this and appends 653c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * them to {@code sink}. Returns the number of bytes read, or -1 if this 663c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * source is exhausted. 673c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 683c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller long read(OkBuffer sink, long byteCount) throws IOException; 693c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 703c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** 713c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Sets the deadline for all operations on this source. 723c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * @return this source. 733c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 743c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller Source deadline(Deadline deadline); 753c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 763c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** 773c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * Closes this source and releases the resources held by this source. It is an 783c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * error to read a closed source. It is safe to close a source more than once. 793c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 803c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller @Override void close() throws IOException; 813c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller} 82