SDK
SDK Java v1.x
1
JavaJava v1.x

You are currently looking at the documentation of a previous version of Kuzzle. We strongly recommend that you use the latest version. You can also use the version selector in the top menu.

This SDK has been deprecated because of stability issues. It is not advised to use it in a production environment.

Getting Started #

In this tutorial you will learn how to install the Kuzzle Java SDK. 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 our download plateform. Download and add it to your classpath.

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.

First connection #

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

import io.kuzzle.sdk.*;
public class gettingstartedfirstconnection {
  private static Kuzzle kuzzle;
  public static void main(String[] args) {
    // Creates a WebSocket connection.
    // Replace "kuzzle" with
    // your Kuzzle hostname like "localhost"
    WebSocket ws = new WebSocket("kuzzle");
    // Instantiates a Kuzzle client
    Kuzzle kuzzle = new Kuzzle(ws, null);
    // Connects to the server.
    try {
      kuzzle.connect();
      System.out.println("Connected!");
    } catch(KuzzleException e){
      e.printStackTrace();
    }
    // Freshly installed Kuzzle servers are empty: we need to create
    // a new index.
    try {
      kuzzle.getIndex().create("nyc-open-data");
      System.out.println("Index nyc-open-data created!");
    } catch(KuzzleException e){
      e.printStackTrace();
    }
    // Creates a collection
    try {
      kuzzle.getCollection().create("nyc-open-data", "yellow-taxi");
      System.out.println("Collection yellow-taxi created!");
    } catch(KuzzleException e){
      e.printStackTrace();
    }
    // Disconnects the SDK
    kuzzle.disconnect();
  }
}

This program initializes the Kuzzle Server storage by creating a index, and a collection inside it Run the program with the following command:

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

Congratulations, you performed your first connection to Kuzzle Server via a Java program. You now know how to:

  • Instantiate Kuzzle SDK and connect to Kuzzle Server using a specific protocol (here websocket)
  • Create a 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 some data.

Here is how Kuzzle structures its storage space:

  • indexes contain collections
  • collections contain documents Create a gettingstartedstorage.java file in the playground and add this code:
import io.kuzzle.sdk.*;
public class gettingstartedstorage {
  private static Kuzzle kuzzle;
  public static void main(String[] args) {
    // Creates a WebSocket connection.
    // Replace "kuzzle" with
    // your Kuzzle hostname like "localhost"
    WebSocket ws = new WebSocket("kuzzle");
    // Instantiates a Kuzzle client
    Kuzzle kuzzle = new Kuzzle(ws, null);
    // Connects to the server.
    try {
      kuzzle.connect();
      System.out.println("Connected!");
    } catch(KuzzleException e){
      e.printStackTrace();
    }
    // New document content
    String content = "{"
      + "\"name\": \"Sirkis\","
      + "\"birthday\": \"1959-06-22\","
      + "\"license\": \"B\""
      + "}";
    // Stores the document in the "yellow-taxi" collection.
    try {
      kuzzle.getDocument()
        .create( "nyc-open-data", "yellow-taxi", "some-id", content);
      System.out.println("New document added to the yellow-taxi collection!");
    } catch(KuzzleException e){
      e.printStackTrace();
    }
    // Disconnects the SDK.
    kuzzle.disconnect();
  }
}

As you did before, build and run your program:

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

You can perform other actions such as delete, replace or search documents. There are also other ways to interact with Kuzzle like our Admin Console, the Kuzzle HTTP API or by using your own protocol.

Now you know how to:

  • Store documents in a Kuzzle Server, and access those

Subscribe to realtime document notifications (pub/sub) #

Time to use realtime with Kuzzle. Create a new file gettingstartedrealtime.java with the following code:

import io.kuzzle.sdk.*;
public class gettingstartedrealtime {
  private static Kuzzle kuzzle;
  public static void main(String[] args) {
    // Creates a WebSocket connection.
    // Replace "kuzzle" with
    // your Kuzzle hostname like "localhost"
    WebSocket ws = new WebSocket("kuzzle");
    // Instantiates a Kuzzle client
    Kuzzle kuzzle = new Kuzzle(ws, null);
    // Connects to the server.
    try {
      kuzzle.connect();
      System.out.println("Connected!");
    } catch(KuzzleException e){
      e.printStackTrace();
    }
    // Starts an async listener
    NotificationListener listener = new NotificationListener() {
      public void onMessage(NotificationResult notification) {
        String content = notification.getResult().getContent();
        System.out.println("New created document notification: " + content);
      }
    };
    // Subscribes to notifications for drivers having a "B" driver license.
    String filters = new String("{ \"equals\": { \"license\":\"B\" } }");
    try {
      // Sends the subscription
      kuzzle.getRealtime()
        .subscribe( "nyc-open-data", "yellow-taxi", filters, listener);
      System.out.println("Successfully subscribed!");
    } catch(KuzzleException e){
      e.printStackTrace();
    }
    // Writes a new document. This triggers a notification
    // sent to our subscription.
    String content =  "{"
      + "\"name\": \"John\","
      + "\"birthday\": \"1995-11-27\","
      + "\"license\": \"B\""
      + "}";
    try {
      kuzzle.getDocument()
        .create( "nyc-open-data", "yellow-taxi", "", content);
      System.out.println("New document added to the yellow-taxi collection!");
    } catch(KuzzleException e){
      e.printStackTrace();
    }
    // Disconnects the SDK.
    kuzzle.disconnect();
  }
}

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:

$ javac -classpath ./path/to/the/sdk.jar gettingstartedrealtime.java
$ java -classpath .:./path/to/the/sdk.jar gettingstartedrealtime
Connected!
Successfully subscribing!
New document added to yellow-taxi collection!
New created document notification: [Document content as JSON]

You should see document content as a JSON string you could parse with your favorite library.

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 Java SDK, you can dive even deeper to learn how to leverage its full capabilities:

Edit this page on Github(opens new window)