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.IOException; 19 import java.io.InputStream; 20 21 /** 22 * A source that keeps a buffer internally so that callers can do small reads 23 * without a performance penalty. It also allows clients to read ahead, 24 * buffering as much as necessary before consuming input. 25 */ 26 public interface BufferedSource extends Source { 27 /** Returns this source's internal buffer. */ 28 OkBuffer buffer(); 29 30 /** 31 * Returns true if there are no more bytes in this source. This will block 32 * until there are bytes to read or the source is definitely exhausted. 33 */ 34 boolean exhausted() throws IOException; 35 36 /** 37 * Returns when the buffer contains at least {@code byteCount} bytes. Throws 38 * an {@link java.io.EOFException} if the source is exhausted before the 39 * required bytes can be read. 40 */ 41 void require(long byteCount) throws IOException; 42 43 /** Removes a byte from this source and returns it. */ 44 byte readByte() throws IOException; 45 46 /** Removes two bytes from this source and returns a big-endian short. */ 47 short readShort() throws IOException; 48 49 /** Removes two bytes from this source and returns a little-endian short. */ 50 short readShortLe() throws IOException; 51 52 /** Removes four bytes from this source and returns a big-endian int. */ 53 int readInt() throws IOException; 54 55 /** Removes four bytes from this source and returns a little-endian int. */ 56 int readIntLe() throws IOException; 57 58 /** Removes eight bytes from this source and returns a big-endian long. */ 59 long readLong() throws IOException; 60 61 /** Removes eight bytes from this source and returns a little-endian long. */ 62 long readLongLe() throws IOException; 63 64 /** 65 * Reads and discards {@code byteCount} bytes from this source. Throws an 66 * {@link java.io.EOFException} if the source is exhausted before the 67 * requested bytes can be skipped. 68 */ 69 void skip(long byteCount) throws IOException; 70 71 /** Removes {@code byteCount} bytes from this and returns them as a byte string. */ 72 ByteString readByteString(long byteCount) throws IOException; 73 74 /** 75 * Removes {@code byteCount} bytes from this, decodes them as UTF-8 and 76 * returns the string. 77 */ 78 String readUtf8(long byteCount) throws IOException; 79 80 /** 81 * Removes and returns characters up to but not including the next line break. 82 * A line break is either {@code "\n"} or {@code "\r\n"}; these characters are 83 * not included in the result. 84 * 85 * <p><strong>On the end of the stream this method returns null,</strong> just 86 * like {@link java.io.BufferedReader}. If the source doesn't end with a line 87 * break then an implicit line break is assumed. Null is returned once the 88 * source is exhausted. Use this for human-generated data, where a trailing 89 * line break is optional. 90 */ 91 String readUtf8Line() throws IOException; 92 93 /** 94 * Removes and returns characters up to but not including the next line break. 95 * A line break is either {@code "\n"} or {@code "\r\n"}; these characters are 96 * not included in the result. 97 * 98 * <p><strong>On the end of the stream this method throws.</strong> Every call 99 * must consume either '\r\n' or '\n'. If these characters are absent in the 100 * stream, an {@link java.io.EOFException} is thrown. Use this for 101 * machine-generated data where a missing line break implies truncated input. 102 */ 103 String readUtf8LineStrict() throws IOException; 104 105 /** 106 * Returns the index of {@code b} in the buffer, refilling it if necessary 107 * until it is found. This reads an unbounded number of bytes into the buffer. 108 * Returns -1 if the stream is exhausted before the requested byte is found. 109 */ 110 long indexOf(byte b) throws IOException; 111 112 /** Returns an input stream that reads from this source. */ 113 InputStream inputStream(); 114 } 115
