From 51ad4e9240bb831ac34183b9ede9635842c5e911 Mon Sep 17 00:00:00 2001 From: Yoann-Abbes <44844010+Yoann-Abbes@users.noreply.github.com> Date: Tue, 1 Dec 2020 11:39:08 +0100 Subject: [PATCH 1/4] Add Java and Kotlin Getting started (#23) What does this PR do ? Add Java and Kotling Getting Started Other changes Fix documentation (Bulk, and SearchResult next) Fix collection:create Update document:search signature Fix token expired --- .ci/doc/templates/empty.tpl.kt | 1 + doc/1/controllers/bulk/index.md | 8 + doc/1/controllers/document/search/index.md | 19 +- .../core-classes/search-result/next/index.md | 3 +- .../next/snippets/fromsize-java.java | 2 +- .../next/snippets/fromsize-kotlin.kt | 4 +- .../next/snippets/scroll-java.java | 2 +- .../next/snippets/scroll-kotlin.kt | 4 +- doc/1/getting-started/index.md | 6 + doc/1/getting-started/java/index.md | 168 ++++++++++++++++++ .../java/snippets/document-java.java | 45 +++++ .../java/snippets/document-java.test.yml | 9 + .../java/snippets/firstconnection-java.java | 47 +++++ .../snippets/firstconnection-java.test.yml | 10 ++ .../java/snippets/realtime-java.java | 77 ++++++++ .../java/snippets/realtime-java.test.yml | 10 ++ doc/1/getting-started/kotlin/index.md | 167 +++++++++++++++++ .../kotlin/snippets/document-kotlin.kt | 38 ++++ .../kotlin/snippets/document-kotlin.test.yml | 9 + .../kotlin/snippets/firstconnection-kotlin.kt | 38 ++++ .../snippets/firstconnection-kotlin.test.yml | 10 ++ .../kotlin/snippets/realtime-kotlin.kt | 69 +++++++ .../kotlin/snippets/realtime-kotlin.test.yml | 10 ++ src/main/kotlin/io/kuzzle/sdk/Kuzzle.kt | 3 +- .../sdk/controllers/CollectionController.kt | 3 +- .../sdk/controllers/DocumentController.kt | 14 +- .../io/kuzzle/sdk/coreClasses/SearchResult.kt | 2 +- 27 files changed, 755 insertions(+), 23 deletions(-) create mode 100644 .ci/doc/templates/empty.tpl.kt create mode 100644 doc/1/controllers/bulk/index.md create mode 100644 doc/1/getting-started/index.md create mode 100644 doc/1/getting-started/java/index.md create mode 100644 doc/1/getting-started/java/snippets/document-java.java create mode 100644 doc/1/getting-started/java/snippets/document-java.test.yml create mode 100644 doc/1/getting-started/java/snippets/firstconnection-java.java create mode 100644 doc/1/getting-started/java/snippets/firstconnection-java.test.yml create mode 100644 doc/1/getting-started/java/snippets/realtime-java.java create mode 100644 doc/1/getting-started/java/snippets/realtime-java.test.yml create mode 100644 doc/1/getting-started/kotlin/index.md create mode 100644 doc/1/getting-started/kotlin/snippets/document-kotlin.kt create mode 100644 doc/1/getting-started/kotlin/snippets/document-kotlin.test.yml create mode 100644 doc/1/getting-started/kotlin/snippets/firstconnection-kotlin.kt create mode 100644 doc/1/getting-started/kotlin/snippets/firstconnection-kotlin.test.yml create mode 100644 doc/1/getting-started/kotlin/snippets/realtime-kotlin.kt create mode 100644 doc/1/getting-started/kotlin/snippets/realtime-kotlin.test.yml diff --git a/.ci/doc/templates/empty.tpl.kt b/.ci/doc/templates/empty.tpl.kt new file mode 100644 index 00000000..f6c250ed --- /dev/null +++ b/.ci/doc/templates/empty.tpl.kt @@ -0,0 +1 @@ +[snippet-code] \ No newline at end of file diff --git a/doc/1/controllers/bulk/index.md b/doc/1/controllers/bulk/index.md new file mode 100644 index 00000000..4dbb61c5 --- /dev/null +++ b/doc/1/controllers/bulk/index.md @@ -0,0 +1,8 @@ +--- +code: true +type: branch +title: Bulk +description: Bulk Controller +--- + +# Bulk Controller diff --git a/doc/1/controllers/document/search/index.md b/doc/1/controllers/document/search/index.md index f745d966..f0c7acb4 100644 --- a/doc/1/controllers/document/search/index.md +++ b/doc/1/controllers/document/search/index.md @@ -39,28 +39,27 @@ You can restrict the scroll session maximum duration under the `services.storage public CompletableFuture search( String index, String collection, - ConcurrentHashMap searchQuery, - String scroll, - Integer from, - Integer size) throws NotConnectedException, InternalException + ConcurrentHashMap searchQuery) throws NotConnectedException, InternalException public CompletableFuture search( String index, String collection, ConcurrentHashMap searchQuery, - String scroll, - Integer from) throws NotConnectedException, InternalException + String scroll) throws NotConnectedException, InternalException public CompletableFuture search( String index, String collection, ConcurrentHashMap searchQuery, - String scroll) throws NotConnectedException, InternalException + String scroll, + Integer size) throws NotConnectedException, InternalException public CompletableFuture search( String index, String collection, - ConcurrentHashMap searchQuery) + ConcurrentHashMap searchQuery + Integer size, + Integer from) throws NotConnectedException, InternalException ``` @@ -102,8 +101,8 @@ Returns a [SearchResult](/sdk/jvm/1/core-classes/search-result) object. collection: String, searchQuery: ConcurrentHashMap, scroll: String? = null, - from: Int = 0, - size: Int? = null): CompletableFuture + size: Int? = null, + from: Int = 0): CompletableFuture ``` | Arguments | Type | Description | diff --git a/doc/1/core-classes/search-result/next/index.md b/doc/1/core-classes/search-result/next/index.md index 3bb55140..ccdd9b9b 100644 --- a/doc/1/core-classes/search-result/next/index.md +++ b/doc/1/core-classes/search-result/next/index.md @@ -75,7 +75,6 @@ Above that limit, any call to `next` throws an Exception. <<< ./snippets/fromsize-java.java - ::: ::: tab Kotlin @@ -143,4 +142,4 @@ Above that limit, any call to `next` throws an Exception. <<< ./snippets/fromsize-kotlin.kt ::: -:::. +:::: diff --git a/doc/1/core-classes/search-result/next/snippets/fromsize-java.java b/doc/1/core-classes/search-result/next/snippets/fromsize-java.java index 576dbcc4..ad29ead2 100644 --- a/doc/1/core-classes/search-result/next/snippets/fromsize-java.java +++ b/doc/1/core-classes/search-result/next/snippets/fromsize-java.java @@ -8,7 +8,7 @@ SearchResult results = kuzzle.getDocumentController().search( "nyc-open-data", "yellow-taxi", - searchQuery, null, 1, 5).get(); + searchQuery, 1, 5).get(); // Fetch the matched items by advancing through the result pages ArrayList> matched = new ArrayList<>(); diff --git a/doc/1/core-classes/search-result/next/snippets/fromsize-kotlin.kt b/doc/1/core-classes/search-result/next/snippets/fromsize-kotlin.kt index 1b658b84..9caa8782 100644 --- a/doc/1/core-classes/search-result/next/snippets/fromsize-kotlin.kt +++ b/doc/1/core-classes/search-result/next/snippets/fromsize-kotlin.kt @@ -14,8 +14,8 @@ ConcurrentHashMap().apply { } var result: SearchResult? = kuzzle -.documentController -.search("nyc-open-data", "yellow-taxi", searchQuery, null, 1, 5).get(); + .documentController + .search("nyc-open-data", "yellow-taxi", searchQuery, 5, 1).get(); // Fetch the matched items by advancing through the result pages val matched: ArrayList> = ArrayList>(); diff --git a/doc/1/core-classes/search-result/next/snippets/scroll-java.java b/doc/1/core-classes/search-result/next/snippets/scroll-java.java index 1a7528a0..0b1f9c94 100644 --- a/doc/1/core-classes/search-result/next/snippets/scroll-java.java +++ b/doc/1/core-classes/search-result/next/snippets/scroll-java.java @@ -8,7 +8,7 @@ SearchResult results = kuzzle.getDocumentController().search( "nyc-open-data", "yellow-taxi", - searchQuery, "1s", 0, 10).get(); + searchQuery, "1s", 10).get(); // Fetch the matched items by advancing through the result pages ArrayList> matched = new ArrayList<>(); diff --git a/doc/1/core-classes/search-result/next/snippets/scroll-kotlin.kt b/doc/1/core-classes/search-result/next/snippets/scroll-kotlin.kt index 8e792f56..693470c0 100644 --- a/doc/1/core-classes/search-result/next/snippets/scroll-kotlin.kt +++ b/doc/1/core-classes/search-result/next/snippets/scroll-kotlin.kt @@ -12,8 +12,8 @@ ConcurrentHashMap().apply { put("query", query) } var result: SearchResult? = kuzzle -.documentController -.search("nyc-open-data", "yellow-taxi", searchQuery, "1s", 0, 10).get(); + .documentController + .search("nyc-open-data", "yellow-taxi", searchQuery, "1s", 10).get(); // Fetch the matched items by advancing through the result pages val matched: ArrayList> = ArrayList>(); diff --git a/doc/1/getting-started/index.md b/doc/1/getting-started/index.md new file mode 100644 index 00000000..150d6807 --- /dev/null +++ b/doc/1/getting-started/index.md @@ -0,0 +1,6 @@ +--- +code: false +type: branch +order: 0 +title: Getting Started +--- diff --git a/doc/1/getting-started/java/index.md b/doc/1/getting-started/java/index.md new file mode 100644 index 00000000..b11b324e --- /dev/null +++ b/doc/1/getting-started/java/index.md @@ -0,0 +1,168 @@ +--- +code: false +type: page +title: Java +description: Java Getting started +order: 99 +--- + +# 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. + +::: success +Before proceeding, please make sure your system meets the following requirements: + +- **Oracle JDK or OpenJDK** version 8 or higher ([OpenJDK installation instructions](https://openjdk.java.net/install/)) +- A running Kuzzle Server ([Kuzzle installation guide](/core/2/guides/essentials/installing-kuzzle)) + +::: + + +::: info +Having trouble? Get in touch with us on [Discord](http://join.discord.kuzzle.io)! +::: + +## Installation + +You can find the SDK JARs directly on [bintray](https://bintray.com/kuzzle/maven/sdk-jvm). Download and add them to your classpath. + +::: info +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 + +```xml + + io.kuzzle + sdk-jvm + 1.0.0 + pom + +``` + +### Gradle + +```groovy +repositories { + maven() { + url "https://dl.bintray.com/kuzzle/maven" + } +} +dependencies { + compile 'io.kuzzle:sdk-jvm:1.0.0' +} +``` + +### Ivy + +```html + + + +``` + +## First connection + +Initialize a new Java project, create a `GettingStartedFirstConnection.java` file and start by adding the code below: + +<<< ./snippets/firstconnection-java.java + +::: info +If you're not yet familiar with how Kuzzle structures its storage, check our [detailed guide][https://docs.kuzzle.io/core/2/guides/essentials/store-access-data/) +::: + +This program initializes the Kuzzle Server storage by creating an index and a collection. +Run the program with the following command: + +```bash +$ 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! +``` + +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.java` file in the playground and add this code: + +<<< ./snippets/document-java.java + +As you did before, build and run your program: + +```bash +$ javac -classpath ./path/to/the/sdk.jar GettingStartedStorage.java +$ 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](https://docs.kuzzle.io/sdk/jvm/1/controllers/document). + +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.java` with the following code: + +<<< ./snippets/realtime-java.java + +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: + +```bash +$ 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: + +{ + _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 `ConcurrentHashMap`. + +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: + +- discover what this SDK has to offer by browsing other sections of this documentation +- learn how to use [pagination strategies](/sdk/jvm/1/core-classes/search-result/next/#pagination-strategies) with the [document:search](/sdk/jvm/1/controllers/document/search/) API action. +- discover other [Kuzzle guides](core/2/guides/essentials/introduction/) diff --git a/doc/1/getting-started/java/snippets/document-java.java b/doc/1/getting-started/java/snippets/document-java.java new file mode 100644 index 00000000..1a38a946 --- /dev/null +++ b/doc/1/getting-started/java/snippets/document-java.java @@ -0,0 +1,45 @@ +import io.kuzzle.sdk.*; +import io.kuzzle.sdk.protocol.WebSocket; + +import java.util.concurrent.ConcurrentHashMap; + +public class SnippetTest { + private static Kuzzle kuzzle; + + public static void main(String[] args) { + + try { + // Creates a WebSocket connection. + // Replace "kuzzle" with + // your Kuzzle host name (e.g. "localhost") + WebSocket ws = new WebSocket("kuzzle"); + + // Instantiates a Kuzzle client + kuzzle = new Kuzzle(ws); + + // Connects to the server. + kuzzle.connect(); + System.out.println("Connected!"); + } catch(Exception e){ + e.printStackTrace(); + } + + // New document content + ConcurrentHashMap content = new ConcurrentHashMap<>(); + content.put("name", "John"); + content.put("birthday", "1995-11-27"); + content.put("license", "B"); + + // Stores the document in the "yellow-taxi" collection. + try { + kuzzle.getDocumentController() + .create( "nyc-open-data", "yellow-taxi", content).get(); + System.out.println("New document added to the yellow-taxi collection!"); + } catch(Exception e){ + e.printStackTrace(); + } + + // Disconnects the SDK. + kuzzle.disconnect(); + } +} diff --git a/doc/1/getting-started/java/snippets/document-java.test.yml b/doc/1/getting-started/java/snippets/document-java.test.yml new file mode 100644 index 00000000..721f96bd --- /dev/null +++ b/doc/1/getting-started/java/snippets/document-java.test.yml @@ -0,0 +1,9 @@ +name: java-gettingstarted#storage +description: Data manipulation +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create ; curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi/; curl -X DELETE kuzzle:7512/nyc-open-data/yellow-taxi/some-id + after: +template: empty +expected: + - Connected! + - New document added to the yellow-taxi collection! \ No newline at end of file diff --git a/doc/1/getting-started/java/snippets/firstconnection-java.java b/doc/1/getting-started/java/snippets/firstconnection-java.java new file mode 100644 index 00000000..ccb7d3f5 --- /dev/null +++ b/doc/1/getting-started/java/snippets/firstconnection-java.java @@ -0,0 +1,47 @@ +import io.kuzzle.sdk.*; +import io.kuzzle.sdk.protocol.WebSocket; + +import java.util.concurrent.ConcurrentHashMap; + +public class SnippetTest { + private static Kuzzle kuzzle; + + public static void main(String[] args) { + + try { + // Creates a WebSocket connection. + // Replace "kuzzle" with + // your Kuzzle hostname like "localhost" + WebSocket ws = new WebSocket("kuzzle"); + + // Instantiates a Kuzzle client + kuzzle = new Kuzzle(ws); + + // Connects to the server. + kuzzle.connect(); + System.out.println("Connected!"); + } catch(Exception e){ + e.printStackTrace(); + } + + // Freshly installed Kuzzle servers are empty: we need to create + // a new index. + try { + kuzzle.getIndexController().create("nyc-open-data").get(); + System.out.println("Index nyc-open-data created!"); + } catch(Exception e){ + e.printStackTrace(); + } + + // Creates a collection + try { + kuzzle.getCollectionController().create("nyc-open-data", "yellow-taxi").get(); + System.out.println("Collection yellow-taxi created!"); + } catch(Exception e){ + e.printStackTrace(); + } + + // Disconnects the SDK + kuzzle.disconnect(); + } +} diff --git a/doc/1/getting-started/java/snippets/firstconnection-java.test.yml b/doc/1/getting-started/java/snippets/firstconnection-java.test.yml new file mode 100644 index 00000000..a8056263 --- /dev/null +++ b/doc/1/getting-started/java/snippets/firstconnection-java.test.yml @@ -0,0 +1,10 @@ +name: java-gettingstarted#firstconnection +description: First connection +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data + after: +template: empty +expected: + - Connected! + - Index nyc-open-data created! + - Collection yellow-taxi created! diff --git a/doc/1/getting-started/java/snippets/realtime-java.java b/doc/1/getting-started/java/snippets/realtime-java.java new file mode 100644 index 00000000..49780688 --- /dev/null +++ b/doc/1/getting-started/java/snippets/realtime-java.java @@ -0,0 +1,77 @@ +import io.kuzzle.sdk.*; +import io.kuzzle.sdk.protocol.WebSocket; + +import java.util.concurrent.ConcurrentHashMap; + +public class SnippetTest { + private static Kuzzle kuzzle; + + public static void main(String[] args) { + + try { + // Creates a WebSocket connection. + // Replace "kuzzle" with + // your Kuzzle hostname like "localhost" + WebSocket ws = new WebSocket("kuzzle"); + + // Instantiates a Kuzzle client + kuzzle = new Kuzzle(ws); + + // Connects to the server. + kuzzle.connect(); + System.out.println("Connected!"); + } catch (Exception e) { + e.printStackTrace(); + } + + // Subscribes to notifications for drivers having a "B" driver license. + ConcurrentHashMap filters = new ConcurrentHashMap<>(); + ConcurrentHashMap equals = new ConcurrentHashMap<>(); + equals.put("license", "B"); + filters.put("equals", equals); + + try { + // Sends the subscription + kuzzle.getRealtimeController() + .subscribe("nyc-open-data", "yellow-taxi", filters, notification -> { + ConcurrentHashMap content = ((ConcurrentHashMap)(notification.getResult())); + System.out.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(); + System.out.println("Successfully subscribed!"); + } catch (Exception e) { + e.printStackTrace(); + } + + // Writes a new document. This triggers a notification + // sent to our subscription. + ConcurrentHashMap content = new ConcurrentHashMap<>(); + content.put("name", "John"); + content.put("birthday", "1995-11-27"); + content.put("license", "B"); + + try { + kuzzle.getDocumentController() + .create("nyc-open-data", "yellow-taxi", content).get(); + System.out.println("New document added to the yellow-taxi collection!"); + } catch (Exception e) { + e.printStackTrace(); + } + + // Disconnects the SDK. + kuzzle.disconnect(); + } +} diff --git a/doc/1/getting-started/java/snippets/realtime-java.test.yml b/doc/1/getting-started/java/snippets/realtime-java.test.yml new file mode 100644 index 00000000..56c67007 --- /dev/null +++ b/doc/1/getting-started/java/snippets/realtime-java.test.yml @@ -0,0 +1,10 @@ +name: java-gettingstarted#realtime +description: Realtime interactions +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create ; curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi/ + after: +template: empty +expected: + - Connected! + - Successfully subscribed! + - ^New created document notification:.*$ diff --git a/doc/1/getting-started/kotlin/index.md b/doc/1/getting-started/kotlin/index.md new file mode 100644 index 00000000..c0a6847f --- /dev/null +++ b/doc/1/getting-started/kotlin/index.md @@ -0,0 +1,167 @@ +--- +code: false +type: page +title: Kotlin +description: Kotlin Getting started +order: 99 +--- + +# 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. + +::: success +Before proceeding, please make sure your system meets the following requirements: + +- **Oracle JDK or OpenJDK** version 8 or higher ([OpenJDK installation instructions](https://openjdk.java.net/install/)) +- A running Kuzzle Server ([Kuzzle installation guide](/core/2/guides/essentials/installing-kuzzle)) + +::: + + +::: info +Having trouble? Get in touch with us on [Discord](http://join.discord.kuzzle.io)! +::: + +## Installation + +You can find the SDK JARs directly on [bintray](https://bintray.com/kuzzle/maven/sdk-jvm). Download and add them to your classpath. + +::: info +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 + +```xml + + io.kuzzle + sdk-jvm + 1.0.0 + pom + +``` + +### Gradle + +```groovy +repositories { + maven() { + url "https://dl.bintray.com/kuzzle/maven" + } +} +dependencies { + compile 'io.kuzzle:sdk-jvm:1.0.0' +} +``` + +### Ivy + +```html + + + +``` +## First connection + +Initialize a new Java project, create a `GettingStartedFirstConnection.kt` file and start by adding the code below: + +<<< ./snippets/firstconnection-kotlin.kt + +::: info +If you're not yet familiar with how Kuzzle structures its storage, check our [detailed guide][https://docs.kuzzle.io/core/2/guides/essentials/store-access-data/) +::: + +This program initializes the Kuzzle Server storage by creating an index and a collection. +Run the program with the following command: + +```bash +$ 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: + +<<< ./snippets/document-kotlin.kt + +As you did before, build and run your program: + +```bash +$ 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](https://docs.kuzzle.io/sdk/jvm/1/controllers/document). + +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: + +<<< ./snippets/realtime-kotlin.kt + +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: + +```bash +$ 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 `ConcurrentHashMap`. + +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: + +- discover what this SDK has to offer by browsing other sections of this documentation +- learn how to use [pagination strategies](/sdk/jvm/1/core-classes/search-result/next/#pagination-strategies) with the [document:search](/sdk/jvm/1/controllers/document/search/) API action. +- discover other [Kuzzle guides](core/2/guides/essentials/introduction/) diff --git a/doc/1/getting-started/kotlin/snippets/document-kotlin.kt b/doc/1/getting-started/kotlin/snippets/document-kotlin.kt new file mode 100644 index 00000000..7b377f27 --- /dev/null +++ b/doc/1/getting-started/kotlin/snippets/document-kotlin.kt @@ -0,0 +1,38 @@ +import io.kuzzle.sdk.*; +import io.kuzzle.sdk.protocol.WebSocket; + +import java.util.concurrent.ConcurrentHashMap; + +fun main() { + // 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: ConcurrentHashMap = ConcurrentHashMap().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() + } +} diff --git a/doc/1/getting-started/kotlin/snippets/document-kotlin.test.yml b/doc/1/getting-started/kotlin/snippets/document-kotlin.test.yml new file mode 100644 index 00000000..0d06f5e6 --- /dev/null +++ b/doc/1/getting-started/kotlin/snippets/document-kotlin.test.yml @@ -0,0 +1,9 @@ +name: kotlin-gettingstarted#storage +description: Data manipulation +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create ; curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi/; curl -X DELETE kuzzle:7512/nyc-open-data/yellow-taxi/some-id + after: +template: empty +expected: + - Connected! + - New document added to the yellow-taxi collection! \ No newline at end of file diff --git a/doc/1/getting-started/kotlin/snippets/firstconnection-kotlin.kt b/doc/1/getting-started/kotlin/snippets/firstconnection-kotlin.kt new file mode 100644 index 00000000..8e3fc1af --- /dev/null +++ b/doc/1/getting-started/kotlin/snippets/firstconnection-kotlin.kt @@ -0,0 +1,38 @@ +import io.kuzzle.sdk.*; +import io.kuzzle.sdk.protocol.WebSocket; + +import java.util.concurrent.ConcurrentHashMap; + +fun main() { + // 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() + } +} diff --git a/doc/1/getting-started/kotlin/snippets/firstconnection-kotlin.test.yml b/doc/1/getting-started/kotlin/snippets/firstconnection-kotlin.test.yml new file mode 100644 index 00000000..f91d9e24 --- /dev/null +++ b/doc/1/getting-started/kotlin/snippets/firstconnection-kotlin.test.yml @@ -0,0 +1,10 @@ +name: kotlin-gettingstarted#firstconnection +description: First connection +hooks: + before: curl -X DELETE kuzzle:7512/nyc-open-data + after: +template: empty +expected: + - Connected! + - Index nyc-open-data created! + - Collection yellow-taxi created! diff --git a/doc/1/getting-started/kotlin/snippets/realtime-kotlin.kt b/doc/1/getting-started/kotlin/snippets/realtime-kotlin.kt new file mode 100644 index 00000000..5484cce4 --- /dev/null +++ b/doc/1/getting-started/kotlin/snippets/realtime-kotlin.kt @@ -0,0 +1,69 @@ +import io.kuzzle.sdk.*; +import io.kuzzle.sdk.protocol.WebSocket; + +import java.util.concurrent.ConcurrentHashMap; + +fun main() { + // 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 { + // Subscribes to notifications for drivers having a "B" driver license. + val equals: ConcurrentHashMap = ConcurrentHashMap().apply { + put("license", "B") + } + val filters: ConcurrentHashMap = ConcurrentHashMap().apply { + put("equals", equals) + } + + // Sends the subscription + kuzzle + .realtimeController + .subscribe("nyc-open-data", "yellow-taxi", filters) { notification -> + val content: ConcurrentHashMap = notification.result as ConcurrentHashMap + 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: ConcurrentHashMap = ConcurrentHashMap().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() + } +} diff --git a/doc/1/getting-started/kotlin/snippets/realtime-kotlin.test.yml b/doc/1/getting-started/kotlin/snippets/realtime-kotlin.test.yml new file mode 100644 index 00000000..de1197bb --- /dev/null +++ b/doc/1/getting-started/kotlin/snippets/realtime-kotlin.test.yml @@ -0,0 +1,10 @@ +name: kotlin-gettingstarted#realtime +description: Realtime interactions +hooks: + before: curl -X POST kuzzle:7512/nyc-open-data/_create ; curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi/ + after: +template: empty +expected: + - Connected! + - Successfully subscribed! + - ^New created document notification:.*$ diff --git a/src/main/kotlin/io/kuzzle/sdk/Kuzzle.kt b/src/main/kotlin/io/kuzzle/sdk/Kuzzle.kt index acbfd9ad..82a61cdd 100644 --- a/src/main/kotlin/io/kuzzle/sdk/Kuzzle.kt +++ b/src/main/kotlin/io/kuzzle/sdk/Kuzzle.kt @@ -75,7 +75,8 @@ class Kuzzle { queries.remove(response.requestId) return } - + + queries[response.requestId]?.completeExceptionally(ApiErrorException(response)) protocol.trigger("tokenExpired") } diff --git a/src/main/kotlin/io/kuzzle/sdk/controllers/CollectionController.kt b/src/main/kotlin/io/kuzzle/sdk/controllers/CollectionController.kt index 375b163c..aab8a549 100644 --- a/src/main/kotlin/io/kuzzle/sdk/controllers/CollectionController.kt +++ b/src/main/kotlin/io/kuzzle/sdk/controllers/CollectionController.kt @@ -9,10 +9,11 @@ import java.util.concurrent.ConcurrentHashMap class CollectionController(kuzzle: Kuzzle) : BaseController(kuzzle) { + @JvmOverloads fun create( index: String, collection: String, - definition: ConcurrentHashMap? + definition: ConcurrentHashMap? = null ): CompletableFuture { return kuzzle .query(KuzzleMap().apply { diff --git a/src/main/kotlin/io/kuzzle/sdk/controllers/DocumentController.kt b/src/main/kotlin/io/kuzzle/sdk/controllers/DocumentController.kt index 6e10ed1b..ac4484bd 100644 --- a/src/main/kotlin/io/kuzzle/sdk/controllers/DocumentController.kt +++ b/src/main/kotlin/io/kuzzle/sdk/controllers/DocumentController.kt @@ -284,8 +284,8 @@ class DocumentController(kuzzle: Kuzzle) : BaseController(kuzzle) { collection: String, searchQuery: ConcurrentHashMap, scroll: String? = null, - from: Int = 0, - size: Int? = null): CompletableFuture { + size: Int? = null, + from: Int = 0): CompletableFuture { val query = KuzzleMap().apply { put("index", index) put("collection", collection) @@ -305,6 +305,16 @@ class DocumentController(kuzzle: Kuzzle) : BaseController(kuzzle) { .thenApplyAsync { response -> SearchResult(kuzzle, query, scroll, from, size, response) } } + fun search( + index: String, + collection: String, + searchQuery: ConcurrentHashMap, + size: Int? = null, + from: Int = 0): CompletableFuture { + + return search(index, collection, searchQuery, null, size, from); + } + @JvmOverloads fun update( index: String, diff --git a/src/main/kotlin/io/kuzzle/sdk/coreClasses/SearchResult.kt b/src/main/kotlin/io/kuzzle/sdk/coreClasses/SearchResult.kt index ba59fc8b..1b263076 100644 --- a/src/main/kotlin/io/kuzzle/sdk/coreClasses/SearchResult.kt +++ b/src/main/kotlin/io/kuzzle/sdk/coreClasses/SearchResult.kt @@ -30,7 +30,7 @@ class SearchResult { kuzzle: Kuzzle?, request: ConcurrentHashMap?, scroll: String? = null, - from: Int, + from: Int = 0, size: Int? = null, response: Response, previouslyFetched: Int? = null) { From 5269a51a56306b2354f5eff35272c58eb157625a Mon Sep 17 00:00:00 2001 From: Yoann Abbes Date: Tue, 1 Dec 2020 11:45:21 +0100 Subject: [PATCH 2/4] update build.gradle sdk version --- build.gradle.kts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/build.gradle.kts b/build.gradle.kts index b15628be..e0932957 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -17,7 +17,7 @@ plugins { val artifactName = "sdk-jvm" val artifactGroup = "io.kuzzle" -val artifactVersion = "1.0.0" +val artifactVersion = "1.0.1" val pomUrl = "https://github.com/kuzzleio/sdk-jvm" val pomScmUrl = "https://github.com/kuzzleio/sdk-jvm" @@ -94,7 +94,7 @@ bintray { } group = "io.kuzzle.sdk" -version = "1.0.0" +version = "1.0.1" val ktorVersion = "1.3.2" From 82f47f714848c7e5f6bda7cf179915f07df0daa1 Mon Sep 17 00:00:00 2001 From: Yoann Abbes Date: Tue, 1 Dec 2020 11:52:27 +0100 Subject: [PATCH 3/4] reverse update build.gradle sdk version --- build.gradle.kts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/build.gradle.kts b/build.gradle.kts index e0932957..b15628be 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -17,7 +17,7 @@ plugins { val artifactName = "sdk-jvm" val artifactGroup = "io.kuzzle" -val artifactVersion = "1.0.1" +val artifactVersion = "1.0.0" val pomUrl = "https://github.com/kuzzleio/sdk-jvm" val pomScmUrl = "https://github.com/kuzzleio/sdk-jvm" @@ -94,7 +94,7 @@ bintray { } group = "io.kuzzle.sdk" -version = "1.0.1" +version = "1.0.0" val ktorVersion = "1.3.2" From 39fb5e22c1ae5516f5d80abe6c9904ace59df954 Mon Sep 17 00:00:00 2001 From: Yoann Abbes Date: Tue, 1 Dec 2020 11:53:06 +0100 Subject: [PATCH 4/4] Release 1.0.1 --- build.gradle.kts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/build.gradle.kts b/build.gradle.kts index b15628be..3d37f411 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -94,8 +94,7 @@ bintray { } group = "io.kuzzle.sdk" -version = "1.0.0" - +version = "1.0.1" val ktorVersion = "1.3.2" repositories {