\subsection*{Introduction}

When programming in Java it is possible to access the kdb 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.

\subsection*{First Steps}

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

After that you can start loading an {\ttfamily K\+DB} object as follows\+: 
\begin{DoxyCode}
Key key = Key.create(\textcolor{stringliteral}{"user/kdbsession/javabinding"});
\textcolor{keywordflow}{try} (KDB \hyperlink{namespacekdb}{kdb} = KDB.open(key)) \{
    \textcolor{comment}{//Your code to manipulate keys}
\} \textcolor{keywordflow}{catch} (KDB.KDBException e) \{
    e.printStackTrace();
\}
\end{DoxyCode}


Note that K\+DB implements {\ttfamily Auto\+Closable} which allows \href{https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html}{\tt try-\/with-\/resouces}.

You can also pass a {\ttfamily Key} object with an empty string on the first line. The passed key ({\ttfamily user/kdbsession/javabinding} in this case) is being used for the session and stores warnings and error informations.

\subsection*{Fetching keys}

First I will show how to get a key which was already saved in the database. The first thing we need to do is to create a {\ttfamily Key\+Set} in which our key(s) will be loaded. 
\begin{DoxyCode}
KeySet \textcolor{keyword}{set} = KeySet.create();
\end{DoxyCode}


Now we load all keys and provide a parent key from which all keys below will be loaded 
\begin{DoxyCode}
\hyperlink{namespacekdb}{kdb}.get(\textcolor{keyword}{set}, Key.create(\textcolor{stringliteral}{"user"}));
\end{DoxyCode}
 Now we can simply fetch the desired key\textquotesingle{}s value as follows\+: 
\begin{DoxyCode}
String str = \textcolor{keyword}{set}.lookup(\textcolor{stringliteral}{"user/my/presaved/key"}).getString()
\end{DoxyCode}
 So for example if you have executed before the application starts {\ttfamily kdb set user/my/test it\+\_\+works!}, the method call {\ttfamily set.\+lookup(\char`\"{}user/my/test\char`\"{}).get\+String()} would return {\ttfamily it\+\_\+works!}.

\subsection*{Saving Keys}

Next I will show how to save a new key into the database. First we need need to create an empty {\ttfamily Key\+Set} again. We also {\bfseries need to fetch} all keys for the namespace before we will be able to save a new key.


\begin{DoxyCode}
KeySet \textcolor{keyword}{set} = KeySet.create();
Key \textcolor{keyword}{namespace }= Key.create("user");
\hyperlink{namespacekdb}{kdb}.get(\textcolor{keyword}{set}, \textcolor{keyword}{namespace});    \textcolor{comment}{//Fetch all keys for the namespace}
\textcolor{keyword}{set}.append(Key.create(\textcolor{stringliteral}{"user/somekey"}, \textcolor{stringliteral}{"myValue"}));
\hyperlink{namespacekdb}{kdb}.set(\textcolor{keyword}{set}, key);
\end{DoxyCode}


If you try to save a key without fetching it beforehand, a {\ttfamily K\+D\+B\+Exception} will be thrown, telling you to call get before set.

The {\itshape user} namespace is accessible without special rights, but if you try to write to {\itshape system} you will need to have root privileges. Check \hyperlink{doc_TESTING_md}{this} to see how to run as non-\/root user. This should only be done in testing environments though as it is not intended for productive systems.

\subsection*{Examples}

\subsubsection*{Traversing Keys in a {\ttfamily Key\+Set}}


\begin{DoxyCode}
Key key = Key.create(\textcolor{stringliteral}{"user/errors"});
\textcolor{keywordflow}{try} (KDB \hyperlink{namespacekdb}{kdb} = KDB.open(key)) \{
    KeySet \textcolor{keyword}{set} = KeySet.create();
    Key \textcolor{keyword}{namespace }= Key.create("user");       \textcolor{comment}{//Select a namespace from which all keys should be fetched}
    \hyperlink{namespacekdb}{kdb}.get(\textcolor{keyword}{set}, \textcolor{keyword}{namespace});                  \textcolor{comment}{//Fetch all keys into the set object}
    \textcolor{keywordflow}{for} (\textcolor{keywordtype}{int} i = 0; i < \textcolor{keyword}{set}.length(); i++) \{  \textcolor{comment}{//Traverse the set}
        String keyAndValue = String.format(\textcolor{stringliteral}{"%s: %s"},
                \textcolor{keyword}{set}.at(i).getName(),          \textcolor{comment}{//Fetch the key's name}
                \textcolor{keyword}{set}.at(i).getString());       \textcolor{comment}{//Fetch the key's value}
        System.out.println(keyAndValue);
    \}
\} \textcolor{keywordflow}{catch} (KDB.KDBException e) \{
    e.printStackTrace();
\}
\end{DoxyCode}


First we create a new {\ttfamily K\+DB} object and fetch all keys for the desired namespace, in this example the {\ttfamily user} namespace. Since it saves all keys in our passed {\ttfamily set} variable we can then iterate through it by a simple for loop. The {\ttfamily at(int)} method gives us the key on the corresponding position which we will print out in this example. 