/* * Copyright 2026 mingliqiye * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * * ProjectName mingli-utils * ModuleName mingli-utils.main * CurrentFile ByteBufferWrapper.kt * LastUpdate 2026-06-21 10:37:47 * UpdateUser MingLiPro */ package com.mingliqiye.utils.buffer import com.mingliqiye.utils.buffer.convertor.ByteBufferWrapperConvertor import com.mingliqiye.utils.bytes.* import com.mingliqiye.utils.netty.toByteBuffer import com.mingliqiye.utils.time.DateTime import com.mingliqiye.utils.time.DateTime.Companion.toDateTime import com.mingliqiye.utils.uuid.UUID import com.mingliqiye.utils.uuid.UUID.Companion.toMLUUID import io.netty.buffer.ByteBuf import java.math.BigDecimal import java.math.BigInteger import java.nio.ByteBuffer import java.nio.ByteOrder import java.nio.charset.Charset import java.time.Instant import java.time.LocalDateTime import java.time.ZoneId import java.util.* import java.util.concurrent.ConcurrentHashMap /** * ByteBuffer 包装器 * * 提供对 java.nio.ByteBuffer 的完整封装,支持链式调用和丰富的数据类型读写。 * 包含基础类型、大数、时间、UUID 等多种数据类型的读写方法。 * 100000 iterations took 52ms * * 使用示例: * ``` * // 写入数据 * val wrapper = ByteBufferWrapper.allocate(1024) * .putInt(100) * .putString("Hello") * .putUUID(UUID.randomUUID()) * .flip() // 切换到读模式 * * // 读取数据 * val intValue = wrapper.getInt() * val strValue = wrapper.getString() * val uuidValue = wrapper.getUUID() * ``` * * @param buffer 底层的 ByteBuffer 实例(私有构造,通过工厂方法创建) */ class ByteBufferWrapper private constructor(private val buffer: ByteBuffer) { /** * 缓冲区容量(总大小) */ @get:JvmName("capacity") val capacity: Int get() = buffer.capacity() /** * 当前位置(读写位置) */ @get:JvmName("position") val position: Int get() = buffer.position() /** * 剩余可读写字节数 */ @get:JvmName("remaining") val remaining: Int get() = buffer.remaining() /** * 是否还有剩余字节 */ @get:JvmName("hasRemaining") val hasRemaining: Boolean get() = buffer.hasRemaining() /** * 限制位置 */ @get:JvmName("limit") val limit: Int get() = buffer.limit() /** * 标记位置(实际 ByteBuffer 没有直接获取 mark 的方法,这里返回当前position) */ @get:JvmName("mark") val mark: Int get() = remaining /** * 是否具有可访问的底层数组 */ @get:JvmName("hasArray") val hasArray: Boolean get() = buffer.hasArray() /** * 获取底层数组(如果存在) * * @return 底层字节数组 * @throws UnsupportedOperationException 如果没有底层数组(如直接缓冲区) */ @get:JvmName("array") val array: ByteArray get() = buffer.array() /** * 转换为整个字节数组 * * @return 数组偏移量 * @throws UnsupportedOperationException 如果没有底层数组 */ fun toByteArray(): ByteArray = getByteArray(remaining) /** * 获取底层数组的偏移量 * * @return 数组偏移量 * @throws UnsupportedOperationException 如果没有底层数组 */ @get:JvmName("arrayOffset") val arrayOffset: Int get() = buffer.arrayOffset() /** * 是否为只读缓冲区 */ @get:JvmName("isReadOnly") val isReadOnly: Boolean get() = buffer.isReadOnly /** * 是否为直接缓冲区(堆外内存) */ @get:JvmName("isDirect") val isDirect: Boolean get() = buffer.isDirect /** * 当前字节序(大端/小端) */ @get:JvmName("order") val byteOrder: ByteOrder get() = buffer.order() /** * 是否为大端字节序 */ @get:JvmName("isBigEndian") val isBigEndian: Boolean get() = byteOrder == ByteOrder.BIG_ENDIAN /** * 是否为小端字节序 */ @get:JvmName("isLittleEndian") val isLittleEndian: Boolean get() = byteOrder == ByteOrder.LITTLE_ENDIAN /** * 缓冲区是否为空(无剩余字节) */ @get:JvmName("isEmpty") val isEmpty: Boolean get() = !hasRemaining /** * 缓冲区是否已满(position == capacity) */ @get:JvmName("isFull") val isFull: Boolean get() = position == capacity /** * 当前位置是否在限制之内 */ @get:JvmName("isWithinLimit") val isWithinLimit: Boolean get() = position < limit /** * 是否已到达限制位置 */ @get:JvmName("isAtLimit") val isAtLimit: Boolean get() = position == limit /** * 获取缓冲区的字符串表示 * * @return 格式化的字符串信息 */ override fun toString(): String { return "ByteBufferWrapper(capacity=$capacity, position=$position, limit=$limit, remaining=$remaining)#${hashCode()}" } /** * 伴生对象,提供工厂方法以及类型转换器的注册与查询功能。 */ companion object { /** * 包装现有的 ByteBuffer * * @param buffer 要包装的 ByteBuffer * @return 新的 ByteBufferWrapper 实例 */ @JvmStatic fun wrap(buffer: ByteBuffer): ByteBufferWrapper { return ByteBufferWrapper(buffer) } /** * 包装现有的 ByteBuf * * @param buffer 要包装的 ByteBuf * @return 新的 ByteBufferWrapper 实例 */ @JvmStatic fun wrap(buffer: ByteBuf): ByteBufferWrapper { return ByteBufferWrapper(buffer.toByteBuffer()) } /** * 包装字节数组 * * @param array 要包装的字节数组 * @return 新的 ByteBufferWrapper 实例 */ @JvmStatic fun wrap(array: ByteArray): ByteBufferWrapper { return ByteBufferWrapper(ByteBuffer.wrap(array)) } /** * 包装字节数组的一部分 * * @param array 要包装的字节数组 * @param offset 起始偏移量 * @param length 长度 * @return 新的 ByteBufferWrapper 实例 */ @JvmStatic fun wrap(array: ByteArray, offset: Int, length: Int): ByteBufferWrapper { return ByteBufferWrapper(ByteBuffer.wrap(array, offset, length)) } /** * 分配堆内缓冲区 * * @param capacity 缓冲区容量 * @return 新的 ByteBufferWrapper 实例 */ @JvmStatic fun allocate(capacity: Int): ByteBufferWrapper { return ByteBufferWrapper(ByteBuffer.allocate(capacity)) } /** * 分配直接缓冲区(堆外内存) * 适用于高性能 I/O 场景,但分配和释放成本较高 * * @param capacity 缓冲区容量 * @return 新的 ByteBufferWrapper 实例 */ @JvmStatic fun allocateDirect(capacity: Int): ByteBufferWrapper { return ByteBufferWrapper(ByteBuffer.allocateDirect(capacity)) } /** * 添加转换器到映射表,转换器内部通过 getType() 提供自己的类型信息 * * @param byteBufferWrapperConvertor 要添加的转换器实例,其泛型类型信息通过 getType() 方法获取 */ @JvmStatic fun addConvertor(byteBufferWrapperConvertor: ByteBufferWrapperConvertor<*>) { _ByteBufferWrapperConvertorMap[byteBufferWrapperConvertor.getType().kotlin.javaObjectType] = byteBufferWrapperConvertor } /** * 添加转换器到映射表,通过具体化类型参数自动创建转换器实例 * * @param T 转换器类型,必须提供无参构造函数 */ @JvmName("inline_addConvertor") inline fun > addConvertor() { addConvertor(ByteBufferWrapperConvertor.getInstantiation()) } /** * 添加转换器到映射表,显式指定要处理的类型 Class * * @param clazz 要处理的类型对应的 Class 对象 * @param byteBufferWrapperConvertor 与指定类型匹配的转换器实例 * @param T 要处理的数据类型 */ @JvmStatic fun addConvertor(clazz: Class, byteBufferWrapperConvertor: ByteBufferWrapperConvertor) { _ByteBufferWrapperConvertorMap[clazz.kotlin.javaObjectType] = byteBufferWrapperConvertor } /** * 根据类型 Class 从映射表中获取对应的转换器,并进行类型转换 * * @param clazz 要获取转换器的类型对应的 Class 对象 * @param T 要处理的数据类型 * @return 与指定类型匹配的转换器实例,如果不存在则返回 null */ @JvmStatic @Suppress("UNCHECKED_CAST") fun getConvertor(clazz: Class): ByteBufferWrapperConvertor? { return _ByteBufferWrapperConvertorMap[clazz] as? ByteBufferWrapperConvertor } /** * 从映射表中移除指定类型的转换器 * * @param clazz 要移除转换器的类型对应的 Class 对象 */ @JvmStatic fun delectConvertor(clazz: Class<*>) { _ByteBufferWrapperConvertorMap.remove(clazz) } /** * 存储类型与转换器映射关系的线程安全哈希表 * 键:要处理的类型 Class<*> * 值:对应的转换器实例 ByteBufferWrapperConvertor<*> */ private val _ByteBufferWrapperConvertorMap = ConcurrentHashMap, ByteBufferWrapperConvertor<*>>(64, 1.5f) init { ByteBufferWrapperConvertor.defaultConvertorInstall() } } /** * 将对象写入 ByteBufferWrapper * * 根据对象的实际类型获取对应的转换器,使用该转换器将对象写入当前的 ByteBufferWrapper * 支持方法链调用(返回 this) * * @param obj 要写入的对象,类型为 T * @return 当前的 ByteBufferWrapper 实例,支持链式调用 * @throws IllegalArgumentException 如果该对象类型没有注册对应的转换器 */ fun putObject(obj: Any): ByteBufferWrapper { val convertor = getConvertor(obj.javaClass) ?: throw IllegalArgumentException("${obj.javaClass.canonicalName} does not convertor exist") convertor.write(obj, this) return this } /** * 将一个字节写入缓冲区。 * * @param byte 要写入的字节值 * @return 当前包装器实例,支持链式调用 */ fun put(byte: Byte): ByteBufferWrapper = putByte(byte) /** * 将一个字符写入缓冲区(2字节)。 * * @param char 要写入的字符值 * @return 当前包装器实例,支持链式调用 */ fun put(char: Char): ByteBufferWrapper = putChar(char) /** * 将一个短整数写入缓冲区(2字节)。 * * @param short 要写入的短整数 * @return 当前包装器实例,支持链式调用 */ fun put(short: Short): ByteBufferWrapper = putShort(short) /** * 将一个整数写入缓冲区(4字节)。 * * @param int 要写入的长整数 * @return 当前包装器实例,支持链式调用 */ fun put(int: Int): ByteBufferWrapper = putInt(int) /** * 将一个长整数写入缓冲区(8字节)。 * * @param long 要写入的长整数 * @return 当前包装器实例,支持链式调用 */ fun put(long: Long): ByteBufferWrapper = putLong(long) /** * 将一个布尔值写入缓冲区(1字节)。 * 通常编码为:true = 0x01,false = 0x00。 * * @param boolean 要写入的布尔值 * @return 当前包装器实例,支持链式调用 */ fun put(boolean: Boolean): ByteBufferWrapper = putBoolean(boolean) /** * 将一个单精度浮点数写入缓冲区(4字节)。 * * @param float 要写入的单精度浮点数 * @return 当前包装器实例,支持链式调用 */ fun put(float: Float): ByteBufferWrapper = putFloat(float) /** * 将一个双精度浮点数写入缓冲区(8字节)。 * * @param double 要写入的双精度浮点数 * @return 当前包装器实例,支持链式调用 */ fun put(double: Double): ByteBufferWrapper = putDouble(double) /** * 将字节数组完整写入缓冲区。 * * @param byteArray 要写入的字节数组 * @return 当前包装器实例,支持链式调用 */ fun put(byteArray: ByteArray): ByteBufferWrapper = putByteArray(byteArray) /** * 将字符数组完整写入缓冲区(每个字符2字节)。 * * @param charArray 要写入的字符数组 * @return 当前包装器实例,支持链式调用 */ fun put(charArray: CharArray): ByteBufferWrapper = putCharArray(charArray) /** * 将短整数数组完整写入缓冲区(每个短整数2字节)。 * * @param shortArray 要写入的短整数数组 * @return 当前包装器实例,支持链式调用 */ fun put(shortArray: ShortArray): ByteBufferWrapper = putShortArray(shortArray) /** * 将整数数组完整写入缓冲区(每个长整数4字节)。 * * @param intArray 要写入的长整数数组 * @return 当前包装器实例,支持链式调用 */ fun put(intArray: IntArray): ByteBufferWrapper = putIntArray(intArray) /** * 将长整数数组完整写入缓冲区(每个长整数8字节)。 * * @param longArray 要写入的长整数数组 * @return 当前包装器实例,支持链式调用 */ fun put(longArray: LongArray): ByteBufferWrapper = putLongArray(longArray) /** * 将布尔数组完整写入缓冲区(每个布尔值1字节)。 * * @param booleanArray 要写入的布尔数组 * @return 当前包装器实例,支持链式调用 */ fun put(booleanArray: BooleanArray): ByteBufferWrapper = putBooleanArray(booleanArray) /** * 将单精度浮点数数组完整写入缓冲区(每个浮点数4字节)。 * * @param floatArray 要写入的单精度浮点数数组 * @return 当前包装器实例,支持链式调用 */ fun put(floatArray: FloatArray): ByteBufferWrapper = putFloatArray(floatArray) /** * 将双精度浮点数数组完整写入缓冲区(每个双精度浮点数8字节)。 * * @param doubleArray 要写入的双精度浮点数数组 * @return 当前包装器实例,支持链式调用 */ fun put(doubleArray: DoubleArray): ByteBufferWrapper = putDoubleArray(doubleArray) /** * 将 DateTime 对象写入缓冲区。 * * @param dateTime 要写入的 DateTime 对象 * @return 当前包装器实例,支持链式调用 */ fun put(dateTime: DateTime): ByteBufferWrapper = putDateTime(dateTime) /** * 将 LocalDateTime 对象写入缓冲区。 * * @param localDateTime 要写入的 LocalDateTime 对象 * @return 当前包装器实例,支持链式调用 */ fun put(localDateTime: LocalDateTime): ByteBufferWrapper = putLocalDateTime(localDateTime) /** * 将 Date 对象写入缓冲区。 * * @param date 要写入的 Date 对象 * @return 当前包装器实例,支持链式调用 */ fun put(date: Date): ByteBufferWrapper = putDate(date) /** * 将字符串写入缓冲区。 * * @param string 要写入的字符串 * @return 当前包装器实例,支持链式调用 */ fun put(string: String): ByteBufferWrapper = putString(string) /** * 将 ByteFlags 标志位对象写入缓冲区。 * * @param byteFlags 要写入的标志位对象 * @return 当前包装器实例,支持链式调用 */ fun put(byteFlags: ByteFlags): ByteBufferWrapper = putFlag(byteFlags) /** * 从 ByteBufferWrapper 中读取指定类型的对象 * * 根据指定的类型获取对应的转换器,使用该转换器从当前的 ByteBufferWrapper 中读取对象 * * @param clazz 要读取的对象类型对应的 Class 对象 * @param T 要读取的对象类型 * @return 读取并转换后的 T 类型对象 * @throws IllegalArgumentException 如果该类型没有注册对应的转换器 */ fun getObject(clazz: Class, parameters: Array): T { val convertor = getConvertor(clazz) ?: throw IllegalArgumentException("${clazz.canonicalName} does not convertor exist") return convertor.read(this, parameters) } /** * 从缓冲区中读取指定类型的对象(不带额外参数) * * @param clazz 要读取的对象类型对应的 Class 对象 * @param T 要读取的对象类型 * @return 读取并转换后的 T 类型对象 * @throws IllegalArgumentException 如果该类型没有注册对应的转换器 */ fun getObject(clazz: Class): T { return getObject(clazz, emptyArray()) } /** * 从缓冲区中读取指定类型的对象,并传入长度参数 * * @param clazz 要读取的对象类型对应的 Class 对象 * @param size 读取长度(如数组元素个数),作为转换器的第一个参数 * @param T 要读取的对象类型 * @return 读取并转换后的 T 类型对象 * @throws IllegalArgumentException 如果该类型没有注册对应的转换器 */ fun getObject(clazz: Class, size: Int): T { return getObject(clazz, arrayOf(size)) } /** * 从缓冲区中读取具体化类型 T 的对象,并传入额外参数 * * @param parameters 传递给转换器的参数数组 * @param T 要读取的对象类型 * @return 读取并转换后的 T 类型对象 * @throws IllegalArgumentException 如果该类型没有注册对应的转换器 */ @JvmName("inline_getObject") inline fun getObject(parameters: Array): T { return getObject(T::class.java, parameters) } /** * 从缓冲区中读取具体化类型 T 的对象,并传入长度参数 * * @param size 读取长度(如数组元素个数),作为转换器的第一个参数 * @param T 要读取的对象类型 * @return 读取并转换后的 T 类型对象 * @throws IllegalArgumentException 如果该类型没有注册对应的转换器 */ @JvmName("inline_getObject") inline fun getObject(size: Int): T { return getObject(T::class.java, size) } /** * 从缓冲区中读取具体化类型 T 的对象(不带额外参数) * * @param T 要读取的对象类型 * @return 读取并转换后的 T 类型对象 * @throws IllegalArgumentException 如果该类型没有注册对应的转换器 */ @JvmName("inline_getObject") inline fun getObject(): T { return getObject(T::class.java) } /** * 写入字节数组 * * @param byteArray 要写入的字节数组 * @param offset 起始偏移量(默认为0) * @param length 写入长度(默认为数组长度) * @return 当前对象(支持链式调用) */ fun putByteArray(byteArray: ByteArray, offset: Int = 0, length: Int = byteArray.size): ByteBufferWrapper { buffer.put(byteArray, offset, length) return this } /** * 按初始化函数生成指定长度的字节数组并写入缓冲区 * * @param size 要生成并写入的字节数 * @param init 初始化函数,根据索引生成每个字节的值 * @return 当前对象(支持链式调用) */ fun putByteArray(size: Int, init: (Int) -> Byte): ByteBufferWrapper { buffer.put(ByteArray(size, init)) return this } /** * 将字符数组完整写入缓冲区(每个字符取低 8 位,1字节) * * @param charArray 要写入的字符数组 * @return 当前对象(支持链式调用) */ fun putCharArray(charArray: CharArray): ByteBufferWrapper { putByteArray(charArray.size) { charArray[it].code.toByte() } return this } /** * 读取指定长度的字符数组(每个字节转换为一个字符) * * @param size 要读取的字符数 * @return 读取的字符数组 */ fun getCharArray(size: Int): CharArray { return getByteArray(size).let { CharArray(it.size) { s -> it[s].toInt().toChar() } } } /** * 将整数数组完整写入缓冲区(每个整数4字节) * * @param intArray 要写入的整数数组 * @return 当前对象(支持链式调用) */ fun putIntArray(intArray: IntArray): ByteBufferWrapper { intArray.forEach(::putInt) return this } /** * 读取指定长度的整数数组 * * @param size 要读取的整数个数 * @return 读取的整数数组 */ fun getIntArray(size: Int): IntArray { return IntArray(size) { getInt() } } /** * 将短整数数组完整写入缓冲区(每个短整数2字节) * * @param shortArray 要写入的短整数数组 * @return 当前对象(支持链式调用) */ fun putShortArray(shortArray: ShortArray): ByteBufferWrapper { shortArray.forEach(::putShort) return this } /** * 读取指定长度的短整数数组 * * @param size 要读取的短整数个数 * @return 读取的短整数数组 */ fun getShortArray(size: Int): ShortArray { return ShortArray(size) { getShort() } } /** * 将长整数数组完整写入缓冲区(每个长整数8字节) * * @param longArray 要写入的长整数数组 * @return 当前对象(支持链式调用) */ fun putLongArray(longArray: LongArray): ByteBufferWrapper { longArray.forEach(::putLong) return this } /** * 读取指定长度的长整数数组 * * @param size 要读取的长整数个数 * @return 读取的长整数数组 */ fun getLongArray(size: Int): LongArray { return LongArray(size) { getLong() } } /** * 将双精度浮点数数组完整写入缓冲区(每个浮点数8字节) * * @param doubleArray 要写入的双精度浮点数数组 * @return 当前对象(支持链式调用) */ fun putDoubleArray(doubleArray: DoubleArray): ByteBufferWrapper { doubleArray.forEach(::putDouble) return this } /** * 读取指定长度的双精度浮点数数组 * * @param size 要读取的双精度浮点数个数 * @return 读取的双精度浮点数数组 */ fun getDoubleArray(size: Int): DoubleArray { return DoubleArray(size) { getDouble() } } /** * 将单精度浮点数数组完整写入缓冲区(每个浮点数4字节) * * @param floatArray 要写入的单精度浮点数数组 * @return 当前对象(支持链式调用) */ fun putFloatArray(floatArray: FloatArray): ByteBufferWrapper { floatArray.forEach(::putFloat) return this } /** * 读取指定长度的单精度浮点数数组 * * @param size 要读取的单精度浮点数个数 * @return 读取的单精度浮点数数组 */ fun getFloatArray(size: Int): FloatArray { return FloatArray(size) { getFloat() } } /** * 将布尔数组完整写入缓冲区(每个布尔值1字节,true = 0x01,false = 0x00) * * @param booleanArray 要写入的布尔数组 * @return 当前对象(支持链式调用) */ fun putBooleanArray(booleanArray: BooleanArray): ByteBufferWrapper { putByteArray(booleanArray.size) { if (booleanArray[it]) 0x01 else 0x00 } return this } /** * 读取指定长度的布尔数组 * * @param size 要读取的布尔值个数 * @return 读取的布尔数组 * @throws IllegalArgumentException 如果读取到的字节值不是 0x00 或 0x01 */ fun getBooleanArray(size: Int): BooleanArray { return getByteArray(size).let { BooleanArray(it.size) { index -> when (val itm = it[index]) { 0x00.toByte() -> false 0x01.toByte() -> true else -> throw IllegalArgumentException("$itm not Boolean") } } } } /** * 写入单个字节 * * @param byte 要写入的字节 * @return 当前对象(支持链式调用) */ fun putByte(byte: Byte): ByteBufferWrapper { buffer.put(byte) return this } /** * 写入字符(2字节) * * @param char 要写入的字符 * @return 当前对象(支持链式调用) */ fun putChar(char: Char): ByteBufferWrapper { buffer.putChar(char) return this } /** * 写入短整数(2字节) * * @param short 要写入的短整数 * @return 当前对象(支持链式调用) */ fun putShort(short: Short): ByteBufferWrapper { buffer.putShort(short) return this } /** * 写入整数(4字节) * * @param int 要写入的整数 * @return 当前对象(支持链式调用) */ fun putInt(int: Int): ByteBufferWrapper { buffer.putInt(int) return this } /** * 写入长整数(8字节) * * @param long 要写入的长整数 * @return 当前对象(支持链式调用) */ fun putLong(long: Long): ByteBufferWrapper { buffer.putLong(long) return this } /** * 写入 BigInteger(大整数) * 格式:[长度:4字节] + [] * * @param bigInteger 要写入的 BigInteger * @return 当前对象(支持链式调用) */ fun putBigInteger(bigInteger: BigInteger): ByteBufferWrapper { val byteArray = bigInteger.toByteArray() putInt(byteArray.size) buffer.put(byteArray) return this } /** * 写入单精度浮点数(4字节) * * @param float 要写入的浮点数 * @return 当前对象(支持链式调用) */ fun putFloat(float: Float): ByteBufferWrapper { buffer.putFloat(float) return this } /** * 写入双精度浮点数(8字节) * * @param double 要写入的双精度浮点数 * @return 当前对象(支持链式调用) */ fun putDouble(double: Double): ByteBufferWrapper { buffer.putDouble(double) return this } /** * 写入 BigDecimal(高精度小数) * 格式:[scale:4字节] + [BigInteger] * * @param bigDecimal 要写入的 BigDecimal * @return 当前对象(支持链式调用) */ fun putBigDecimal(bigDecimal: BigDecimal): ByteBufferWrapper { putInt(bigDecimal.scale()) putBigInteger(bigDecimal.unscaledValue()) return this } /** * 写入布尔值(1字节) * 0x00 = false, 0x01 = true * * @param boolean 要写入的布尔值 * @return 当前对象(支持链式调用) */ fun putBoolean(boolean: Boolean): ByteBufferWrapper { putByte(if (boolean) 0x01 else 0x00) return this } /** * 写入标志位(ByteFlags) * * @param flags 要写入的标志位 * @return 当前对象(支持链式调用) */ fun putFlag(flags: ByteFlags): ByteBufferWrapper { putByte(flags.toByte()) return this } /** * 写入字符串(带长度前缀) * 格式:[长度:变长] + [UTF-8字节数组] * * @param string 要写入的字符串 * @param charset 字符集(默认 UTF-8) * @return 当前对象(支持链式调用) */ fun putString(string: String, charset: Charset = Charsets.UTF_8): ByteBufferWrapper { buffer.putString(string, charset) return this } /** * 写入变长编码的短整数 * 使用 VarInt 编码节省空间 * * @param varShort 要写入的短整数 * @return 当前对象(支持链式调用) */ fun putVarShort(varShort: Short): ByteBufferWrapper { buffer.putVarShort(varShort) return this } /** * 写入变长编码的整数 * 使用 VarInt 编码节省空间 * * @param varInt 要写入的整数 * @return 当前对象(支持链式调用) */ fun putVarInt(varInt: Int): ByteBufferWrapper { buffer.putVarInt(varInt) return this } /** * 写入变长编码的长整数 * 使用 VarLong 编码节省空间 * * @param varLong 要写入的长整数 * @return 当前对象(支持链式调用) */ fun putVarLong(varLong: Long): ByteBufferWrapper { buffer.putVarLong(varLong) return this } /** * 写入 Instant(时间戳) * 格式:[seconds:8字节] + [nanos:4字节] * * @param instant 要写入的 Instant * @return 当前对象(支持链式调用) */ fun putInstant(instant: Instant): ByteBufferWrapper { putLong(instant.epochSecond) putInt(instant.nano) return this } /** * 写入 DateTime(Joda-Time) * * @param dateTime 要写入的 DateTime * @return 当前对象(支持链式调用) */ fun putDateTime(dateTime: DateTime): ByteBufferWrapper { putInstant(dateTime.toInstant()) return this } /** * 写入 LocalDateTime(Java 8 时间) * * @param localDateTime 要写入的 LocalDateTime * @return 当前对象(支持链式调用) */ fun putLocalDateTime(localDateTime: LocalDateTime): ByteBufferWrapper { putDateTime(localDateTime.toDateTime()) return this } /** * 写入 Date(传统 Java 日期) * * @param date 要写入的 Date * @return 当前对象(支持链式调用) */ fun putDate(date: Date): ByteBufferWrapper { putDateTime(date.toDateTime()) return this } /** * 写入自定义 UUID * * @param uuid 要写入的 UUID * @return 当前对象(支持链式调用) */ fun putUUID(uuid: UUID): ByteBufferWrapper { putByteArray(uuid.toBytes()) return this } /** * 写入 Java UUID * * @param uuid 要写入的 Java UUID * @return 当前对象(支持链式调用) */ fun putUUID(uuid: java.util.UUID): ByteBufferWrapper { putByteArray(uuid.toMLUUID().toBytes()) return this } /** * 读取字节数组 * * @param size 要读取的字节数 * @return 读取的字节数组 */ fun getByteArray(size: Int): ByteArray { return ByteArray(size).let { buffer.get(it) it } } /** * 读取单个字节 * * @return 读取的字节 */ fun getByte(): Byte { return buffer.get() } /** * 读取字符 * * @return 读取的字符 */ fun getChar(): Char { return buffer.getChar() } /** * 读取短整数 * * @return 读取的短整数 */ fun getShort(): Short { return buffer.getShort() } /** * 读取整数 * * @return 读取的整数 */ fun getInt(): Int { return buffer.getInt() } /** * 读取长整数 * * @return 读取的长整数 */ fun getLong(): Long { return buffer.getLong() } /** * 读取 BigInteger * * @return 读取的 BigInteger */ fun getBigInteger(): BigInteger { return BigInteger(getByteArray(getInt())) } /** * 读取单精度浮点数 * * @return 读取的浮点数 */ fun getFloat(): Float { return buffer.getFloat() } /** * 读取双精度浮点数 * * @return 读取的双精度浮点数 */ fun getDouble(): Double { return buffer.getDouble() } /** * 读取 BigDecimal * * @return 读取的 BigDecimal */ fun getBigDecimal(): BigDecimal { val scale = getInt() return BigDecimal(getBigInteger(), scale) } /** * 读取布尔值 * * @return 读取的布尔值 * @throws IllegalArgumentException 如果字节值不是 0x00 或 0x01 */ fun getBoolean(): Boolean { return when (getByte()) { 0x00.toByte() -> false 0x01.toByte() -> true else -> throw java.lang.IllegalArgumentException("Not a boolean") } } /** * 读取标志位 * * @return 读取的 ByteFlags */ fun getFlag(): ByteFlags { return ByteFlags(getByte()) } /** * 读取字符串 * * @param charset 字符集(默认 UTF-8) * @return 读取的字符串 */ fun getString(charset: Charset = Charsets.UTF_8): String { return buffer.getString(charset) } /** * 读取变长编码的短整数 * * @return 读取的短整数 */ fun getVarShort(): Short { return buffer.getVarShort() } /** * 读取变长编码的整数 * * @return 读取的整数 */ fun getVarInt(): Int { return buffer.getVarInt() } /** * 读取变长编码的长整数 * * @return 读取的长整数 */ fun getVarLong(): Long { return buffer.getVarLong() } /** * 读取 Instant * * @return 读取的 Instant */ fun getInstant(): Instant { return Instant.ofEpochSecond(getLong(), getInt().toLong()) } /** * 读取 DateTime(Joda-Time) * * @param zoneId 时区(默认系统时区) * @return 读取的 DateTime */ fun getDateTime(zoneId: ZoneId = ZoneId.systemDefault()): DateTime { return DateTime.of(getInstant(), zoneId) } /** * 读取 LocalDateTime * * @param zoneId 时区(默认系统时区) * @return 读取的 LocalDateTime */ fun getLocalDateTime(zoneId: ZoneId = ZoneId.systemDefault()): LocalDateTime { return getDateTime(zoneId).toLocalDateTime() } /** * 读取 Date * * @param zoneId 时区(默认系统时区) * @return 读取的 Date */ fun getDate(zoneId: ZoneId = ZoneId.systemDefault()): Date { return getDateTime(zoneId).toDate() } /** * 读取自定义 UUID * * @return 读取的 UUID */ fun getUUID(): UUID { return getByteArray(16).let { UUID.of(it) } } /** * 读取 Java UUID * * @return 读取的 Java UUID */ fun getJUUID(): java.util.UUID { return getByteArray(16).let { UUID.of(it).getUuid() } } /** * 创建当前缓冲区的副本 * 共享内容但拥有独立的位置、限制和标记 * * @return 新的 ByteBufferWrapper 实例 */ fun duplicate(): ByteBufferWrapper { return ByteBufferWrapper(buffer.duplicate()) } /** * 创建当前缓冲区的只读视图 * * @return 只读的 ByteBufferWrapper 实例 */ fun asReadOnly(): ByteBufferWrapper { return ByteBufferWrapper(buffer.asReadOnlyBuffer()) } /** * 创建当前缓冲区的切片 * 从当前位置到限制的共享视图 * * @return 新的 ByteBufferWrapper 实例 */ fun slice(): ByteBufferWrapper { return ByteBufferWrapper(buffer.slice()) } /** * 设置位置 * * @param newPosition 新的位置 * @return 当前对象(支持链式调用) * @throws IllegalArgumentException 如果位置超出范围 */ fun position(newPosition: Int): ByteBufferWrapper { buffer.position(newPosition) return this } /** * 设置限制 * * @param newLimit 新的限制 * @return 当前对象(支持链式调用) * @throws IllegalArgumentException 如果限制超出范围 */ fun limit(newLimit: Int): ByteBufferWrapper { buffer.limit(newLimit) return this } /** * 设置标记位置 * * @return 当前对象(支持链式调用) */ fun mark(): ByteBufferWrapper { buffer.mark() return this } /** * 重置到标记位置 * * @return 当前对象(支持链式调用) * @throws java.nio.InvalidMarkException 如果没有标记 */ fun reset(): ByteBufferWrapper { buffer.reset() return this } /** * 设置字节序 * * @param byteOrder 字节序(BIG_ENDIAN 或 LITTLE_ENDIAN) * @return 当前对象(支持链式调用) */ fun order(byteOrder: ByteOrder): ByteBufferWrapper { buffer.order(byteOrder) return this } /** * 设置为大端字节序 * * @return 当前对象(支持链式调用) */ fun asBigEndian(): ByteBufferWrapper { buffer.order(ByteOrder.BIG_ENDIAN) return this } /** * 设置为小端字节序 * * @return 当前对象(支持链式调用) */ fun asLittleEndian(): ByteBufferWrapper { buffer.order(ByteOrder.LITTLE_ENDIAN) return this } /** * 清除缓冲区 * position = 0, limit = capacity, mark = -1 * 准备重新写入 * * @return 当前对象(支持链式调用) */ fun clear(): ByteBufferWrapper { buffer.clear() return this } /** * 翻转缓冲区 * limit = position, position = 0, mark = -1 * 用于从写入模式切换到读取模式 * * @return 当前对象(支持链式调用) */ fun flip(): ByteBufferWrapper { buffer.flip() return this } /** * 重绕缓冲区 * position = 0, mark = -1 * 准备重新读取 * * @return 当前对象(支持链式调用) */ fun rewind(): ByteBufferWrapper { buffer.rewind() return this } /** * 压缩缓冲区 * 将未读数据移到开头,position = 剩余字节数,limit = capacity * 适用于部分读取后想继续写入的场景 * * @return 当前对象(支持链式调用) */ fun compact(): ByteBufferWrapper { buffer.compact() return this } /** * 跳过指定字节数 * 相当于 position += bytes * * @param bytes 要跳过的字节数 * @return 当前对象(支持链式调用) * @throws IllegalArgumentException 如果跳过的字节数超出范围 */ fun skip(bytes: Int): ByteBufferWrapper { buffer.position(buffer.position() + bytes) return this } /** * 跳转到指定位置 * * @param newPosition 目标位置 * @return 当前对象(支持链式调用) */ fun jumpTo(newPosition: Int): ByteBufferWrapper { buffer.position(newPosition) return this } /** * 回到开头 * position = 0 * * @return 当前对象(支持链式调用) */ fun rewindToStart(): ByteBufferWrapper { buffer.position(0) return this } /** * 跳到末尾 * position = limit * * @return 当前对象(支持链式调用) */ fun jumpToEnd(): ByteBufferWrapper { buffer.position(buffer.limit()) return this } }