third-party/atomix/storage/src/main/java/io/atomix/storage/buffer/BufferInput.java

   1 /*
   2  * Copyright 2015-present Open Networking Foundation
   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 io.atomix.storage.buffer;
  17
  18 import java.nio.charset.Charset;
  19 import java.util.function.Function;
  20
  21 /**
  22  * Readable buffer.
  23  * <p>
  24  * This interface exposes methods for reading from a byte buffer. Readable buffers maintain a small amount of state
  25  * regarding current cursor positions and limits similar to the behavior of {@link java.nio.ByteBuffer}.
  26  *
  27  * @author <a href="http://github.com/kuujo">Jordan Halterman</a>
  28  */
  29 public interface BufferInput<T extends BufferInput<?>> extends AutoCloseable {
  30
  31   /**
  32    * Returns the buffer's current read/write position.
  33    * <p>
  34    * The position is an internal cursor that tracks where to write/read bytes in the underlying storage implementation.
  35    * As bytes are written to or read from the buffer, the position will advance based on the number of bytes read.
  36    *
  37    * @return The buffer's current position.
  38    */
  39   int position();
  40
  41   /**
  42    * Returns the number of bytes remaining in the input.
  43    *
  44    * @return The number of bytes remaining in the input.
  45    */
  46   int remaining();
  47
  48   /**
  49    * Returns a boolean value indicating whether the input has bytes remaining.
  50    *
  51    * @return Indicates whether bytes remain to be read from the input.
  52    */
  53   boolean hasRemaining();
  54
  55   /**
  56    * Skips the given number of bytes in the input.
  57    *
  58    * @param bytes The number of bytes to attempt to skip.
  59    * @return The skipped input.
  60    */
  61   T skip(int bytes);
  62
  63   /**
  64    * Reads bytes into the given byte array.
  65    *
  66    * @param bytes The byte array into which to read bytes.
  67    * @return The buffer.
  68    */
  69   T read(Bytes bytes);
  70
  71   /**
  72    * Reads bytes into the given byte array.
  73    *
  74    * @param bytes The byte array into which to read bytes.
  75    * @return The buffer.
  76    */
  77   T read(byte[] bytes);
  78
  79   /**
  80    * Reads bytes into the given byte array starting at the current position.
  81    *
  82    * @param bytes  The byte array into which to read bytes.
  83    * @param offset The offset at which to write bytes into the given buffer
  84    * @return The buffer.
  85    */
  86   T read(Bytes bytes, int offset, int length);
  87
  88   /**
  89    * Reads bytes into the given byte array starting at current position up to the given length.
  90    *
  91    * @param bytes  The byte array into which to read bytes.
  92    * @param offset The offset at which to write bytes into the given buffer
  93    * @return The buffer.
  94    */
  95   T read(byte[] bytes, int offset, int length);
  96
  97   /**
  98    * Reads bytes into the given buffer.
  99    *
 100    * @param buffer The buffer into which to read bytes.
 101    * @return The buffer.
 102    */
 103   T read(Buffer buffer);
 104
 105   /**
 106    * Reads an object from the buffer.
 107    *
 108    * @param decoder the object decoder
 109    * @param <U> the type of the object to read
 110    * @return the read object.
 111    */
 112   default <U> U readObject(Function<byte[], U> decoder) {
 113     byte[] bytes = readBytes(readInt());
 114     return decoder.apply(bytes);
 115   }
 116
 117   /**
 118    * Reads a byte array.
 119    *
 120    * @param length The byte array length
 121    * @return The read byte array.
 122    */
 123   default byte[] readBytes(int length) {
 124     byte[] bytes = new byte[length];
 125     read(bytes);
 126     return bytes;
 127   }
 128
 129   /**
 130    * Reads a byte from the buffer at the current position.
 131    *
 132    * @return The read byte.
 133    */
 134   int readByte();
 135
 136   /**
 137    * Reads an unsigned byte from the buffer at the current position.
 138    *
 139    * @return The read byte.
 140    */
 141   int readUnsignedByte();
 142
 143   /**
 144    * Reads a 16-bit character from the buffer at the current position.
 145    *
 146    * @return The read character.
 147    */
 148   char readChar();
 149
 150   /**
 151    * Reads a 16-bit signed integer from the buffer at the current position.
 152    *
 153    * @return The read short.
 154    */
 155   short readShort();
 156
 157   /**
 158    * Reads a 16-bit unsigned integer from the buffer at the current position.
 159    *
 160    * @return The read short.
 161    */
 162   int readUnsignedShort();
 163
 164   /**
 165    * Reads a 24-bit signed integer from the buffer at the current position.
 166    *
 167    * @return The read integer.
 168    */
 169   int readMedium();
 170
 171   /**
 172    * Reads a 24-bit unsigned integer from the buffer at the current position.
 173    *
 174    * @return The read integer.
 175    */
 176   int readUnsignedMedium();
 177
 178   /**
 179    * Reads a 32-bit signed integer from the buffer at the current position.
 180    *
 181    * @return The read integer.
 182    */
 183   int readInt();
 184
 185   /**
 186    * Reads a 32-bit unsigned integer from the buffer at the current position.
 187    *
 188    * @return The read integer.
 189    */
 190   long readUnsignedInt();
 191
 192   /**
 193    * Reads a 64-bit signed integer from the buffer at the current position.
 194    *
 195    * @return The read long.
 196    */
 197   long readLong();
 198
 199   /**
 200    * Reads a single-precision 32-bit floating point number from the buffer at the current position.
 201    *
 202    * @return The read float.
 203    */
 204   float readFloat();
 205
 206   /**
 207    * Reads a double-precision 64-bit floating point number from the buffer at the current position.
 208    *
 209    * @return The read double.
 210    */
 211   double readDouble();
 212
 213   /**
 214    * Reads a 1 byte boolean from the buffer at the current position.
 215    *
 216    * @return The read boolean.
 217    */
 218   boolean readBoolean();
 219
 220   /**
 221    * Reads a string from the buffer at the current position.
 222    *
 223    * @return The read string.
 224    */
 225   String readString();
 226
 227   /**
 228    * Reads a string from the buffer at the current position.
 229    *
 230    * @param charset The character set with which to decode the string.
 231    * @return The read string.
 232    */
 233   String readString(Charset charset);
 234
 235   /**
 236    * Reads a UTF-8 string from the buffer at the current position.
 237    *
 238    * @return The read string.
 239    */
 240   String readUTF8();
 241
 242   @Override
 243   void close();
 244
 245 }