键值存储数据库(chronicle-map)

概述

是一个高性能、低延迟的Java键值存储库，特别适用于需要高并发和持久化的场景。

maven依赖

xml 复制代码

        <dependency>
            <groupId>net.openhft</groupId>
            <artifactId>chronicle-map</artifactId>
            <version>3.27ea1</version>
        </dependency>
        <!-- getAll(File toFile)方法需要以下依赖 -->
        <dependency>
            <groupId>xstream</groupId>
            <artifactId>xstream</artifactId>
            <version>1.2.2</version>
        </dependency>
        <dependency>
             <groupId>org.codehaus.jettison</groupId>
             <artifactId>jettison</artifactId>
             <version>1.3.6</version>
        </dependency>

示例

内存模式

java 复制代码

    @Test
    void contextLoads() throws IOException {
        // 创建ChronicleMap实例，并将其持久化到磁盘文件
        ChronicleMap<String, String> chronicleMap = ChronicleMapBuilder.of(String.class, String.class)
                .name("persisted-map")
                .entries(10000)
                .averageValueSize(100)
                .create();
        // 插入键值对并获取值
        chronicleMap.put("key1", "value1");
        System.out.println(chronicleMap.get("key1"));
        // 关闭ChronicleMap实例以释放资源
        chronicleMap.close();
    }

持久化模式

java 复制代码

    @Test
    void contextLoads() throws IOException {
        // 创建ChronicleMap实例，并将其持久化到磁盘文件
        ChronicleMap<String, String> chronicleMap = ChronicleMapBuilder.of(String.class, String.class)
                .name("persisted-map")
                .entries(10000)
                .averageValueSize(100)
                .createPersistedTo(new File("E:\\db\\ChronicleMap.dat"));
        // 插入键值对并获取值
        chronicleMap.put("key1", "value1");
        System.out.println(chronicleMap.get("key1"));
        // 关闭ChronicleMap实例以释放资源
        chronicleMap.close();
    }

常用API

基础API

ChronicleMapBuilder

方法	说明
of(Class<K> keyClass,Class<V> valueClass)	静态方法
simpleMapOf(Class<K> keyClass,Class<V> valueClass)	静态方法
clone()	克隆对象
name(String name)	用于设置 Map 名称
averageKeySize(double averageKeySize)	用于指定存储在数据库中的键的平均字节长度。
averageKey(K averageKey)	用于通过样本对象精确预估固定大小键内存占用的配置方法。
averageValueSize(double averageValueSize)	指定存储在数据库中的值的平均字节长度
averageValue(V averageValue)	用于通过样本对象精确预估固定大小值内存占用的配置方法，适用于值类型为固定大小对象或自定义值接口的场景
constantKeySizeBySample(K sampleKey)	用于声明所有键具有相同固定大小，适用于键类型为固定大小且无需动态计算的场景。
constantValueSizeBySample(V sampleValue)	用于声明所有值具有相同固定大小，适用于值类型为固定大小且无需动态计算的场景。
actualChunkSize(int actualChunkSize)	指定每个内存块的固定字节大小
maxChunksPerEntry(int maxChunksPerEntry)	用于限制单个键值对可占用最大内存块数，主要用于防止超大值导致内存溢出或性能崩溃
entryAndValueOffsetAlignment(int alignment)	用于指定键值对存储偏移量对齐字节数，主要用于优化内存访问性能和硬件兼容性
entries(long entries)	用于设置键值对最大数量，直接影响内存分配和并发性能
entriesPerSegment(long entriesPerSegment)	用于显式指定每个内存分段包含键值对数量，直接影响并发性能和锁粒度
actualChunksPerSegmentTier(long actualChunksPerSegmentTier)	用于控制每个内存分段层级可分配内存块数量，主要用于优化超大键值对的存储效率和内存碎片管理
minSegments(int minSegments)	用于显式指定最小分段数量，直接影响并发性能和内存分配策略
actualSegments(int actualSegments)	用于精确控制最终创建的内存分段数量，直接影响并发性能和内存布局
putReturnsNull(boolean putReturnsNull)	用于控制 put() 方法在键已存在时的返回行为。为true时返回null，为false时返回旧值
putIfAbsentUsingValue(boolean putIfAbsentUsingValue)	用于控制 putIfAbsent() 方法行为，决定当键不存在时是否直接使用提供的值对象（而非克隆）进行存储
removeReturnsNull(boolean removeReturnsNull)	用于控制 remove() 方法在键不存在时的返回行为，为true时返回null，为false时抛出异常
maxBloatFactor() maxBloatFactor(double maxBloatFactor)	用于控制内存分配膨胀系数，直接影响Map的最大容量限制和内存使用效率
allowSegmentTiering(boolean allowSegmentTiering)	用于控制内存分段分层存储，通过启用/禁用分段分层策略来优化大规模数据存储的内存使用和访问性能
nonTieredSegmentsPercentile(double nonTiered)	用于控制分段存储策略的阈值，通过指定百分比值来决定哪些数据段保持非分层存储
keyReaderAndDataAccess(SizedReader<K> keyReader,DataAccess<K> keyDataAccess)	用于配置自定义键序列化/反序列化逻辑，适用于需要优化键类型处理或支持非标准数据格式的场景
keyMarshallers(SizedReader<K> keyReader,SizedWriter<? super K> keyWriter) keyMarshallers(BytesReader<K> keyReader,BytesWriter<? super K> keyWriter)	用于配置键类型自定义序列化/反序列化，适用于需要高性能或特殊格式处理的键类型
valueMarshallers(SizedReader<V> valueReader,SizedWriter<? super V> valueWriter) valueMarshallers(BytesReader<V> valueReader,BytesWriter<? super V> valueWriter)	用于配置值类型自定义序列化/反序列化，适用于需要高性能或特殊格式处理的值类型
keyMarshaller(M sizedMarshaller) keyMarshaller(M marshaller)	用于自定义键序列化/反序列化行为，通过实现这些接口可以优化存储效率并支持复杂数据类型
valueMarshaller(M sizedMarshaller) valueMarshaller(M marshaller)	用于自定义值序列化/反序列化行为的核心接口，通过实现这些接口可以优化存储效率并支持复杂数据类型
keySizeMarshaller(SizeMarshaller keySizeMarshaller)	用于配置键大小计算逻辑的接口，适用于需要自定义键内存占用计算方式的场景。
valueSizeMarshaller(SizeMarshaller valueSizeMarshaller)	用于配置值大小计算逻辑的接口，适用于需要自定义值内存占用计算方式的场景。
aligned64BitMemoryOperationsAtomic(boolean aligned64Bit)	用于控制是否启用64位对齐原子内存操作，适用于需要优化多线程环境下内存访问性能的场景
checksumEntries(boolean checksumEntries)	用于控制是否为存储条目启用校验和功能，适用于需要检测数据完整性的场景
valueReaderAndDataAccess(SizedReader<V> valueReader,DataAccess<V> valueDataAccess)	用于自定义值存储访问机制，允许开发者直接控制值的读取方式和数据访问策略
defaultValueProvider(DefaultValueProvider<K, V> defaultValueProvider)	用于为集合提供动态默认值，允许在键不存在时通过自定义逻辑生成默认值
replication(byte identifier)	用于配置数据库复制功能的标识符，属于分布式场景下的高可用性配置
replicatedMapClassName(String replicatedMapClassName)	用于配置分布式环境下复制映射实现类，属于高可用集群架构的关键配置项
sparseFile() sparseFile(boolean sparseFile)	用于控制存储文件是否采用稀疏模式，主要影响磁盘空间利用率和文件系统性能
setPreShutdownAction(Runnable preShutdownAction)	用于配置数据库关闭前执行自定义清理逻辑
skipCloseOnExitHook(boolean skipCloseOnExitHook)	用于控制是否跳过 JVM 关闭时自动执行数据库清理钩子
entryOperations(MapEntryOperations<K, V, ?> entryOperations)	用于自定义键值对操作行为，属于高级数据操作配置项
mapMethods(MapMethods<K, V, ?> mapMethods)	用于注入自定义键值操作
createPersistedTo(File file)	用于创建持久化到指定文件
create()	用于创建内存数据库
recoverPersistedTo(File file, boolean sameBuilderConfigAndLibraryVersion) recoverPersistedTo(File file, boolean sameBuilderConfigAndLibraryVersion,ChronicleHashCorruption.Listener corruptionListener)	用于从文件中恢复持久化数据
constantlySizedKeys()	用于声明键类型具有固定长度的序列化优化方法。
constantlySizedValues()	用于声明值类型具有固定长度的序列化优化方法。
validateAlignment(int ifSet, int actualChunkSize, int alignment)	用于验证数据块对齐条件，通常用于内存或存储操作前的参数校验。

