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 */
16package okio;
17
18import java.io.IOException;
19import 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 */
26public 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