| Elektra 0.11.0

How-To: Java kdb

# Introduction

When programming in Java it is possible to access the key database, changing values of existing keys or adding new ones and a few other things. It is also possible to write plugins for Elektra in Java but we will focus on using the Java binding in this tutorial.

# First Steps

In order to use `kdb` you need to include the dependency in your project. Here you can find a detailed tutorial on how to do that.

After that you can start loading a `KDB` object as follows:

try (KDB kdb = KDB.open()) {
// code to manipulate keys
} catch (KDBException e) {
e.printStackTrace();
}
kdb
This is the main namespace for the C++ binding and libraries.
Definition backend.hpp:31

Note that `KDB` implements `AutoClosable` which allows `try-with-resouces`.

If an error occurs, detailed information can be obtained from the thrown `KDBException`.

# A word about releasing native resources

There are 3 kinds of native resources having to be cleaned up properly to prevent memory leaks: `KeySet`, `Key` and `KDB` or rather their backing native key set, key or KDB session.

Fortunately the only resource you are strictly required to release is `KDB` via either `KDB::close` or `try-with-resouces`. For `KeySet` and `Key` the garbage collector cleans them up automatically using a `Cleaner`

# Fetching keys

First let's retrieve a key which is already part of the key database. The first thing we need to do is to create a `KeySet` your keys are going to be stored in:

var keySet = KeySet.create();

Now we load all keys located below a specific parent key:

var parentKey = Key.create("user:/");
kdb.get(keySet, parentKey);

Note on `KDB::get`: The resulting key set may contain more keys than requested.

Now we can simply fetch the desired key's value as follows:

String value = keySet.lookup("user:/my/presaved/key").map(Key::getString).orElseThrow();

So for example if you had executed the command below via shell, before starting the application:

kdb set user:/my/presaved/key it_works!

`value` would equals `it_works!`.

# Saving Keys

Next let's save a new key to the key database. Again, first we need to create an empty `KeySet`. We also need to fetch all keys for the namespace before we will be able to save a new key.

var keyNamespace = Key.create("user:/"); // create key representing the namespace to fetch
var keySet = kdb.get(keyNamespace); // fetch all keys for the namespace into a new key set
var keyToStore = Key.create("user:/somekey", "myValue"); // create key with value to store
keySet.append(keyToStore);
kdb.set(keySet, keyToStore);

If you try to save a key without fetching it beforehand, a `KDBException` will be thrown, telling you to call get before set.

The user namespace is accessible without special rights, but if you try to write to system you will need to have root privileges. Take a look at TESTING.md to see how to access the system namespace as non-root user. This should only be done in testing environments though as it is not intended for productive systems.

# Examples

## Traversing Keys in a <tt>KeySet</tt>

First we create a new `KDB` handle and fetch all keys for the desired namespace, in this example the whole `user` namespace. Since all keys are put in the passed `keySet` variable we can then iterate through it. The `at(int)` method returns a new `Key` object for the native key with the corresponding position within the `keySet`.

var keyNamespace = Key.create("user:/"); // select a namespace from which all keys should be fetched
try (KDB kdb = KDB.open()) {
var keySet = kdb.get(keyNamespace); // fetch all keys into a new key set
for (int i = 0; i < keySet.length(); i++) { // traverse the set
var currentKey = keySet.at(i);
System.out.println(String.format("%s: %s",
currentKey.getName(), // fetch the key's name
currentKey.getString())); // fetch the key's value
}
} catch (KDBException e) {
e.printStackTrace();
}

`KeySet` also provides an iterator implementation:

var keyNamespace = Key.create("user:/"); // select a namespace from which all keys should be fetched
try (KDB kdb = KDB.open()) {
var iter = kdb.get(keyNamespace).iterator(); // fetch all keys into a new key set
while(iter.hasNext()) { // traverse the set
var currentKey = iter.next();
System.out.println(String.format("%s: %s",
currentKey.getName(), // fetch the key's name
currentKey.getString())); // fetch the key's value
}
} catch (KDBException e) {
e.printStackTrace();
}

Of course, alternatively a for each loop can be used:

var keyNamespace = Key.create("user:/"); // select a namespace from which all keys should be fetched
try (KDB kdb = KDB.open()) {
var keySet = kdb.get(keyNamespace); // fetch all keys into a new key set
for (var currentKey : keySet) { // traverse the set
System.out.println(String.format("%s: %s",
currentKey.getName(), // fetch the key's name
currentKey.getString())); // fetch the key's value
}
} catch (KDBException e) {
e.printStackTrace();
}

Another way to traverse is to use the Stream API which was introduced with Java 8:

var keyNamespace = Key.create("user:/"); // select a namespace from which all keys should be fetched
try (KDB kdb = KDB.open()) {
var keySet = kdb.get(keyNamespace); // fetch all keys into a new key set
keySet.forEach(key -> System.out.printf("%s: %s%n", key.getName(), key.getString())); // directly format-print all key value pairs using foreach
// or
keySet.stream().map(key -> String.format("%s: %s", key.getName(), key.getString())).forEach(System.out::println); // map the key value paris to the desired format first and then print them using foreach and a function reference
} catch (KDBException e) {
e.printStackTrace();
}

As the `KeySet` implements the `SortedSet<Key>` interface, all its methods can be used for (not only) a traversal:

var keyNamespace = Key.create("user:/"); // select a namespace from which all keys should be fetched
try (KDB kdb = KDB.open()) {
var keySet = kdb.get(keyNamespace); // fetch all keys into a new key set
keySet.subSet(Key.create("user:/b"), Key.create("user:/k")) // only select the keys starting with "user:/a" through "user:/k" (excluded).
.forEach(key -> System.out.printf("%s: %s%n", key.getName(), key.getString())); // directly format-print all key value pairs using foreach
} catch (KDBException e) {
e.printStackTrace();
}

Another way to traverse is to use the Stream API which was introduced with Java 8:

var keyNamespace = Key.create("user:/"); // select a namespace from which all keys should be fetched
try (KDB kdb = KDB.open()) {
var keySet = kdb.get(keyNamespace); // fetch all keys into a new key set
keySet.forEach(key -> System.out.printf("%s: %s%n", key.getName(), key.getString())); // directly format-print all key value pairs using foreach
// or
keySet.stream().map(key -> String.format("%s: %s", key.getName(), key.getString())).forEach(System.out::println); // map the key value paris to the desired format first and then print them using foreach and a function reference
} catch (KDBException e) {
e.printStackTrace();
}

## Read Multiple Keys From KDB

This example shows how to read multiple keys. It provides comments for further clarification. Further information can be found here.

# Java Plugin Tutorial

For the tutorial on how to write java plugins, please check out this page.