SDK
SDK Jvm v1.x
2
JvmJvm v1.x

Getting Started #

In this tutorial you will learn how to install and use the JVM SDK for Kuzzle. This page shows examples of scripts that store documents in Kuzzle, and of scripts that subcribe to real-time notifications for each new document created.

Before proceeding, please make sure your system meets the following requirements:

Having trouble? Get in touch with us on Discord!

Installation #

You can find the SDK JARs directly on Maven. Download and add them to your classpath.

This SDK has 2 jar files that you can use:

  • sdk-jvm-<version>.jar: this is the fat jar version, containing the SDK and all its dependencies.
  • sdk-jvm-<version>-without-dependencies.jar: this is the thin jar version of the SDK, without any dependencies included in it.

Depending on your project, you might need one or the other version of the SDK: if you already use some of the dependencies needed by the SDK, then you need to use the thin jar version. Otherwise, you may use the fat jar one.

If you are using the fat jar, you might have duplicate dependencies issues in a Kotlin Android Studio project. Add the following lines to your build.gradle file:

configurations {
     cleanedAnnotations
     compile.exclude group: 'org.jetbrains'
     compile.exclude group: 'org.jetbrains.kotlin'
 }

If you are using the thin jar, make sure to add the following dependencies:

    implementation("io.ktor:ktor-client-websockets:1.5.2")
    implementation("io.ktor:ktor-client-okhttp:1.5.2")
    implementation("io.ktor:ktor-client-cio:1.5.2")
    implementation("io.ktor:ktor-client-json:1.5.2")
    implementation("io.ktor:ktor-client-gson:1.5.2")
    implementation("io.ktor:ktor-client-serialization:1.5.2")
    implementation("com.google.code.gson:gson:2.8.5")

The following examples are made to be executed without any IDE. If you're using Eclipse, IntelliJ or another Java IDE, you need to add the SDK as a project dependency in your classpath.

Installing for Android projects using gradle #

To build the project, add the following lines:

Maven #

<dependency>
  <groupId>io.kuzzle</groupId>
  <artifactId>sdk-jvm</artifactId>
  <version>1.3.2</version>
  <type>pom</type>
</dependency>

Gradle #

dependencies {
  compile 'io.kuzzle:sdk-jvm:1.3.2'
}

Ivy #

<dependency org='io.kuzzle' name='sdk-jvm' rev='1.3.2'>
  <artifact name='sdk-jvm' ext='pom' ></artifact>
</dependency>

First connection #

Initialize a new Java project, create a GettingStartedFirstConnection.kt file and start by adding the code below:

import io.kuzzle.sdk.*;
import io.kuzzle.sdk.protocol.WebSocket;
fun main() {
  // @start
  // Creates a WebSocket connection.
  // Replace "kuzzle" with
  // your Kuzzle hostname like "localhost"
  val ws = WebSocket("kuzzle")
  // Instantiates a Kuzzle client
  val kuzzle = Kuzzle(ws).apply {
    // Connects to the server.
    connect()
  }
  println("Connected!")
  try {
    // Freshly installed Kuzzle servers are empty: we need to create
    // a new index.
    kuzzle
      .indexController
      .create("nyc-open-data").get()
    println("Index nyc-open-data created!")
    // Creates a collection
    kuzzle
      .collectionController
      .create("nyc-open-data", "yellow-taxi").get()
    println("Collection yellow-taxi created!")
  } catch (e: Exception) {
    e.printStackTrace()
  } finally {
    // Disconnects the SDK
    kuzzle.disconnect()
  }
  // @end
}

If you're not yet familiar with how Kuzzle structures its storage, check our detailed guide

This program initializes the Kuzzle Server storage by creating an index and a collection. Run the program with the following command:

$ kotlinc -classpath ./path/to/the/sdk.jar GettingStartedFirstConnection.kt
$ java -classpath .:./path/to/the/sdk.jar GettingStartedFirstConnection
Connected!
Index nyc-open-data created!
Collection yellow-taxi created!

You now know how to:

  • Instantiate the Kuzzle SDK and connect to a Kuzzle Server using a specific network protocol (here websocket)
  • Create an index
  • Create a collection within an existing index

Create your first document #

Now that you successfully connected to your Kuzzle Server instance, and created an index and a collection, it's time to manipulate documents.

Create a GettingStartedStorage.kt file in the playground and add this code:

