B4A Library [B4X] KVS - KeyValueStore library

A key / value persistent store. The data is serialized using B4XSerializator and is stored in an internal database. The database can be shared between B4A, B4i and B4J.

Using KVS is similar to using a Map. You initialize it once and then you can put or get items with Put, Get or GetDefault methods.

The supported types of objects are:

Lists, Maps, Strings, primitives (numbers), user defined types and arrays (only arrays of bytes and arrays of objects are supported).
Including combinations of these types (a list that holds maps for example).
Custom types should be declared in the main module or in B4XMainPage.
Bitmaps are supported with PutBitmap / GetBitmap methods.

Adding encryption:

Spoiler: Encryption

Encryption is also supported but is not enabled by default as it requires some configuration:

1. Add KVS_ENCRYPTION to the build configuration (Ctrl + B):

2.
B4A: Add reference to B4XEncryption.
B4i: Add reference to iEncryption
B4J:
Add reference to jB4XEncryption
Download bouncycastle: https://www.bouncycastle.org/download/bcprov-jdk15on-154.jar and put it in the additional libraries folder.
Add to main module:

#AdditionalJar: bcprov-jdk15on-154

3. Use PutEncrypted / GetEncrypted

Usage example:

xui.SetDataFolder("kvs")
    kvs.Initialize(xui.DefaultFolder, "kvs.dat")
    kvs.Put("time", DateTime.Now)

    'fetch this value
    Log(DateTime.Time(kvs.Get("time")))
    Log(kvs.Get("doesn't exist"))
    Log(kvs.GetDefault("doesn't exist", 10))
    'put a Bitmap
    kvs.PutBitmap("bitmap1", xui.LoadBitmap(File.DirAssets, "smiley.gif"))
    'fetch a bitmap
    ImageView1.SetBitmap(kvs.GetBitmap("bitmap1"))
    'remove the bitmap from the store
    kvs.Remove("bitmap1")
    'put an array with two custom types
    kvs.Put("2 custom types", Array(CreateCustomType(1, "one"), CreateCustomType(2, "two")))
    'get them
    Dim mytypes() As Object = kvs.Get("2 custom types") 'the array type must be object or bytes

This library is named KeyValueStore. There is an older library named KeyValueStore2. Don't confuse between the two. It is recommended to use this one.
It is an internal library now.

Updates

v2.31 - New Vacuum method. This method frees unused space from the database file. It can be used after doing large deletes to free space.

 

[DonManfred]

Is it a Internal library?

I am asking because i do have KeyValueStore2.jar/xml in my Internal Libs folder....

 

[Erel]

It will be an internal library in the future.
There is indeed some confusion between the two B4A libraries.

Use KeyValueStore. This is the new library.
Don't use KeyvalueStore2. This is the old library.

 

[Vikjh]

What maximum bitmap size can be stored?

 

[Mahares]

What maximum bitmap size can be stored?

Since KeyValueStore is essentially based on a SQLite database, and a bitmap file is stored as a blob and SQLite has theoretically an absolute maximum blob size of 2GB I am assuming your answer will be 2 GB. In other words it is huge. If someone comes up with an answer that makes more sense, I will delete this post in order not to confuse the members.

 

[Erel]

1. Bitmap size = size of the compressed image.
2. On old Android devices there is a limit of 1mb. The limit on newer Android devices is 2mb.
3. There is no similar limit in B4J or B4i.

 

[Patrick Clark]

It will be an internal library in the future.
There is indeed some confusion between the two B4A libraries.

Use KeyValueStore. This is the new library.
Don't use KeyvalueStore2. This is the old library.

Can I be clear? I should add this library to Additional Libraries and then load KeyValueStore in the IDE.

Thanks

 

[DonManfred]

Can I be clear? I should add this library to Additional Libraries and then load KeyValueStore in the IDE.

Correct.

Regarding the Library in #1 you should add it to the Additional Library folder, refresh the libraries in the IDE and mark the Library.

Erels answer was because i had an old Library somewhere and he told me not to use it.

 

[swChef]

Why not name it KVSX/KeyValueStoreX ?

 

[Erel]

Changing the name right now will make things more confusing. In the next version of B4A there will be a deprecation message in KeyValueStore2.

 

[Patrick Clark]

Is the database from KVS2 fully compatible with this KVS?

 

[Erel]

Yes.

 

[Martin Larsen]

Use KeyValueStore. This is the new library.
Don't use KeyvalueStore2. This is the old library.

Why is the title of this thread called "KVS2 - KeyValueStore2"? It is a bit confusing when you say "Don't use KeyvalueStore2"

 

[Erel]

There was a mistake. This is a new package for KeyValueStore2.

The important thing is:

"This library is named KeyValueStore. There is an older library named KeyValueStore2. Don't confuse between the two. It is recommended to use this one. "

 

[Bob Spielen]

Hi all, were is the recommended place to initialize (configure) kvs in B4XPages. Tks in advance

 

[Erel]

You can do it in the Initialize method of B4XMainPage.

If your app can start in the background (push notifications, StartAtBoot...) then it makes sense to do it in the starter service.

 

[Bob Spielen]

You can ......

Thanks a lot for the reply! Yes in the starter service because I have a sort of "wakeup service".....

 

[fbritop]

Yes.

Not completely. If I list all keys from older version, in the new version they are all lowercaps, buy my keys in KVS2 where case sensitive

 

[Erel]

The keys are not lowercased. You can test it with this code:

Dim kvs As KeyValueStore
kvs.Initialize(File.DirInternal, "1.dat")
kvs.Put("Aaa", "Vvv")
Log(kvs.ListKeys)

 

[a6000000]

Against confusion

from: https://www.b4x.com/android/forum/threads/b4x-kvs2-keyvaluestore2-library.120234/

" This library is named KeyValueStore. There is an older library named KeyValueStore2. Don't confuse between the two. It is recommended to use this one. "

Against confusion: Maybe it would be helpful to add the new library KeyValueStore ,
with the same content as a new library
KeyValueStore3 == KeyValueStore
to be published