Package dev.jorel.commandapi.network

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 Summary

Constructors

Constructor	Description
FriendlyByteBuffer()	Creates a new FriendlyByteBuffer with no bytes, ready to be written to.
FriendlyByteBuffer(byte[] bytes)	Creates a new FriendlyByteBuffer with the given bytes already written, ready to be read from.

Method Summary

Modifier and Type	Method	Description
void	checkReadIndexIsInBounds()	Checks if the current readIndex for this buffer is out of bounds.
void	checkReadIndexIsInBounds(int readIndex)	Checks if the given readIndex is out of bounds.
void	checkWriteIndexIsInBounds()	Checks if the current writeIndex for this buffer is out of bounds.
void	checkWriteIndexIsInBounds(int writeIndex)	Checks if the given writeIndex is out of bounds.
int	countReadableBytes()
int	countTotalBytes()
int	getReadIndex()
byte[]	getRemainingBytes()
int	getWriteIndex()
boolean	isReadIndexOutOfBounds()	Evaluates if the current readIndex for this buffer is out of bounds.
boolean	isReadIndexOutOfBounds(int readIndex)	Evaluates if the given readIndex is out of bounds.
boolean	isWriteIndexOutOfBounds()	Evaluates if the current writeIndex for this buffer is out of bounds.
boolean	isWriteIndexOutOfBounds(int writeIndex)	Evaluates if the given writeIndex is out of bounds.
byte	readByte()	Reads a single byte (8 bits) from this buffer.
byte[]	readBytes(int n)	Reads n bytes from this buffer.
int	readInt()	Reads a 32 bit int from this buffer.
String	readString()	Reads a String from this buffer.
int	readVarInt()	Reads a 32 bit int from this buffer, encoded as a VarInt.
void	resetIndices()	Sets the readIndex and writeIndex to 0.
void	setReadIndex(int index)	Sets the readIndex for this buffer.
void	setWriteIndex(int index)	Sets the writeIndex for this buffer.
byte[]	toByteArray()
void	writeByte(byte b)	Writes a single byte (8 bits) into this buffer.
void	writeByte(int i)	Writes a single byte (8 bits) into this buffer using writeByte(byte).
void	writeBytes(byte... bytes)	Writes multiple bytes to this buffer.
void	writeInt(int i)	Writes a 32 bit int to this buffer.
void	writeString(String string)	Writes a String to this buffer.
void	writeVarInt(int value)	Writes a 32 bit int to this buffer using between 1 and 5 bytes, with small positive numbers using fewer bytes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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)

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.

readString

public String readString()
                  throws IllegalStateException

Reads a String from this buffer. This method assumes the String was written by writeString(String).

Returns:

The String read from this buffer.

Throws:

IllegalStateException - If the read index goes out of bounds while reading bytes.