The Java SDK for KVStore.io is on GitHub.com

Ready for a quick tour of the Java SDK for KVStore.io?

TL; DR You will learn to interact with KVStore.io, storing and retrieving data, by writing a very few lines of Java code thanks to the provided SDK.

Disclaimer

The current version of the KVStore.io Java SDK library is Release Candidate (RC). Please, refer to the GitHub repository to report issues (see the links at the bottom of this page)

Introduction

KVStore.io is a simple storage service based on a “key/value” data modeling: you can easily organize data in dictionaries, where your keys map to values, both of which are simple strings. Furthermore, you may create one or more dictionaries that are called collections.

Although very simple, this approach is very flexible and powerful, because it does not imply any specific data format or use-case scenario. You could use it to store simple sequences of characters read from a hardware sensor or complex JSON structures generated from a micro-service.

KVStore is data agnostic and so its interfaces are (RESTful API/SDK). For further details, see the documentation.

Obtain your secret token

To start using KVStore.io, you need to signup for the service and to obtain your secret token (API key). Don’t worry, the “forever free” plan is more than enough to start learning or for simple use cases.

Once logged, you locate your secret token in your private home page, like in the image below:

Create your Java program

Let’s start by getting the KVStore Java SDK. Of course, the easiest way to install it is by using a build automation tool, like Maven or Gradle. Otherwise, you will need to download the jar and later include it in your classpath while compiling and executing your code (eg. javac -cp <path_to_sdk/sdk-java-1.0.0-VERSION.jar> Main.java).

For Maven, add this dependency to your pom.xml:

<dependency>
    <groupId>io.kvstore</groupId>
    <artifactId>sdk-java</artifactId>
    <version>1.0.0-RC</version>
</dependency>

For Gradle, add the following to your build.gradle:

compile group: 'io.kvstore', name: 'sdk-java', version: '1.0.0-RC'

For the sake of simplicity, let’s create a simple Java application from scratch using Maven. Open your terminal and paste this command:

mvn archetype:generate -DgroupId=io.kvstore.demo -DartifactId=sdk-demo -Dversion=1.0-SNAPSHOT -DarchetypeArtifactId=maven-archetype-quickstart

It will create a folder “sdk-demo” containing an empty app just after you will confirm the operation by typing “Y”.

$ mvn archetype:generate -DgroupId=io.kvstore.demo -DartifactId=sdk-demo -Dversion=1.0-SNAPSHOT -DarchetypeArtifactId=maven-archetype-quickstart -q
Confirm properties configuration:
groupId: io.kvstore.demo
artifactId: sdk-demo
version: 1.0-SNAPSHOT
package: io.kvstore.demo
 Y: : Y

Now jump into the new folder “sdk-demo”, edit the pom.xml file using your preferred editor, and paste the KVStore SDK dependency just between the <dependencies> tag.

Your final pom.xml should look like:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>io.kvstore.demo</groupId>
  <artifactId>sdk-demo</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>sdk-demo</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>io.kvstore</groupId>
      <artifactId>sdk-java</artifactId>
      <version>1.0.0-RC</version>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

Edit now the file src/main/java/io/kvstore/demo/App.java and paste (please, remember to replace the PUT_YOUR_API_KEY with your own secret token):

package io.kvstore.demo;
import io.kvstore.sdk.KVStore;
import io.kvstore.sdk.clients.CollectionsClient;
import io.kvstore.sdk.clients.ItemsClient;
import io.kvstore.sdk.clients.KVStoreClient;
import io.kvstore.sdk.exceptions.KVStoreException;
public class App {
public static void main(String[] args) {
        KVStoreClient kvStore = KVStore.instance("PUT_YOUR_API_KEY");
CollectionsClient collectionsClient = kvStore.collectionsClient();
collectionsClient.create("test");
        ItemsClient itemsClient = kvStore.itemsClient();
itemsClient.put("test", "mykey", "my value!");
        ItemsClient.ItemValue item = itemsClient.get("test", "mykey");
System.out.println(item);
}
}

The code shows the basic operations:

1. instance the client by calling the static instance method and assign to the kvStore variable (KVStoreClient kvStore = KVStore.instance("PUT_YOUR_API_KEY"))
2. obtain the collections handler (CollectionsClient collectionsClient = kvStore.collectionsClient())
3. create the “test” collection (collectionsClient.create("test"))
4. obtain the items handler (ItemsClient itemsClient = kvStore.itemsClient())
5. store “my value!” with the key “mykey” (itemsClient.put("test", "mykey", "my value!"))
6. read back its value and assign to the item variable (ItemsClient.ItemValue item = itemsClient.get("test", "mykey"))
7. print the value of the item variable to the console

Now we’re very close to the finish line! We just need to compile the code:

$ mvn compile

and then execute it:

$ mvn exec:java -Dexec.mainClass="io.kvstore.demo.App" -q
Item(value=my value!, created_at=Mon Jul 06 19:29:15 CEST 2020, updated_at=Mon Jul 06 19:29:15 CEST 2020)

Yeah, as expected we can see the output of our System.out :-)

Conclusions

In this short tutorial, we have installed the Java SDK thanks to Maven and created a sample app connecting and leveraging some of the KVStore.io features, such as creating a collection, storing and then retrieving some data.

Useful links:

• The official documentation on the main website,
• GitHub repository of the Java SDK (report issues here)