1 /* 2 * Copyright (C) 2014 Square, Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package okio; 17 18 import java.io.Closeable; 19 import java.io.IOException; 20 21 /** 22 * Supplies a stream of bytes. Use this interface to read data from wherever 23 * it's located: from the network, storage, or a buffer in memory. Sources may 24 * be layered to transform supplied data, such as to decompress, decrypt, or 25 * remove protocol framing. 26 * 27 * <p>Most applications shouldn't operate on a source directly, but rather 28 * {@link BufferedSource} which is both more efficient and more convenient. Use 29 * {@link Okio#buffer(Source)} to wrap any source with a buffer. 30 * 31 * <p>Sources are easy to test: just use an {@link Buffer} in your tests, and 32 * fill it with the data your application is to read. 33 * 34 * <h3>Comparison with InputStream</h3> 35 * This interface is functionally equivalent to {@link java.io.InputStream}. 36 * 37 * <p>{@code InputStream} requires multiple layers when consumed data is 38 * heterogeneous: a {@code DataInputStream} for primitive values, a {@code 39 * BufferedInputStream} for buffering, and {@code InputStreamReader} for 40 * strings. This class uses {@code BufferedSource} for all of the above. 41 * 42 * <p>Source avoids the impossible-to-implement {@linkplain 43 * java.io.InputStream#available available()} method. Instead callers specify 44 * how many bytes they {@link BufferedSource#require require}. 45 * 46 * <p>Source omits the unsafe-to-compose {@linkplain java.io.InputStream#mark 47 * mark and reset} state that's tracked by {@code InputStream}; callers instead 48 * just buffer what they need. 49 * 50 * <p>When implementing a source, you need not worry about the {@linkplain 51 * java.io.InputStream#read single-byte read} method that is awkward to 52 * implement efficiently and that returns one of 257 possible values. 53 * 54 * <p>And source has a stronger {@code skip} method: {@link BufferedSource#skip} 55 * won't return prematurely. 56 * 57 * <h3>Interop with InputStream</h3> 58 * Use {@link Okio#source} to adapt an {@code InputStream} to a source. Use 59 * {@link BufferedSource#inputStream} to adapt a source to an {@code 60 * InputStream}. 61 */ 62 public interface Source extends Closeable { 63 /** 64 * Removes at least 1, and up to {@code byteCount} bytes from this and appends 65 * them to {@code sink}. Returns the number of bytes read, or -1 if this 66 * source is exhausted. 67 */ 68 long read(Buffer sink, long byteCount) throws IOException; 69 70 /** Returns the timeout for this source. */ 71 Timeout timeout(); 72 73 /** 74 * Closes this source and releases the resources held by this source. It is an 75 * error to read a closed source. It is safe to close a source more than once. 76 */ 77 @Override void close() throws IOException; 78 } 79