import io.kuzzle.sdk.*
import io.kuzzle.sdk.protocol.WebSocket
fun main() {
  // @start
  // Creates a WebSocket connection.
  // Replace "kuzzle" with
  // your Kuzzle host name (e.g. "localhost")
  val ws = WebSocket("kuzzle")
  // Instantiates a Kuzzle client
  val kuzzle = Kuzzle(ws).apply {
    // Connects to the server.
    connect()
  }
  println("Connected!")
  try {
    // New document content
    val content: Map<String, Any?> = HashMap<String, Any?>().apply {
      put("name", "John")
      put("birthday", "1995-11-27")
      put("license", "B")
    }
    // Stores the document in the "yellow-taxi" collection.
    kuzzle
      .documentController
      .create("nyc-open-data", "yellow-taxi", content).get()
    println("New document added to the yellow-taxi collection!")
  } catch (e: Exception) {
    e.printStackTrace()
  } finally {
    // Disconnects the SDK.
    kuzzle.disconnect()
  }
  // @end
}

As you did before, build and run your program:

$ kotlinc -classpath ./path/to/the/sdk.jar  GettingStartedStorage.kt
$ java -classpath .:./path/to/the/sdk.jar GettingStartedStorage
Connected!
New document added to the yellow-taxi collection!

Many other actions are available to manipulate stored documents. You can check the exhaustive list in the Document Controller documentation.

Now you know how to:

  • Store documents in a Kuzzle Server, and access to those

Subscribe to realtime document notifications (pub/sub) #

Time to use Kuzzle's realtime capabilities. Create a new file GettingStartedRealtime.kt with the following code:

import io.kuzzle.sdk.*
import io.kuzzle.sdk.protocol.WebSocket
fun main() {
  // @start
  // Creates a WebSocket connection.
  // Replace "kuzzle" with
  // your Kuzzle hostname like "localhost"
  val ws = WebSocket("kuzzle")
  // Instantiates a Kuzzle client
  val kuzzle = Kuzzle(ws).apply {
    // Connects to the server.
    connect()
  }
  try {
    // Subscribes to notifications for drivers having a "B" driver license.
    val equals: Map<String, Any?> = HashMap<String, Any?>().apply {
      put("license", "B")
    }
    val filters: Map<String, Any> = HashMap<String, Any>().apply {
      put("equals", equals)
    }
    println("Connected!")
    // Sends the subscription
    kuzzle
      .realtimeController
      .subscribe("nyc-open-data", "yellow-taxi", filters) { notification ->
        val content: Map<String, Any?> = notification.result as Map<String, Any?>
        println("New created document notification: " + content)  
        /*
          {
          _source={
            birthday=1995-11-27,
            license=B,
            name=John,
            _kuzzle_info={
              createdAt=1605694059151,author=-1
              }
            },
            _id=9PDS2nUBeGNr7nwl8j2Q,
            _version=1
          }
        */
          }.get()
      println("Successfully subscribed!")
    // Writes a new document. This triggers a notification
    // sent to our subscription.
    val content: Map<String, Any?> = HashMap<String, Any?>().apply {
      put("name", "John")
      put("birthday", "1995-11-27")
      put("license", "B")
    }
      kuzzle
        .documentController
        .create("nyc-open-data", "yellow-taxi", content).get()
      println("New document added to the yellow-taxi collection!")
  } catch (e: Exception) {
    e.printStackTrace()
  } finally {
    // Disconnects the SDK.
    kuzzle.disconnect()
  }
  // @end
}

This program subscribes to changes made to documents with a license field set to B, within the yellow-taxi collection. Whenever a document matching the provided filters changes, a new notification is received from Kuzzle.

Build and run your program:

$ kotlinc -classpath ./path/to/the/sdk.jar GettingStartedRealtime.kt
$ java -classpath .:./path/to/the/sdk.jar GettingStartedRealtime
Connected!
Successfully subscribing!
New document added to yellow-taxi collection!
New created document notification:

{
  _source={
    birthday=1995-11-27,
    license=B,
    name=John,
    _kuzzle_info={
      createdAt=1605694059151,author=-1
      }
    },
    _id=9PDS2nUBeGNr7nwl8j2Q,
    _version=1
  }

You should see the document content as a Map.

Now, you know how to:

  • Create realtime filters
  • Subscribe to notifications

Where do we go from here? #

Now that you're more familiar with the JVM SDK, you can dive even deeper to learn how to leverage its full capabilities:

Edit this page on Github(opens new window)