Add a "How to Migrate from SDK Java to SDK JVM" page (#99)

## What does this PR do ? Add a "How to Migrate from SDK Java to SDK JVM" page #97 Since this doc use an example with `document:search`, kuzzleio/sdk-jvm#23 has to be merged before (the signature has been updated) ### Boyscout Typo in Getting Started
kuzzleio · Dec 4, 2020 · 3259f30 · 3259f30
1 parent 33cd92a
commit 3259f30
Show file tree

Hide file tree

Showing 4 changed files with 228 additions and 11 deletions.
diff --git a/doc/3/getting-started/install/index.md b/doc/3/getting-started/install/index.md
@@ -35,22 +35,50 @@ If you're using Eclipse, IntelliJ or another Java IDE, you need to add the SDK a
 
 ### Installing on Android using gradle
 
-In your app build.gradle add the following line and sync.
+To build the project, add the following lines:
 
-    implementation "io.kuzzle:kuzzle-sdk-java:3.0.0"
+### Maven
+
+```xml
+<dependency>
+  <groupId>io.kuzzle</groupId>
+  <artifactId>kuzzle-sdk-java</artifactId>
+  <version>3.0.0</version>
+  <type>pom</type>
+</dependency>
+```
+### Gradle
+
+```groovy
+repositories {
+    maven() {
+        url  "https://dl.bintray.com/kuzzle/maven" 
+    }
+}
+dependencies {
+  compile 'io.kuzzle:kuzzle-sdk-java:3.0.0'
+}
+```
+### Ivy
+
+```html
+<dependency org='io.kuzzle' name='kuzzle-sdk-java' rev='3.0.0'>
+  <artifact name='kuzzle-sdk-java' ext='pom' ></artifact>
+</dependency>
+```
 
 ## First connection
 
-Initialize a new Java project, create a `gettingstartedfirstconnection.java` file and start by adding the code below:
+Initialize a new Java project, create a `GettingStartedFirstConnection.java` file and start by adding the code below:
 
 <<< ./snippets/firstconnection.java
 
 This program initializes the Kuzzle Server storage by creating a index, and a collection inside it
 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
+$ 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!
@@ -71,15 +99,15 @@ 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:
+  Create a `GettingStartedStorage.java` file in the playground and add this code:
 
 <<< ./snippets/document.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
+$ 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!
 ```
@@ -92,7 +120,7 @@ Now you know how to:
 
 ## Subscribe to realtime document notifications (pub/sub)
 
-Time to use realtime with Kuzzle. Create a new file `gettingstartedrealtime.java` with the following code:
+Time to use realtime with Kuzzle. Create a new file `GettingStartedRealtime.java` with the following code:
 
 <<< ./snippets/realtime.java
 
@@ -101,8 +129,8 @@ This program subscribes to changes made to documents with a `license` field set
 Build and run your program:
 
 ```bash
-$ javac -classpath ./path/to/the/sdk.jar gettingstartedrealtime.java
-$ java -classpath .:./path/to/the/sdk.jar gettingstartedrealtime
+$ 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!

diff --git a/doc/3/migration/how-to/index.md b/doc/3/migration/how-to/index.md
@@ -0,0 +1,161 @@
+---
+code: false
+type: page
+title: SDK Java to SDK JVM
+description: SDK Java to SDK JVM
+order: 99
+---
+
+# SDK JVM
+
+In this tutorial you will learn how to migrate from the Kuzzle **Java SDK** to the **JVM SDK**.
+
+::: info
+Having trouble? Get in touch with us on [Discord](http://join.discord.kuzzle.io)!
+:::
+
+## Installation
+
+The installation of the JVM SDK is the same as for the Java SDK.
+You can find the SDK JARs directly on [bintray](https://bintray.com/kuzzle/maven/sdk-jvm). Download them and add them to your classpath.
+
+### Maven:
+**from**
+```xml
+<dependency>
+  <groupId>io.kuzzle</groupId>
+  <artifactId>kuzzle-sdk-java</artifactId>
+  <version>3.0.0</version>
+  <type>pom</type>
+</dependency>
+```
+**to**
+```xml
+<dependency>
+  <groupId>io.kuzzle</groupId>
+  <artifactId>sdk-jvm</artifactId>
+  <version>1.0.0</version>
+  <type>pom</type>
+</dependency>
+```
+
+### Gradle:
+**from**
+```groovy
+implementation 'io.kuzzle:kuzzle-sdk-java:3.0.0'
+```
+**to**
+```groovy
+implementation 'io.kuzzle:sdk-jvm:1.0.0'
+```
+
+### Ivy:
+**from**
+```html
+<dependency org='io.kuzzle' name='kuzzle-sdk-java' rev='3.0.0'>
+  <artifact name='kuzzle-sdk-java' ext='pom' ></artifact>
+</dependency>
+```
+**to**
+```html
+<dependency org='io.kuzzle' name='sdk-jvm' rev='1.0.0'>
+  <artifact name='sdk-jvm' ext='pom' ></artifact>
+</dependency>
+```
+
+# Breaking changes
+
+## Options handling
+
+The main difference between those two SDKs is the way they handle options on API actions.
+
+In the Java SDK, there is an option class for each API action, such as [SearchOptions](/sdk/java/3/core-classes/search-options),
+[CreateOptions](/sdk/java/3/core-classes/create-options) or [SubscriptionOptions](/sdk/java/3/core-classes/subscribe-options).
+
+Using option objects was a simple and easy way for our SDK users to handle the many available options in API actions.
+
+The new JVM SDK is now entirely written in Kotlin. The Java part of that SDK is now generated from the Kotlin code.  
+The idiomatic way of handling optional arguments in Kotlin is to use named arguments, which is not supported by Java. 
+
+What this means is this: optional arguments in Java are now handled using overloads. Most of them are automatically created when converting Kotlin code to Java, but we also added a few ones of our own, and removed less pertinent ones, so that the methods exposed by the Java SDK are as consistent as possible.
+
+That is why in this SDK, **we do not have any `Options` object**.
+
+For example:
+
+```java
+public CompletableFuture<SearchResult> search(
+      final String index,
+      final String collection,
+      final ConcurrentHashMap<String, Object> searchQuery,
+      final SearchOptions options)
+```
+Becomes:
+
+```kotlin
+@JvmOverloads
+fun search(
+      index: String,
+      collection: String,
+      searchQuery: ConcurrentHashMap<String, Any?>,
+      scroll: String? = null,
+      size: Int? = null,
+      from: Int = 0): CompletableFuture<SearchResult>
+```
+
+Which will generate the followings signatures:
+
+```java
+public CompletableFuture<SearchResult> search(
+      String index,
+      String collection,
+      ConcurrentHashMap<String, Object> searchQuery)
+
+public CompletableFuture<SearchResult> search(
+      String index,
+      String collection,
+      ConcurrentHashMap<String, Object> searchQuery,
+      String scroll)
+
+public CompletableFuture<SearchResult> search(
+      String index,
+      String collection,
+      ConcurrentHashMap<String, Object> searchQuery,
+      String scroll,
+      Integer size)
+
+public CompletableFuture<SearchResult> search(
+      String index,
+      String collection,
+      ConcurrentHashMap<String, Object> searchQuery,
+      Integer size,
+      Integer from)
+```
+
+### Example
+
+Using the Java SDK, you could have written:
+
+```java
+SearchOptions options = new SearchOptions();
+    options.setScroll("10s");
+    options.setSize(5);
+
+SearchResult results = kuzzle.getDocumentController().search(
+  "nyc-open-data",
+  "yellow-taxi",
+  searchQuery, options).get();
+```
+
+With the new Jvm SDK it becomes:
+
+```java
+SearchResult results = kuzzle.getDocumentController().search(
+  "nyc-open-data",
+  "yellow-taxi",
+  searchQuery, "10s", 5).get();
+```
+
+::: info
+You can find the full documentation of the Jvm SDK [here](https://docs.kuzzle.io/sdk/jvm/1), and compare signatures to adapt your code.
+:::
diff --git a/doc/3/migration/index.md b/doc/3/migration/index.md
@@ -0,0 +1,6 @@
+---
+code: false
+type: branch
+order: 0
+title: Migration
+---
diff --git a/doc/frontmatter-errors.json b/doc/frontmatter-errors.json
@@ -0,0 +1,22 @@
+{
+    "/migration/": [
+        {
+            "fix": {
+                "type": "branch"
+            },
+            "error": "MISSING_KEY",
+            "key": "type"
+        },
+        {
+            "error": "MISSING_KEY",
+            "key": "title"
+        },
+        {
+            "fix": {
+                "code": false
+            },
+            "error": "MISSING_KEY",
+            "key": "code"
+        }
+    ]
+}