1 /* 2 * Copyright 2014 The gRPC Authors 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 17 package io.grpc.internal; 18 19 import java.io.Closeable; 20 import java.io.IOException; 21 import java.io.OutputStream; 22 import java.nio.ByteBuffer; 23 24 /** 25 * Interface for an abstract byte buffer. Buffers are intended to be a read-only, except for the 26 * read position which is incremented after each read call. 27 * 28 * <p>Buffers may optionally expose a backing array for optimization purposes, similar to what is 29 * done in {@link ByteBuffer}. It is not expected that callers will attempt to modify the backing 30 * array. 31 */ 32 public interface ReadableBuffer extends Closeable { 33 34 /** 35 * Gets the current number of readable bytes remaining in this buffer. 36 */ readableBytes()37 int readableBytes(); 38 39 /** 40 * Reads the next unsigned byte from this buffer and increments the read position by 1. 41 * 42 * @throws IndexOutOfBoundsException if required bytes are not readable 43 */ readUnsignedByte()44 int readUnsignedByte(); 45 46 /** 47 * Reads a 4-byte signed integer from this buffer using big-endian byte ordering. Increments the 48 * read position by 4. 49 * 50 * @throws IndexOutOfBoundsException if required bytes are not readable 51 */ readInt()52 int readInt(); 53 54 /** 55 * Increments the read position by the given length. 56 * 57 * @throws IndexOutOfBoundsException if required bytes are not readable 58 */ skipBytes(int length)59 void skipBytes(int length); 60 61 /** 62 * Reads {@code length} bytes from this buffer and writes them to the destination array. 63 * Increments the read position by {@code length}. 64 * 65 * @param dest the destination array to receive the bytes. 66 * @param destOffset the starting offset in the destination array. 67 * @param length the number of bytes to be copied. 68 * @throws IndexOutOfBoundsException if required bytes are not readable or {@code dest} is too 69 * small. 70 */ readBytes(byte[] dest, int destOffset, int length)71 void readBytes(byte[] dest, int destOffset, int length); 72 73 /** 74 * Reads from this buffer until the destination's position reaches its limit, and increases the 75 * read position by the number of the transferred bytes. 76 * 77 * @param dest the destination buffer to receive the bytes. 78 * @throws IndexOutOfBoundsException if required bytes are not readable 79 */ readBytes(ByteBuffer dest)80 void readBytes(ByteBuffer dest); 81 82 /** 83 * Reads {@code length} bytes from this buffer and writes them to the destination stream. 84 * Increments the read position by {@code length}. If the required bytes are not readable, throws 85 * {@link IndexOutOfBoundsException}. 86 * 87 * @param dest the destination stream to receive the bytes. 88 * @param length the number of bytes to be copied. 89 * @throws IOException thrown if any error was encountered while writing to the stream. 90 * @throws IndexOutOfBoundsException if required bytes are not readable 91 */ readBytes(OutputStream dest, int length)92 void readBytes(OutputStream dest, int length) throws IOException; 93 94 /** 95 * Reads {@code length} bytes from this buffer and returns a new Buffer containing them. Some 96 * implementations may return a Buffer sharing the backing memory with this buffer to prevent 97 * copying. However, that means that the returned buffer may keep the (possibly much larger) 98 * backing memory in use even after this buffer is closed. 99 * 100 * @param length the number of bytes to contain in returned Buffer. 101 * @throws IndexOutOfBoundsException if required bytes are not readable 102 */ readBytes(int length)103 ReadableBuffer readBytes(int length); 104 105 /** 106 * Indicates whether or not this buffer exposes a backing array. 107 */ hasArray()108 boolean hasArray(); 109 110 /** 111 * Gets the backing array for this buffer. This is an optional method, so callers should first 112 * check {@link #hasArray}. 113 * 114 * @throws UnsupportedOperationException the buffer does not support this method 115 */ array()116 byte[] array(); 117 118 /** 119 * Gets the offset in the backing array of the current read position. This is an optional method, 120 * so callers should first check {@link #hasArray} 121 * 122 * @throws UnsupportedOperationException the buffer does not support this method 123 */ arrayOffset()124 int arrayOffset(); 125 126 /** 127 * Closes this buffer and releases any resources. 128 */ 129 @Override close()130 void close(); 131 } 132