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.IOException; 193c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerimport java.io.OutputStream; 20e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fullerimport java.nio.charset.Charset; 213c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 223c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller/** 233c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * A sink that keeps a buffer internally so that callers can do small writes 243c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller * without a performance penalty. 253c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 263c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fullerpublic interface BufferedSink extends Sink { 273c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** Returns this sink's internal buffer. */ 28e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller Buffer buffer(); 293c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 303c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller BufferedSink write(ByteString byteString) throws IOException; 313c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 323c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** 33e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * Like {@link OutputStream#write(byte[])}, this writes a complete byte array to 34e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * this sink. 353c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 363c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller BufferedSink write(byte[] source) throws IOException; 373c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 383c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** 39e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * Like {@link OutputStream#write(byte[], int, int)}, this writes {@code byteCount} 40e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * bytes of {@code source}, starting at {@code offset}. 413c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller */ 423c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller BufferedSink write(byte[] source, int offset, int byteCount) throws IOException; 433c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 44e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller /** 45e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * Removes all bytes from {@code source} and appends them to this sink. Returns the 46e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * number of bytes read which will be 0 if {@code source} is exhausted. 47e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller */ 48e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller long writeAll(Source source) throws IOException; 49e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 50e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller /** Removes {@code byteCount} bytes from {@code source} and appends them to this sink. */ 51e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller BufferedSink write(Source source, long byteCount) throws IOException; 52e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 533c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** Encodes {@code string} in UTF-8 and writes it to this sink. */ 543c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller BufferedSink writeUtf8(String string) throws IOException; 553c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 56a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller /** 57a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller * Encodes the characters at {@code beginIndex} up to {@code endIndex} from {@code string} in 58a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller * UTF-8 and writes it to this sink. 59a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller */ 60a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller BufferedSink writeUtf8(String string, int beginIndex, int endIndex) throws IOException; 61a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller 62781c9c216deed11c44044d23841a4ba6a012106eNeil Fuller /** Encodes {@code codePoint} in UTF-8 and writes it to this sink. */ 63781c9c216deed11c44044d23841a4ba6a012106eNeil Fuller BufferedSink writeUtf8CodePoint(int codePoint) throws IOException; 64781c9c216deed11c44044d23841a4ba6a012106eNeil Fuller 65e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller /** Encodes {@code string} in {@code charset} and writes it to this sink. */ 66e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller BufferedSink writeString(String string, Charset charset) throws IOException; 67e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 68a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller /** 69a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller * Encodes the characters at {@code beginIndex} up to {@code endIndex} from {@code string} in 70a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller * {@code charset} and writes it to this sink. 71a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller */ 72a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller BufferedSink writeString(String string, int beginIndex, int endIndex, Charset charset) 73a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller throws IOException; 74a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller 75c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller /** Writes a byte to this sink. */ 763c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller BufferedSink writeByte(int b) throws IOException; 773c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 78c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller /** Writes a big-endian short to this sink using two bytes. */ 793c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller BufferedSink writeShort(int s) throws IOException; 803c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 81c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller /** Writes a little-endian short to this sink using two bytes. */ 82c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller BufferedSink writeShortLe(int s) throws IOException; 83c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller 84c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller /** Writes a big-endian int to this sink using four bytes. */ 853c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller BufferedSink writeInt(int i) throws IOException; 863c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 87c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller /** Writes a little-endian int to this sink using four bytes. */ 88c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller BufferedSink writeIntLe(int i) throws IOException; 89c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller 90c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller /** Writes a big-endian long to this sink using eight bytes. */ 91c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller BufferedSink writeLong(long v) throws IOException; 92c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller 93c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller /** Writes a little-endian long to this sink using eight bytes. */ 94c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller BufferedSink writeLongLe(long v) throws IOException; 95c6bd683320121544811f481709b3fdbcbe9b3866Neil Fuller 96a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller /** Writes a long to this sink in signed decimal form (i.e., as a string in base 10). */ 97a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller BufferedSink writeDecimalLong(long v) throws IOException; 98a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller 99a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller /** Writes a long to this sink in hexadecimal form (i.e., as a string in base 16). */ 100a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller BufferedSink writeHexadecimalUnsignedLong(long v) throws IOException; 101a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fuller 102e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller /** 103e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * Writes complete segments to the underlying sink, if one exists. Like {@link #flush}, but 104e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * weaker. Use this to limit the memory held in the buffer to a single segment. 105e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller */ 1063c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller BufferedSink emitCompleteSegments() throws IOException; 1073c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller 108e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller /** 109e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * Writes all buffered data to the underlying sink, if one exists. Like {@link #flush}, but 110e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * weaker. Call this before this buffered sink goes out of scope so that its data can reach its 111e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * destination. 112e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller */ 113e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller BufferedSink emit() throws IOException; 114e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 1153c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller /** Returns an output stream that writes to this sink. */ 1163c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller OutputStream outputStream(); 1173c938a3f6b61ce5e2dba0d039b03fe73b89fd26cNeil Fuller} 118