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 import java.nio.charset.Charset; 21 22 /** 23 * A source that keeps a buffer internally so that callers can do small reads 24 * without a performance penalty. It also allows clients to read ahead, 25 * buffering as much as necessary before consuming input. 26 */ 27 public interface BufferedSource extends Source { 28 /** Returns this source's internal buffer. */ buffer()29 Buffer buffer(); 30 31 /** 32 * Returns true if there are no more bytes in this source. This will block 33 * until there are bytes to read or the source is definitely exhausted. 34 */ exhausted()35 boolean exhausted() throws IOException; 36 37 /** 38 * Returns when the buffer contains at least {@code byteCount} bytes. Throws 39 * an {@link java.io.EOFException} if the source is exhausted before the 40 * required bytes can be read. 41 */ require(long byteCount)42 void require(long byteCount) throws IOException; 43 44 /** 45 * Returns true when the buffer contains at least {@code byteCount} bytes, 46 * expanding it as necessary. Returns false if the source is exhausted before 47 * the requested bytes can be read. 48 */ request(long byteCount)49 boolean request(long byteCount) throws IOException; 50 51 /** Removes a byte from this source and returns it. */ readByte()52 byte readByte() throws IOException; 53 54 /** Removes two bytes from this source and returns a big-endian short. */ readShort()55 short readShort() throws IOException; 56 57 /** Removes two bytes from this source and returns a little-endian short. */ readShortLe()58 short readShortLe() throws IOException; 59 60 /** Removes four bytes from this source and returns a big-endian int. */ readInt()61 int readInt() throws IOException; 62 63 /** Removes four bytes from this source and returns a little-endian int. */ readIntLe()64 int readIntLe() throws IOException; 65 66 /** Removes eight bytes from this source and returns a big-endian long. */ readLong()67 long readLong() throws IOException; 68 69 /** Removes eight bytes from this source and returns a little-endian long. */ readLongLe()70 long readLongLe() throws IOException; 71 72 /** 73 * Reads a long from this source in signed decimal form (i.e., as a string in base 10 with 74 * optional leading '-'). This will iterate until a non-digit character is found. 75 * 76 * @throws NumberFormatException if the found digits do not fit into a {@code long} or a decimal 77 * number was not present. 78 */ readDecimalLong()79 long readDecimalLong() throws IOException; 80 81 /** 82 * Reads a long form this source in hexadecimal form (i.e., as a string in base 16). This will 83 * iterate until a non-hexadecimal character is found. 84 * 85 * @throws NumberFormatException if the found hexadecimal does not fit into a {@code long} or 86 * hexadecimal was not found. 87 */ readHexadecimalUnsignedLong()88 long readHexadecimalUnsignedLong() throws IOException; 89 90 /** 91 * Reads and discards {@code byteCount} bytes from this source. Throws an 92 * {@link java.io.EOFException} if the source is exhausted before the 93 * requested bytes can be skipped. 94 */ skip(long byteCount)95 void skip(long byteCount) throws IOException; 96 97 /** Removes all bytes bytes from this and returns them as a byte string. */ readByteString()98 ByteString readByteString() throws IOException; 99 100 /** Removes {@code byteCount} bytes from this and returns them as a byte string. */ readByteString(long byteCount)101 ByteString readByteString(long byteCount) throws IOException; 102 103 /** Removes all bytes from this and returns them as a byte array. */ readByteArray()104 byte[] readByteArray() throws IOException; 105 106 /** Removes {@code byteCount} bytes from this and returns them as a byte array. */ readByteArray(long byteCount)107 byte[] readByteArray(long byteCount) throws IOException; 108 109 /** 110 * Removes up to {@code sink.length} bytes from this and copies them into {@code sink}. 111 * Returns the number of bytes read, or -1 if this source is exhausted. 112 */ read(byte[] sink)113 int read(byte[] sink) throws IOException; 114 115 /** 116 * Removes exactly {@code sink.length} bytes from this and copies them into {@code sink}. 117 * Throws an {@link java.io.EOFException} if the requested number of bytes cannot be read. 118 */ readFully(byte[] sink)119 void readFully(byte[] sink) throws IOException; 120 121 /** 122 * Removes up to {@code byteCount} bytes from this and copies them into {@code sink} at 123 * {@code offset}. Returns the number of bytes read, or -1 if this source is exhausted. 124 */ read(byte[] sink, int offset, int byteCount)125 int read(byte[] sink, int offset, int byteCount) throws IOException; 126 127 /** 128 * Removes exactly {@code byteCount} bytes from this and appends them to 129 * {@code sink}. Throws an {@link java.io.EOFException} if the requested 130 * number of bytes cannot be read. 131 */ readFully(Buffer sink, long byteCount)132 void readFully(Buffer sink, long byteCount) throws IOException; 133 134 /** 135 * Removes all bytes from this and appends them to {@code sink}. Returns the 136 * total number of bytes written to {@code sink} which will be 0 if this is 137 * exhausted. 138 */ readAll(Sink sink)139 long readAll(Sink sink) throws IOException; 140 141 /** Removes all bytes from this, decodes them as UTF-8, and returns the string. */ readUtf8()142 String readUtf8() throws IOException; 143 144 /** 145 * Removes {@code byteCount} bytes from this, decodes them as UTF-8, and 146 * returns the string. 147 */ readUtf8(long byteCount)148 String readUtf8(long byteCount) throws IOException; 149 150 /** 151 * Removes and returns characters up to but not including the next line break. 152 * A line break is either {@code "\n"} or {@code "\r\n"}; these characters are 153 * not included in the result. 154 * 155 * <p><strong>On the end of the stream this method returns null,</strong> just 156 * like {@link java.io.BufferedReader}. If the source doesn't end with a line 157 * break then an implicit line break is assumed. Null is returned once the 158 * source is exhausted. Use this for human-generated data, where a trailing 159 * line break is optional. 160 */ readUtf8Line()161 String readUtf8Line() throws IOException; 162 163 /** 164 * Removes and returns characters up to but not including the next line break. 165 * A line break is either {@code "\n"} or {@code "\r\n"}; these characters are 166 * not included in the result. 167 * 168 * <p><strong>On the end of the stream this method throws.</strong> Every call 169 * must consume either '\r\n' or '\n'. If these characters are absent in the 170 * stream, an {@link java.io.EOFException} is thrown. Use this for 171 * machine-generated data where a missing line break implies truncated input. 172 */ readUtf8LineStrict()173 String readUtf8LineStrict() throws IOException; 174 175 /** 176 * Removes and returns a single UTF-8 code point, reading between 1 and 4 bytes as necessary. 177 * 178 * <p>If this source is exhausted before a complete code point can be read, this throws an {@link 179 * java.io.EOFException} and consumes no input. 180 * 181 * <p>If this source doesn't start with a properly-encoded UTF-8 code point, this method will 182 * remove 1 or more non-UTF-8 bytes and return the replacement character ({@code U+FFFD}). This 183 * covers encoding problems (the input is not properly-encoded UTF-8), characters out of range 184 * (beyond the 0x10ffff limit of Unicode), code points for UTF-16 surrogates (U+d800..U+dfff) and 185 * overlong encodings (such as {@code 0xc080} for the NUL character in modified UTF-8). 186 */ readUtf8CodePoint()187 int readUtf8CodePoint() throws IOException; 188 189 /** 190 * Removes all bytes from this, decodes them as {@code charset}, and returns 191 * the string. 192 */ readString(Charset charset)193 String readString(Charset charset) throws IOException; 194 195 /** 196 * Removes {@code byteCount} bytes from this, decodes them as {@code charset}, 197 * and returns the string. 198 */ readString(long byteCount, Charset charset)199 String readString(long byteCount, Charset charset) throws IOException; 200 201 /** 202 * Returns the index of the first {@code b} in the buffer. This expands the 203 * buffer as necessary until {@code b} is found. This reads an unbounded 204 * number of bytes into the buffer. Returns -1 if the stream is exhausted 205 * before the requested byte is found. 206 */ indexOf(byte b)207 long indexOf(byte b) throws IOException; 208 209 /** 210 * Returns the index of the first {@code b} in the buffer at or after {@code 211 * fromIndex}. This expands the buffer as necessary until {@code b} is found. 212 * This reads an unbounded number of bytes into the buffer. Returns -1 if the 213 * stream is exhausted before the requested byte is found. 214 */ indexOf(byte b, long fromIndex)215 long indexOf(byte b, long fromIndex) throws IOException; 216 217 /** 218 * Returns the index of the first match for {@code bytes} in the buffer. This expands the buffer 219 * as necessary until {@code bytes} is found. This reads an unbounded number of bytes into the 220 * buffer. Returns -1 if the stream is exhausted before the requested bytes are found. 221 */ indexOf(ByteString bytes)222 long indexOf(ByteString bytes) throws IOException; 223 224 /** 225 * Returns the index of the first match for {@code bytes} in the buffer at or after {@code 226 * fromIndex}. This expands the buffer as necessary until {@code bytes} is found. This reads an 227 * unbounded number of bytes into the buffer. Returns -1 if the stream is exhausted before the 228 * requested bytes are found. 229 */ indexOf(ByteString bytes, long fromIndex)230 long indexOf(ByteString bytes, long fromIndex) throws IOException; 231 232 /** 233 * Returns the index of the first byte in {@code targetBytes} in the buffer. 234 * This expands the buffer as necessary until a target byte is found. This 235 * reads an unbounded number of bytes into the buffer. Returns -1 if the 236 * stream is exhausted before the requested byte is found. 237 */ indexOfElement(ByteString targetBytes)238 long indexOfElement(ByteString targetBytes) throws IOException; 239 240 /** 241 * Returns the index of the first byte in {@code targetBytes} in the buffer 242 * at or after {@code fromIndex}. This expands the buffer as necessary until 243 * a target byte is found. This reads an unbounded number of bytes into the 244 * buffer. Returns -1 if the stream is exhausted before the requested byte is 245 * found. 246 */ indexOfElement(ByteString targetBytes, long fromIndex)247 long indexOfElement(ByteString targetBytes, long fromIndex) throws IOException; 248 249 /** Returns an input stream that reads from this source. */ inputStream()250 InputStream inputStream(); 251 } 252