Class FriendlyByteBuffer

java.lang.Object
dev.jorel.commandapi.network.FriendlyByteBuffer
public class FriendlyByteBuffer extends Object
A sequence of bytes that can be written to and read from.

Reading and writing is handled by two ints, the readIndex and writeIndex, which can be accessed using getReadIndex() and getWriteIndex() respectively. These indices are automatically incremented when reading and writing bytes. If the readIndex is ever greater than or equal to the writeIndex when a byte is read, an IllegalStateException will be thrown for attempting to read out of bounds.

This class provides methods that make it easier to read and write certain data types, using methods like readVarInt() and writeVarInt(int). These methods handle formatting the bytes correctly, letting developers simply worry about the structure of their data. If a specific method has a problem while reading bytes, an appropriate IllegalStateException will be thrown to indicate something is misformatted.

This buffer can be created empty (FriendlyByteBuffer()), or pre-written with a byte array (FriendlyByteBuffer(byte[])).

  • Constructor Details

    • FriendlyByteBuffer

      public FriendlyByteBuffer()
      Creates a new FriendlyByteBuffer with no bytes, ready to be written to.

    • FriendlyByteBuffer

      public FriendlyByteBuffer(byte[] bytes)
      Creates a new FriendlyByteBuffer with the given bytes already written, ready to be read from.
      Parameters:
      bytes - The initial bytes to put in this buffer. This array is written to the buffer using writeBytes(byte...).

  • Method Details

    • checkReadIndexIsInBounds

      public void checkReadIndexIsInBounds() throws IllegalStateException
      Checks if the current readIndex for this buffer is out of bounds.
      Throws:
      IllegalStateException - If isReadIndexOutOfBounds() returns true.

    • checkReadIndexIsInBounds

      public void checkReadIndexIsInBounds(int readIndex) throws IllegalStateException
      Checks if the given readIndex is out of bounds.
      Parameters:
      readIndex - The index to check.
      Throws:
      IllegalStateException - If isReadIndexOutOfBounds(int) returns true for the given readIndex.

    • isReadIndexOutOfBounds

      public boolean isReadIndexOutOfBounds()
      Evaluates if the current readIndex for this buffer is out of bounds.
      Returns:
      True if this.readIndex < 0 || this.readIndex >= this.writeIndex, and false otherwise.

    • isReadIndexOutOfBounds

      public boolean isReadIndexOutOfBounds(int readIndex)
      Evaluates if the given readIndex is out of bounds.
      Parameters:
      readIndex - The index to check.
      Returns:
      True if readIndex < 0 || readIndex >= this.writeIndex, and false otherwise.

    • checkWriteIndexIsInBounds

      public void checkWriteIndexIsInBounds() throws IllegalStateException
      Checks if the current writeIndex for this buffer is out of bounds.
      Throws:
      IllegalStateException - If isWriteIndexOutOfBounds() returns true.

    • checkWriteIndexIsInBounds

      public void checkWriteIndexIsInBounds(int writeIndex) throws IllegalStateException
      Checks if the given writeIndex is out of bounds.
      Parameters:
      writeIndex - The index to check.
      Throws:
      IllegalStateException - If isWriteIndexOutOfBounds(int) returns true for the given writeIndex.

    • isWriteIndexOutOfBounds

      public boolean isWriteIndexOutOfBounds()
      Evaluates if the current writeIndex for this buffer is out of bounds.
      Returns:
      True if this.writeIndex < 0, and false otherwise.

    • isWriteIndexOutOfBounds

      public boolean isWriteIndexOutOfBounds(int writeIndex)
      Evaluates if the given writeIndex is out of bounds.
      Parameters:
      writeIndex - The index to check.
      Returns:
      True if writeIndex < 0, and false otherwise.

    • getReadIndex

      public int getReadIndex()
      Returns:
      The current readIndex for this buffer.

    • setReadIndex

      public void setReadIndex(int index) throws IllegalStateException
      Sets the readIndex for this buffer.

      This method checks the given index using isReadIndexOutOfBounds(int) to make sure it is not out of bounds before setting the index of this buffer.

      Parameters:
      index - The new readIndex.
      Throws:
      IllegalStateException - If the given index is out of bounds.

    • getWriteIndex

      public int getWriteIndex()
      Returns:
      The current writeIndex for this buffer.

    • setWriteIndex

      public void setWriteIndex(int index) throws IllegalStateException
      Sets the writeIndex for this buffer.

      This method checks the given index using isWriteIndexOutOfBounds(int) to make sure it is not out of bounds before setting the index of this buffer.

      Parameters:
      index - The new writeIndex.
      Throws:
      IllegalStateException - If the given index is out of bounds.

    • resetIndices

      public void resetIndices()
      Sets the readIndex and writeIndex to 0. This effectively clears this buffer, since future writes will overwrite the old bytes. The bytes are not actually forgotten, since if the write index is jumped forward, the bytes can still be read.

    • toByteArray

      public byte[] toByteArray() throws IllegalStateException
      Returns:
      An array containing all the bytes written to this buffer.
      Throws:
      IllegalStateException - If the current writeIndex is out of bounds according to checkWriteIndexIsInBounds().

    • getRemainingBytes

      public byte[] getRemainingBytes() throws IllegalStateException
      Returns:
      An array containing all the bytes left to be read from this buffer.
      Throws:
      IllegalStateException - If the current writeIndex is out of bounds according to checkWriteIndexIsInBounds(), or if the current readIndex is out of bounds according to checkReadIndexIsInBounds().

    • countTotalBytes

      public int countTotalBytes()
      Returns:
      The number of bytes currently written to this buffer.

    • countReadableBytes

      public int countReadableBytes()
      Returns:
      The number of bytes left to read fom this buffer.

    • writeByte

      public void writeByte(byte b) throws IllegalStateException
      Writes a single byte (8 bits) into this buffer.
      Parameters:
      b - The byte to write.
      Throws:
      IllegalStateException - If the writeIndex is out of bounds according to checkWriteIndexIsInBounds().

    • writeByte

      public void writeByte(int i) throws IllegalStateException
      Writes a single byte (8 bits) into this buffer using writeByte(byte).
      Parameters:
      i - The byte to write, given as a 32-bit integer. Only the 8 least significant bits are written.
      Throws:
      IllegalStateException - If the write index goes out of bounds while writing the byte.

    • readByte

      public byte readByte() throws IllegalStateException
      Reads a single byte (8 bits) from this buffer.
      Returns:
      The next byte in this buffer.
      Throws:
      IllegalStateException - If the readIndex is out of bounds according to checkReadIndexIsInBounds().

    • writeBytes

      public void writeBytes(byte... bytes) throws IllegalStateException
      Writes multiple bytes to this buffer. This happens one at a time using writeByte(byte).
      Parameters:
      bytes - An array of bytes to write.
      Throws:
      IllegalStateException - If the write index goes out of bounds while writing bytes.

    • readBytes

      public byte[] readBytes(int n) throws IllegalStateException
      Reads n bytes from this buffer. This happens one at a time using readByte().
      Parameters:
      n - The number of bytes to read.
      Returns:
      An array of the next n bytes in this buffer.
      Throws:
      IllegalStateException - If the read index goes out of bounds while reading bytes.

    • writeInt

      public void writeInt(int i) throws IllegalStateException
      Writes a 32 bit int to this buffer. This method writes the int as 4 bytes, starting with the 8 most significant bits.
      Parameters:
      i - The int to write.
      Throws:
      IllegalStateException - If the write index goes out of bounds while writing bytes.

    • readInt

      public int readInt() throws IllegalStateException
      Reads a 32 bit int from this buffer. This method assumes the int was written by writeInt(int).
      Returns:
      The int read from this buffer.
      Throws:
      IllegalStateException - If the read index goes out of bounds while reading bytes.

    • writeVarInt

      public void writeVarInt(int value) throws IllegalStateException
      Writes a 32 bit int to this buffer using between 1 and 5 bytes, with small positive numbers using fewer bytes. For the details of this encoding, see VarInt and VarLong.
      Parameters:
      value - The int to write.
      Throws:
      IllegalStateException - If the write index goes out of bounds while writing bytes.

    • readVarInt

      public int readVarInt() throws IllegalStateException
      Reads a 32 bit int from this buffer, encoded as a VarInt. This method assumes the VarInt was written by writeVarInt(int).
      Returns:
      The int read from this buffer.
      Throws:
      IllegalStateException - If the read index goes out of bounds while reading bytes or if the VarInt is improperly formatted.

    • writeString

      public void writeString(String string, int maxLength)
      Writes a String to this buffer. The String is encoded as an array of bytes using the UTF-8 encoding. For the details of this encoding, see UTF-8 - Wikipedia
      Parameters:
      string - The String to write.
      maxLength - The length of the longest String that is allowed.
      Throws:
      IllegalStateException - If the given String is longer than the given maximum length.

    • readString

      public String readString(int maxLength) throws IllegalStateException
      Reads a String from this buffer. This method assumes the String was written by writeString(String, int).
      Parameters:
      maxLength - The length of the longest String that is allowed.
      Returns:
      The String read from this buffer.
      Throws:
      IllegalStateException - If the read String is longer than the given maximum length.