DataSketches Java Memory 组件技术文档

以下是对DataSketches Java Memory组件的详细技术文档，包含安装指南、使用说明和API使用文档。

1. 安装指南

环境要求

• Java Development Kit (JDK) 版本 17 或更高版本。

Maven构建

1. 克隆项目到本地目录。
2. 确保你的Maven配置正确，并且安装了JDK 17。
3. 运行以下命令构建项目：

mvn clean install -DskipTests=true

构建过程将会生成以下JAR包：

• datasketches-memory-X.Y.Z.jar：编译后的主类文件。
• datasketches-memory-X.Y.Z-tests.jar：编译后的测试类文件。
• datasketches-memory-X.Y.Z-sources.jar：主源代码文件。
• datasketches-memory-X.Y.Z-test-sources.jar：测试源代码文件。
• datasketches-memory-X.Y.Z-javadoc.jar：压缩的Javadoc文档。

注意事项

• 在构建时，确保编译命令行包含JVM参数--add-modules=jdk.incubator.foreign。
• 此组件不是作为Java模块设计的，因此JAR文件应该是应用程序类路径的一部分。

2. 项目的使用说明

DataSketches Java Memory组件提供了对以下四种不同类型内存资源的访问API：

• 通过原始数组在Java堆上构建的连续字节（只读）。
• 通过原始数组在Java堆上构建的连续字节（可写）。
• 通过ByteBuffer在Java堆上构建的连续字节（只读和可写）。
• 通过直接分配在Java堆外构建的连续字节（只读和可写）。
• 通过内存映射文件在Java堆外构建的连续字节（只读和可写）。

以下是一些示例：

Java堆上的连续字节

通过原始数组

• 只读：Memory.wrap(primitive[])
• 可写：WritableMemory.allocate(int)
• 可写（包装）：WritableMemory.writableWrap(primitive[])

通过ByteBuffer

• 只读：Memory.wrap(ByteBuffer.wrap(byte[]))
• 可写：WritableMemory.writableWrap(ByteBuffer.allocate(int))

Java堆外的连续字节

通过直接分配

• 可写：WritableMemory.allocateDirect(long)

通过ByteBuffer

• 可写：WritableMemory.writableWrap(ByteBuffer.allocateDirect(int))

通过内存映射文件

• 只读：Memory.map(File)
• 可写：WritableMemory.writableMap(File)

3. 项目API使用文档

Memory类

• 用于访问不同类型的内存资源。

• Memory.wrap(primitive[])：将原始数组包装为Memory对象（只读）。

• Memory.wrap(ByteBuffer.wrap(byte[]))：将ByteBuffer包装为Memory对象（只读）。

• Memory.map(File)：从文件创建Memory对象（只读）。

WritableMemory类

• 用于可写操作。

• WritableMemory.allocate(int)：在Java堆上分配内存。

• WritableMemory.allocateDirect(long)：直接分配堆外内存。

• WritableMemory.writableWrap(primitive[])：将原始数组包装为WritableMemory对象。

• WritableMemory.writableWrap(ByteBuffer.allocate(int))：将ByteBuffer包装为WritableMemory对象。

• WritableMemory.writableMap(File)：从文件创建WritableMemory对象。

请注意，DataSketches Java Memory组件不是线程安全的。

4. 项目安装方式

项目的安装方式已在“安装指南”部分详细说明。使用Maven构建和安装项目是最推荐的方式。确保遵循构建指南中的步骤，并正确配置Maven环境。安装完成后，生成的JAR包可以直接用于开发或部署。