Class Util

java.lang.Object
zeroecho.core.io.Util
public final class Util extends Object
Utility class for performing efficient I/O operations with support for packed integers. This class provides static methods to write and read data with a compact variable-length encoding ("Pack7") and custom handling of UUIDs and UTF-8 strings.

Design rationale: Using static methods allows developers to perform encoding and decoding operations directly on existing InputStream and OutputStream instances without the need for additional stream wrappers such as FilterInputStream or FilterOutputStream. This approach eliminates extra object creation and method call overhead, potentially improving performance, especially in high-throughput scenarios.

Usage: These methods can be used independently with any I/O stream to achieve custom serialization formats, such as length-prefixed UTF-8 strings, packed integers, or custom binary structures.

  • Method Summary

    Modifier and Type
    Method
    Description
    static byte[]
    read(InputStream in, int maxLength)
    Reads a byte array from the input stream.
    static long
    readLong(InputStream in)
    Reads a long value from the input stream in big-endian order (8 bytes).
    static int
    readPack7I(InputStream in)
    Reads an integer from the input stream using packed 7-bit encoding (variable length).
    static long
    readPack7L(InputStream in)
    Reads a long value from the input stream using packed 7-bit encoding (variable length).
    static String
    readUTF8(InputStream in, int maxLength)
    Reads a UTF-8 encoded string from the input stream.
    static UUID
    readUUID(InputStream in)
    Reads a UUID from the input stream, composed of two big-endian long values.
    static byte[]
    readWithPackedLengthPrefix(InputStream in, int maxSize)
    Reads up to maxSize bytes from the given InputStream, encodes the total number of bytes using 7-bit variable-length encoding (similar to writePack7L(OutputStream, long)), and returns a single byte array containing the encoded length prefix followed by the actual data read.
    static void
    write(OutputStream out, byte[] buf)
    Writes a byte array to the output stream with its length encoded as a packed 7-bit integer.
    static void
    write(OutputStream out, UUID uuid)
    Writes a UUID to the output stream as two big-endian long values.
    static void
    writeLong(OutputStream out, long val)
    Writes a long value to the output stream in big-endian order (8 bytes).
    static void
    writePack7I(OutputStream out, int val)
    Writes an integer to the output stream using packed 7-bit encoding (variable length).
    static void
    writePack7L(OutputStream out, long val)
    Writes a long value to the output stream using packed 7-bit encoding (variable length).
    static void
    writeUTF8(OutputStream out, String str)
    Writes a UTF-8 encoded string to the output stream with its length as a packed 7-bit integer.

    Methods inherited from class Object

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

  • Method Details

    • write

      public static void write(OutputStream out, byte[] buf) throws IOException
      Writes a byte array to the output stream with its length encoded as a packed 7-bit integer.
      Parameters:
      out - the output stream
      buf - the byte array to write
      Throws:
      IOException - if an I/O error occurs

    • write

      public static void write(OutputStream out, UUID uuid) throws IOException
      Writes a UUID to the output stream as two big-endian long values.
      Parameters:
      out - the output stream
      uuid - the UUID to write
      Throws:
      IOException - if an I/O error occurs

    • writeUTF8

      public static void writeUTF8(OutputStream out, String str) throws IOException
      Writes a UTF-8 encoded string to the output stream with its length as a packed 7-bit integer.
      Parameters:
      out - the output stream
      str - the string to write
      Throws:
      IOException - if an I/O error occurs

    • writeLong

      public static void writeLong(OutputStream out, long val) throws IOException
      Writes a long value to the output stream in big-endian order (8 bytes).
      Parameters:
      out - the output stream
      val - the long value to write
      Throws:
      IOException - if an I/O error occurs

    • readUUID

      public static UUID readUUID(InputStream in) throws IOException
      Reads a UUID from the input stream, composed of two big-endian long values.
      Parameters:
      in - the input stream
      Returns:
      the UUID read from the stream
      Throws:
      IOException - if an I/O error occurs or if the stream ends prematurely

    • readUTF8

      public static String readUTF8(InputStream in, int maxLength) throws IOException
      Reads a UTF-8 encoded string from the input stream. The string is prefixed with a packed 7-bit integer indicating its length. To prevent excessive allocation, the maximum allowable length must be specified.
      Parameters:
      in - the input stream
      maxLength - the maximum allowable length of the string in bytes
      Returns:
      the string read from the stream
      Throws:
      IOException - if an I/O error occurs, the length exceeds maxLength, or if the stream ends prematurely

    • readLong

      public static long readLong(InputStream in) throws IOException
      Reads a long value from the input stream in big-endian order (8 bytes).
      Parameters:
      in - the input stream
      Returns:
      the long value read
      Throws:
      IOException - if an I/O error occurs or if the stream ends prematurely

    • writePack7I

      public static void writePack7I(OutputStream out, int val) throws IOException
      Writes an integer to the output stream using packed 7-bit encoding (variable length).
      Parameters:
      out - the output stream
      val - the integer value to write
      Throws:
      IOException - if an I/O error occurs

    • writePack7L

      public static void writePack7L(OutputStream out, long val) throws IOException
      Writes a long value to the output stream using packed 7-bit encoding (variable length).
      Parameters:
      out - the output stream
      val - the long value to write
      Throws:
      IOException - if an I/O error occurs

    • read

      public static byte[] read(InputStream in, int maxLength) throws IOException
      Reads a byte array from the input stream. The length of the array is specified as a packed 7-bit integer prefix. To prevent excessive allocation, the maximum allowable length must be specified.
      Parameters:
      in - the input stream
      maxLength - the maximum allowable length of the byte array
      Returns:
      the byte array read
      Throws:
      IOException - if an I/O error occurs, the length exceeds maxLength, or if the stream ends prematurely

    • readPack7I

      public static int readPack7I(InputStream in) throws IOException
      Reads an integer from the input stream using packed 7-bit encoding (variable length).
      Parameters:
      in - the input stream
      Returns:
      the integer value read
      Throws:
      IOException - if an I/O error occurs or if the stream ends prematurely

    • readPack7L

      public static long readPack7L(InputStream in) throws IOException
      Reads a long value from the input stream using packed 7-bit encoding (variable length). Payload groups are stored most-significant first, and the high bit marks the final byte. At most ten bytes are accepted. In a ten-byte representation, the first payload group is limited to one bit so that the encoded value fits exactly in the 64-bit long bit pattern.

      Both non-negative and negative long values produced by writePack7L(OutputStream, long) are supported. The method consumes exactly one complete packed value and performs at most ten stream reads.

      Parameters:
      in - the input stream
      Returns:
      the long value read
      Throws:
      EOFException - if the stream ends before a terminating byte
      IOException - if an I/O error occurs, the encoding exceeds ten bytes, or the payload exceeds 64 bits

    • readWithPackedLengthPrefix

      public static byte[] readWithPackedLengthPrefix(InputStream in, int maxSize) throws IOException
      Reads up to maxSize bytes from the given InputStream, encodes the total number of bytes using 7-bit variable-length encoding (similar to writePack7L(OutputStream, long)), and returns a single byte array containing the encoded length prefix followed by the actual data read.

      Input is retained in chunks until the full size is known, then copied into one result array. For n input bytes, time and auxiliary memory are O(n); the retained chunks coexist with the result during the final copy. The size limit bounds accepted input, not peak allocation to a single buffer.

      The size prefix uses a packed 7-bit encoding, where the most significant bit of the last byte is set to 1. This format is useful for compactly representing lengths in binary protocols.

      Parameters:
      in - the InputStream to read data from; must not be null
      maxSize - the maximum number of bytes allowed to be read from the stream; must be non-negative and less than or equal to Integer.MAX_VALUE - 10
      Returns:
      a byte[] array where the first bytes are the encoded length, followed by the data read
      Throws:
      IOException - if an I/O error occurs or if the data read exceeds maxSize
      IllegalArgumentException - if maxSize is negative or too large