XByteBuffer (Apache Tomcat 11.0.23 API Documentation)
Description: declaration: package: org.apache.catalina.tribes.io, class: XByteBuffer

# Class XByteBuffer

java.lang.Object
org.apache.catalina.tribes.io.XByteBuffer

All Implemented Interfaces:
  `Serializable`

public class XByteBuffer extends Object implements Serializable
The XByteBuffer provides a dual functionality. One, it stores message bytes and automatically extends the byte buffer if needed.
Two, it can encode and decode packages so that they can be defined and identified as they come in on a socket.
THIS CLASS IS NOT THREAD SAFE
Transfer package:

- START_DATA- 7 bytes - FLT2002
- SIZE - 4 bytes - size of the data package
- DATA - should be as many bytes as the prev SIZE
- END_DATA - 7 bytes - TLF2003

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected byte[]`
  `buf`
  Variable to hold the data
  `protected int`
  `bufSize`
  Current length of data in the buffer
  `protected boolean`
  `discard`
  Flag for discarding invalid packages If this flag is set to true, and append(byte[],...) is called, the data added will be inspected, and if it doesn't start with `START_DATA` it will be thrown away.
  `protected static final StringManager`
  `sm`
  String manager for this class.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `XByteBuffer(byte[] data, boolean discard)`
  Constructs a new XByteBuffer from the given data.
  `XByteBuffer(byte[] data, int size, boolean discard)`
  Constructs a new XByteBuffer from the given data with a specific buffer size.
  `XByteBuffer(int size, boolean discard)`
  Constructs a new XByteBuffer.
  TODO use a pool of byte[] for performance

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `append(boolean i)`
  Appends a boolean value to the buffer.
  `boolean`
  `append(byte i)`
  Appends a single byte to the buffer.
  `boolean`
  `append(byte[] b, int off, int len)`
  Appends a portion of a byte array to the buffer.
  `boolean`
  `append(int i)`
  Appends an integer value to the buffer.
  `boolean`
  `append(long i)`
  Appends a long value to the buffer.
  `boolean`
  `append(ByteBuffer b, int len)`
  Appends the data to the buffer.
  `void`
  `clear()`
  Resets the buffer
  `int`
  `countPackages()`
  Internal mechanism to make a check if a complete package exists within the buffer
  `int`
  `countPackages(boolean first)`
  Counts the number of complete packages in the buffer.
  `static byte[]`
  `createDataPackage(byte[] data)`
  Creates a complete data package from the given data.
  `static byte[]`
  `createDataPackage(byte[] data, int doff, int dlength, byte[] buffer, int bufoff)`
  Creates a complete data package with header, size, data, and footer, writing to a provided buffer.
  `static byte[]`
  `createDataPackage(ChannelData cdata)`
  Creates a complete data package
  `static Serializable`
  `deserialize(byte[] data)`
  Deserializes a Serializable object from the given byte array.
  `static Serializable`
  `deserialize(byte[] data, int offset, int length)`
  Deserializes a Serializable object from a portion of the given byte array.
  `static Serializable`
  `deserialize(byte[] data, int offset, int length, ClassLoader[] cls)`
  Deserializes a Serializable object from a portion of the given byte array using the specified class loaders.
  `boolean`
  `doesPackageExist()`
  Method to check if a package exists in this byte buffer.
  `void`
  `expand(int newcount)`
  Expands the internal buffer to accommodate the specified number of bytes.
  `XByteBuffer`
  `extractDataPackage(boolean clearFromBuffer)`
  Extracts the message bytes from a package.
  `ChannelData`
  `extractPackage(boolean clearFromBuffer)`
  Extracts a complete package from the buffer and deserializes it into a ChannelData object.
  `static int`
  `firstIndexOf(byte[] src, int srcOff, byte[] find)`
  Similar to a String.IndexOf, but uses pure bytes.
  `byte[]`
  `getBytes()`
  Returns the bytes in the buffer, in its exact length.
  `byte[]`
  `getBytesDirect()`
  Returns the internal byte array directly, without copying.
  `int`
  `getCapacity()`
  Returns the current capacity of the internal buffer.
  `static int`
  `getDataPackageLength(int datalength)`
  Calculates the total length of a data package including header, size indicator, data, and footer.
  `boolean`
  `getDiscard()`
  Returns the discard flag for invalid packages.
  `int`
  `getLength()`
  Returns the current length of the data in the buffer.
  `void`
  `reset()`
  Resets the buffer length to zero.
  `static byte[]`
  `serialize(Serializable msg)`
  Serializes a message into cluster data
  `void`
  `setDiscard(boolean discard)`
  Sets the discard flag for invalid packages.
  `void`
  `setLength(int size)`
  Sets the current length of the data in the buffer.
  `static boolean`
  `toBoolean(byte[] b, int offset)`
  Converts a byte array entry to boolean.
  `static byte[]`
  `toBytes(boolean bool, byte[] data, int offset)`
  Converts a boolean and put it in a byte array.
  `static byte[]`
  `toBytes(int n, byte[] b, int offset)`
  Converts an integer to four bytes.
  `static byte[]`
  `toBytes(long n, byte[] b, int offset)`
  Converts a long to eight bytes.
  `static int`
  `toInt(byte[] b, int off)`
  Convert four bytes to an int
  `static long`
  `toLong(byte[] b, int off)`
  Convert eight bytes to a long
  `void`
  `trim(int length)`
  Trims the specified number of bytes from the end of the buffer.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### sm

    protected static final StringManager sm
    String manager for this class.

  - ### buf

    protected byte[] buf
    Variable to hold the data

  - ### bufSize

    protected int bufSize
    Current length of data in the buffer

  - ### discard

    protected boolean discard
    Flag for discarding invalid packages If this flag is set to true, and append(byte[],...) is called, the data added will be inspected, and if it doesn't start with `START_DATA` it will be thrown away.

- ## Constructor Details

  - ### XByteBuffer

    public XByteBuffer(int size, boolean discard)
    Constructs a new XByteBuffer.
    TODO use a pool of byte[] for performance
    Parameters:
      `size` - the initial size of the byte buffer
      `discard` - Flag for discarding invalid packages

  - ### XByteBuffer

    public XByteBuffer(byte[] data, boolean discard)
    Constructs a new XByteBuffer from the given data.
    Parameters:
      `data` - the initial data
      `discard` - Flag for discarding invalid packages

  - ### XByteBuffer

    public XByteBuffer(byte[] data, int size, boolean discard)
    Constructs a new XByteBuffer from the given data with a specific buffer size.
    Parameters:
      `data` - the initial data
      `size` - the initial size of the byte buffer
      `discard` - Flag for discarding invalid packages

- ## Method Details

  - ### getLength

    public int getLength()
    Returns the current length of the data in the buffer.
    Returns:
      the current length

  - ### setLength

    public void setLength(int size)
    Sets the current length of the data in the buffer.
    Parameters:
      `size` - the new length

  - ### trim

    public void trim(int length)
    Trims the specified number of bytes from the end of the buffer.
    Parameters:
      `length` - the number of bytes to trim

  - ### reset

    public void reset()
    Resets the buffer length to zero.

  - ### getBytesDirect

    public byte[] getBytesDirect()
    Returns the internal byte array directly, without copying.
    Returns:
      the internal byte array

  - ### getBytes

    public byte[] getBytes()
    Returns the bytes in the buffer, in its exact length.
    Returns:
      The bytes in the buffer

  - ### clear

    public void clear()
    Resets the buffer

  - ### append

    public boolean append(ByteBuffer b, int len)
    Appends the data to the buffer. If the data is incorrectly formatted, ie, the data should always start with the header, false will be returned and the data will be discarded.
    Parameters:
      `b` - - bytes to be appended
      `len` - - the number of bytes to append.
    Returns:
      true if the data was appended correctly. Returns false if the package is incorrect, ie missing header or something, or the length of data is 0

  - ### append

    public boolean append(byte i)
    Appends a single byte to the buffer.
    Parameters:
      `i` - the byte to append
    Returns:
      always returns true

  - ### append

    public boolean append(boolean i)
    Appends a boolean value to the buffer.
    Parameters:
      `i` - the boolean to append
    Returns:
      always returns true

  - ### append

    public boolean append(long i)
    Appends a long value to the buffer.
    Parameters:
      `i` - the long to append
    Returns:
      always returns true

  - ### append

    public boolean append(int i)
    Appends an integer value to the buffer.
    Parameters:
      `i` - the integer to append
    Returns:
      always returns true

  - ### append

    public boolean append(byte[] b, int off, int len)
    Appends a portion of a byte array to the buffer.
    Parameters:
      `b` - the byte array
      `off` - the offset in the byte array
      `len` - the number of bytes to append
    Returns:
      true if data was appended, false if length is zero

  - ### expand

    public void expand(int newcount)
    Expands the internal buffer to accommodate the specified number of bytes.
    Parameters:
      `newcount` - the new minimum capacity required

  - ### getCapacity

    public int getCapacity()
    Returns the current capacity of the internal buffer.
    Returns:
      the buffer capacity

  - ### countPackages

    public int countPackages()
    Internal mechanism to make a check if a complete package exists within the buffer
    Returns:
      - true if a complete package (header,compress,size,data,footer) exists within the buffer

  - ### countPackages

    public int countPackages(boolean first)
    Counts the number of complete packages in the buffer.
    Parameters:
      `first` - if true, only check for the first package
    Returns:
      the number of complete packages found

  - ### doesPackageExist

    public boolean doesPackageExist()
    Method to check if a package exists in this byte buffer.
    Returns:
      - true if a complete package (header,options,size,data,footer) exists within the buffer

  - ### extractDataPackage

    public XByteBuffer extractDataPackage(boolean clearFromBuffer)
    Extracts the message bytes from a package. If no package exists, a IllegalStateException will be thrown.
    Parameters:
      `clearFromBuffer` - - if true, the package will be removed from the byte buffer
    Returns:
      - returns the actual message bytes (header, compress,size and footer not included).

  - ### extractPackage

    public ChannelData extractPackage(boolean clearFromBuffer)
    Extracts a complete package from the buffer and deserializes it into a ChannelData object.
    Parameters:
      `clearFromBuffer` - if true, the extracted package will be removed from the buffer
    Returns:
      the deserialized ChannelData object

  - ### createDataPackage

    public static byte[] createDataPackage(ChannelData cdata)
    Creates a complete data package
    Parameters:
      `cdata` - - the message data to be contained within the package
    Returns:
      - a full package (header,size,data,footer)

  - ### createDataPackage

    public static byte[] createDataPackage(byte[] data, int doff, int dlength, byte[] buffer, int bufoff)
    Creates a complete data package with header, size, data, and footer, writing to a provided buffer.
    Parameters:
      `data` - the data to package
      `doff` - the offset in the data array
      `dlength` - the length of the data
      `buffer` - the output buffer
      `bufoff` - the offset in the output buffer
    Returns:
      the output buffer

  - ### getDataPackageLength

    public static int getDataPackageLength(int datalength)
    Calculates the total length of a data package including header, size indicator, data, and footer.
    Parameters:
      `datalength` - the length of the data portion
    Returns:
      the total package length

  - ### createDataPackage

    public static byte[] createDataPackage(byte[] data)
    Creates a complete data package from the given data.
    Parameters:
      `data` - the data to package
    Returns:
      a full package (header, size, data, footer)

  - ### toInt

    public static int toInt(byte[] b, int off)
    Convert four bytes to an int
    Parameters:
      `b` - - the byte array containing the four bytes
      `off` - - the offset
    Returns:
      the integer value constructed from the four bytes

  - ### toLong

    public static long toLong(byte[] b, int off)
    Convert eight bytes to a long
    Parameters:
      `b` - - the byte array containing the four bytes
      `off` - - the offset
    Returns:
      the long value constructed from the eight bytes

  - ### toBytes

    public static byte[] toBytes(boolean bool, byte[] data, int offset)
    Converts a boolean and put it in a byte array.
    Parameters:
      `bool` - the integer
      `data` - the byte buffer in which the boolean will be placed
      `offset` - the offset in the byte array
    Returns:
      the byte array

  - ### toBoolean

    public static boolean toBoolean(byte[] b, int offset)
    Converts a byte array entry to boolean.
    Parameters:
      `b` - byte array
      `offset` - within byte array
    Returns:
      true if byte array entry is non-zero, false otherwise

  - ### toBytes

    public static byte[] toBytes(int n, byte[] b, int offset)
    Converts an integer to four bytes.
    Parameters:
      `n` - the integer
      `b` - the byte buffer in which the integer will be placed
      `offset` - the offset in the byte array
    Returns:
      four bytes in an array

  - ### toBytes

    public static byte[] toBytes(long n, byte[] b, int offset)
    Converts a long to eight bytes.
    Parameters:
      `n` - the long
      `b` - the byte buffer in which the integer will be placed
      `offset` - the offset in the byte array
    Returns:
      eight bytes in an array

  - ### firstIndexOf

    public static int firstIndexOf(byte[] src, int srcOff, byte[] find)
    Similar to a String.IndexOf, but uses pure bytes.
    Parameters:
      `src` - - the source bytes to be searched
      `srcOff` - - offset on the source buffer
      `find` - - the string to be found within src
    Returns:
      - the index of the first matching byte. -1 if the find array is not found

  - ### deserialize

    public static Serializable deserialize(byte[] data) throws IOException, ClassNotFoundException, ClassCastException
    Deserializes a Serializable object from the given byte array.
    Parameters:
      `data` - the byte array containing the serialized object
    Returns:
      the deserialized object
    Throws:
      `IOException` - if an I/O error occurs
      `ClassNotFoundException` - if the class of the serialized object cannot be found
      `ClassCastException` - if the deserialized object is not Serializable

  - ### deserialize

    public static Serializable deserialize(byte[] data, int offset, int length) throws IOException, ClassNotFoundException, ClassCastException
    Deserializes a Serializable object from a portion of the given byte array.
    Parameters:
      `data` - the byte array containing the serialized object
      `offset` - the offset in the byte array
      `length` - the length of the data to deserialize
    Returns:
      the deserialized object
    Throws:
      `IOException` - if an I/O error occurs
      `ClassNotFoundException` - if the class of the serialized object cannot be found
      `ClassCastException` - if the deserialized object is not Serializable

  - ### deserialize

    public static Serializable deserialize(byte[] data, int offset, int length, ClassLoader[] cls) throws IOException, ClassNotFoundException, ClassCastException
    Deserializes a Serializable object from a portion of the given byte array using the specified class loaders.
    Parameters:
      `data` - the byte array containing the serialized object
      `offset` - the offset in the byte array
      `length` - the length of the data to deserialize
      `cls` - the class loaders to use for deserialization
    Returns:
      the deserialized object
    Throws:
      `IOException` - if an I/O error occurs
      `ClassNotFoundException` - if the class of the serialized object cannot be found
      `ClassCastException` - if the deserialized object is not Serializable

  - ### serialize

    public static byte[] serialize(Serializable msg) throws IOException
    Serializes a message into cluster data
    Parameters:
      `msg` - ClusterMessage
    Returns:
      serialized content as byte[] array
    Throws:
      `IOException` - Serialization error

  - ### setDiscard

    public void setDiscard(boolean discard)
    Sets the discard flag for invalid packages.
    Parameters:
      `discard` - the new discard flag value

  - ### getDiscard

    public boolean getDiscard()
    Returns the discard flag for invalid packages.
    Returns:
      the discard flag value