ChronicleMap(ConcurrentMap的子接口，只展出其常用方法)

方法	说明
put(K key, V value)	添加数据
putAll(File fromFile) putAll(Map<? extends K, ? extends V> m)	通过文件或Map集合添加数据
putIfAbsent(K key, V value)	线程安全的条件写入，仅在键不存在时插入值。
get(Object key)	获取指定键的值
getMapped(K key, SerializableFunction<? super V, R> function)	用于对键值进行条件转换并返回新值的线程安全方法。
getAll(File toFile)	获取所有数据到指定文件(json)
getUsing(K key, V usingValue)	键不存在时,插入 usingValue 并返回,键存在时,可能返回当前值或覆盖（取决于实现）
getOrDefault(Object key, V defaultValue)	根据键获取值，若键不存在则返回默认值
acquireUsing(K key, V usingValue)	键不存在时,插入 usingValue 并返回,键存在时,直接返回当前值
acquireContext(K key, V usingValue)
file()	获取数据持久化文件
name()	获取数据持久化文件路径
toIdentityString()	获取数据库信息字符串
longSize()	获取数据库存储数据数量
offHeapMemoryUsed()	获取未使用堆内存
keyClass()	获取键的Class
keyType()	获取键的数据类型
valueClass()	获取值的Class
valueType()	获取值的数据类型
queryContext(K key) queryContext(Data<K> key) queryContext(BytesStore<?, ?> keyBytes, long offset, long size)	用于获取指定键的查询上下文（ExternalMapQueryContext）的方法，支持细粒度锁控制和条件操作。
segmentContext(int segmentIndex)	用于访问或操作特定分段的上下文方法，通常用于高级性能优化或自定义分段管理
segments()	用于获取分段数量
forEachEntryWhile(Predicate<? super E> predicate)	用于在满足条件时对每个条目执行操作，支持提前终止遍历。
forEachEntry(Consumer<? super E> action)	用于在满足条件时对每个条目执行操作，支持提前终止遍历。
close()	用于释放 ChronicleMap 占用的资源（如内存或文件句柄），持久化存储时需显式调用以确保数据写入磁盘。
isOpen()	判断数据库是否开启

可参考文档

github