FastKV

中文文档

FastKV is an efficient and reliable key-value storage component written with Java.
It can be used on platforms with JVM environment, such as Android.

1. Features

1. Efficient

   • Binary coding: the size after coding is much smaller than that of text coding such as XML;
   • Incremental update: FastKV records the offset of each key-value relative to the file, updating can be written directly at the right location.
   • By default, data is recorded with mmap . When updating data, it can be written directly to memory without IO blocking.
   • For a value which length is larger than the threshold, it will be written to another file separately, only it's file name will be cached. In that way, it will not slow down other key-value's accessing.

2. Support multiple writing mode

   • In addition to the non-blocking writing mode (with mmap), FastKV also supports synchronous blocking and asynchronous blocking (similar to commit and apply of SharePreferences).

3. Support multiple types

   • Support primitive types such as Boolean / int / float / long / double / string;
   • Support ByteArray (byte []);
   • Support storage objects.
   • Built in encoder with Set (for compatibility with SharePreferences).

4. Easy to use

   • FastKV provides rich API interfaces, including getAll() and putAll() methods, it is convenient to migrate the data of frameworks such as sharepreferences to FastKV.

5. Stable and reliable

   • When FastKV writes data in non-blocking way (mmap), it writes two files one by one, to ensure that at least one file is complete at any time;
   • FastKV checks the integrity of the files when loading, if one file is incomplete, it will be restored with another file which is complte.
   • If mmap API fails, it will be degraded to the normal I/O writing mode; and it will try to restore to mmap mode when reloading.

6. Simple code

   • FastKV is implemented in pure Java and the jar package is less than 40K.

2. Getting Start

2.1 Import

FastKV had been publish to Maven Central:

dependencies {
    implementation 'io.github.billywei01:fastkv:1.0.2'
}

2.2 Initialization

    FastKVConfig.setLogger(FastKVLogger)
    FastKVConfig.setExecutor(ChannelExecutorService(4))

Initialization is optional.
You could set log callback and executor as needed.
It is recommended to pass in your own thread pool to reuse threads.

The log interface provides three levels of callbacks.

    public interface Logger {
        void i(String name, String message);

        void w(String name, Exception e);

        void e(String name, Exception e);
    }

2.3 Read/Write

• Basic case

    FastKV kv = new FastKV.Builder(path, name).build();
    if(!kv.getBoolean("flag")){
        kv.putBoolean("flag" , true);
    }

• Sava custom object

    FastKV.Encoder<?>[] encoders = new FastKV.Encoder[]{LongListEncoder.INSTANCE};
    FastKV kv = new FastKV.Builder(path, name).encoder(encoders).build();
        
    String objectKey = "long_list";
    List<Long> list = new ArrayList<>();
    list.add(100L);
    list.add(200L);
    list.add(300L);
    kv.putObject(objectKey, list, LongListEncoder.INSTANCE);

    List<Long> list2 = kv.getObject("long_list");

In addition to supporting basic types, FastKV also supports writing objects. You only need to pass in the encoder of the object when building FastKV instances.
The encoder is an object that implements FastKV.Encoder.
For example, the implementation of LongListEncoder like this:

public class LongListEncoder implements FastKV.Encoder<List<Long>> {
    public static final LongListEncoder INSTANCE = new LongListEncoder();

    @Override
    public String tag() {
        return "LongList";
    }

    @Override
    public byte[] encode(List<Long> obj) {
        return new PackEncoder().putLongList(0, obj).getBytes();
    }

    @Override
    public List<Long> decode(byte[] bytes, int offset, int length) {
        PackDecoder decoder = PackDecoder.newInstance(bytes, offset, length);
        List<Long> list = decoder.getLongList(0);
        decoder.recycle();
        return (list != null) ? list : new ArrayList<>();
    }
}

Encoding objects needs serialization/deserialization.
Here recommend my serialization project: https://github.com/BillyWei01/Packable

2.4 For Android

Comparing with common usage, Android platform has SharePreferences API and support Kotlin.
See: Android Case

3. Benchmark

• Data source: Collecting part of the key-value data of SharePreferences in the app (with confusion) , 400+ key-values.
  Because some key values are accessed more and others accessed less in normally, I make a normally distributed sequence to test the accessing.

• Comparison component: Sharepreferences/DataStore/MMKV

• Device: Huawei Horor 20s

Result:

• SharePreferences use the apply mode. When use commit mode, used more than 5s, much slower.
• DataStore writes data very slow.
• MMKV read slower then SharePreferences/DataStore，but much faster in writing.
• FastKV is fastest both in writing or reading.

License

See the LICENSE file for license rights and limitations.