Merge pull request #24 from kuzzleio/1.0.1-proposal

Release 1.0.1

.ci/doc/templates/empty.tpl.kt

@@ -0,0 +1 @@
+[snippet-code]

build.gradle.kts

@@ -94,7 +94,7 @@ bintray {
 }
 
 group = "io.kuzzle.sdk"
-version = "1.1.0"
+version = "1.0.1"
 val ktorVersion = "1.3.2"
 
 repositories {

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<SearchResult> search(
       String index,
       String collection,
-      ConcurrentHashMap<String, Object> searchQuery,
-      String scroll,
-      Integer from,
-      Integer size) throws NotConnectedException, InternalException
+      ConcurrentHashMap<String, Object> searchQuery) throws NotConnectedException, InternalException
 
 public CompletableFuture<SearchResult> search(
       String index,
       String collection,
       ConcurrentHashMap<String, Object> searchQuery,
-      String scroll,
-      Integer from) throws NotConnectedException, InternalException
+      String scroll) throws NotConnectedException, InternalException
 
 public CompletableFuture<SearchResult> search(
       String index,
       String collection,
       ConcurrentHashMap<String, Object> searchQuery,
-      String scroll) throws NotConnectedException, InternalException
+      String scroll,
+      Integer size) throws NotConnectedException, InternalException
 
 public CompletableFuture<SearchResult> search(
       String index,
       String collection,
-      ConcurrentHashMap<String, Object> searchQuery)
+      ConcurrentHashMap<String, Object> 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<String?, Any?>,
       scroll: String? = null,
-      from: Int = 0,
-      size: Int? = null): CompletableFuture<SearchResult>
+      size: Int? = null,
+      from: Int = 0): CompletableFuture<SearchResult>
 ```
 
 | Arguments          | Type                                         | Description                       |

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
 

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<ConcurrentHashMap<String, Object>> matched = new ArrayList<>();

doc/1/core-classes/search-result/next/snippets/fromsize-kotlin.kt

@@ -14,8 +14,8 @@ ConcurrentHashMap<String, Any?>().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<ConcurrentHashMap<String, Any>> = ArrayList<ConcurrentHashMap<String, Any>>();

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<ConcurrentHashMap<String, Object>> matched = new ArrayList<>();

doc/1/core-classes/search-result/next/snippets/scroll-kotlin.kt

@@ -12,8 +12,8 @@ ConcurrentHashMap<String, Any?>().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<ConcurrentHashMap<String, Any>> = ArrayList<ConcurrentHashMap<String, Any>>();

doc/1/getting-started/index.md

@@ -0,0 +1,6 @@
+---
+code: false
+type: branch
+order: 0
+title: Getting Started
+---

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
+<dependency>
+  <groupId>io.kuzzle</groupId>
+  <artifactId>sdk-jvm</artifactId>
+  <version>1.0.0</version>
+  <type>pom</type>
+</dependency>
+```
+
+### Gradle
+
+```groovy
+repositories {
+    maven() {
+        url  "https://dl.bintray.com/kuzzle/maven" 
+    }
+}
+dependencies {
+  compile 'io.kuzzle:sdk-jvm:1.0.0'
+}
+```
+
+### Ivy
+
+```html
+<dependency org='io.kuzzle' name='sdk-jvm' rev='1.0.0'>
+  <artifact name='sdk-jvm' ext='pom' ></artifact>
+</dependency>
+```
+
+## 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/)

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<String, Object> 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();
+  }
+}

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!

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();
+  }
+}

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!