SDK V3 Kuzzle&WebSocket Documentation

.travis.yml

@@ -18,8 +18,8 @@ jobs:
         - cd kuzzle-sdk-java && npm run doc-prepare
         - npm run --prefix doc/framework clone-repos && cd -
       script:
-        - gem install typhoeus
-        - HYDRA_MAX_CONCURRENCY=20 npm run --prefix doc/framework dead-links
+        - cd kuzzle-sdk-java && gem install typhoeus
+        - HYDRA_MAX_CONCURRENCY=20 npm run --prefix doc/framework dead-links && cd -
 
     - stage: Deployment Doc Dev
       name: Deploy next-docs.kuzzle.io

kuzzle-sdk-java/.ci/doc/config.yml

@@ -0,0 +1,20 @@
+---
+
+snippets:
+  mount: /mnt
+  path: doc/**/snippets/*.test.yml
+  templates: /mnt/.ci/doc/templates
+
+runners:
+  default: java
+
+  java:
+    service: doc-runner-java
+    path: /var/snippets/java
+    lint:
+      cmd: echo "lint me master"
+    build:
+      cmd: cp -f {{ snippet.source }} Main.java && javac -cp "/mnt/build/libs/kuzzle-sdk-java-3.0.0.jar:/gson2.8.5.jar:/nv-websocket-client2.9.jar" Main.java
+    run:
+      cmd: java -cp ".:/mnt/build/libs/kuzzle-sdk-java-3.0.0.jar:/gson2.8.5.jar:/nv-websocket-client2.9.jar" Main
+      before: timeout 600 bash -c 'until curl -f -s -o /dev/null http://kuzzle:7512/_now; do sleep 1; done'

kuzzle-sdk-java/.ci/doc/docker-compose.yml

@@ -0,0 +1,49 @@
+version: '3'
+
+services:
+  kuzzle:
+    image: kuzzleio/kuzzle:2
+    ports:
+      - "7512:7512"
+    cap_add:
+      - SYS_PTRACE
+    depends_on:
+      - redis
+      - elasticsearch
+    container_name: kuzzle
+    environment:
+      - kuzzle_services__storageEngine__client__host=http://elasticsearch:9200
+      - kuzzle_services__internalCache__node__host=redis
+      - kuzzle_services__memoryStorage__node__host=redis
+      - NODE_ENV=development
+
+  redis:
+    image: redis:5
+
+  elasticsearch:
+    image: kuzzleio/elasticsearch:7.4.0
+    ulimits:
+      nofile: 65536
+
+  doc-tests:
+    image: kuzzleio/snippets-tests
+    privileged: true
+    depends_on:
+      - kuzzle
+      - doc-runner-java
+    volumes:
+      - ../..:/mnt
+      - /var/run/docker.sock:/var/run/docker.sock
+      - snippets:/var/snippets
+    environment:
+      - CONFIG_FILE=/mnt/.ci/doc/config.yml
+
+  doc-runner-java:
+    image: groot:latest
+    command: tail -f /dev/null
+    volumes:
+      - ../..:/mnt
+      - snippets:/var/snippets
+
+volumes:
+  snippets:

kuzzle-sdk-java/.ci/doc/docker/Dockerfile

@@ -0,0 +1,14 @@
+FROM openjdk:8
+
+LABEL io.kuzzle.vendor="Kuzzle <support@kuzzle.io>"
+LABEL description="Runner for java documentation snippets"
+LABEL name="kuzzleio/documentation:java"
+
+RUN apt-get update && apt-get install -y \
+      git \
+      curl
+
+RUN curl https://repo1.maven.org/maven2/com/google/code/gson/gson/2.8.5/gson-2.8.5.jar --output gson2.8.5.jar
+RUN curl https://repo1.maven.org/maven2/com/neovisionaries/nv-websocket-client/2.9/nv-websocket-client-2.9.jar --output nv-websocket-client2.9.jar
+
+WORKDIR /app

kuzzle-sdk-java/.ci/doc/templates/blank.tpl.java

@@ -0,0 +1,15 @@
+import java.lang.System;
+import io.kuzzle.sdk.Kuzzle;
+import io.kuzzle.sdk.Protocol.WebSocket;
+import io.kuzzle.sdk.CoreClasses.Responses.*;
+import io.kuzzle.sdk.Exceptions.*;
+import java.util.concurrent.ConcurrentHashMap;
+
+public class Main {
+
+    public static void main(String[] args) {
+        [snippet-code]
+        System.out.println("Success");
+    }
+
+}

kuzzle-sdk-java/.ci/doc/templates/catch.tpl.java

@@ -0,0 +1,18 @@
+import java.lang.System;
+import io.kuzzle.sdk.Kuzzle;
+import io.kuzzle.sdk.Protocol.WebSocket;
+import io.kuzzle.sdk.CoreClasses.Responses.*;
+import io.kuzzle.sdk.Exceptions.*;
+import java.util.concurrent.ConcurrentHashMap;
+
+public class Main {
+
+    public static void main(String[] args) {
+        try {
+            [snippet-code]
+        } catch (Exception) {
+            System.out.println("Success");
+        }
+    }
+
+}

kuzzle-sdk-java/.ci/doc/templates/default.tpl.java

@@ -0,0 +1,19 @@
+import java.lang.System;
+import io.kuzzle.sdk.Kuzzle;
+import io.kuzzle.sdk.Protocol.WebSocket;
+import io.kuzzle.sdk.CoreClasses.Responses.*;
+import io.kuzzle.sdk.Exceptions.*;
+import java.util.concurrent.ConcurrentHashMap;
+
+public class Main {
+
+    public static void main(String[] args) throws Exception {
+        WebSocket socket = new WebSocket("kuzzle");
+        Kuzzle kuzzle = new Kuzzle(socket);
+
+        kuzzle.connect();
+        [snippet-code]
+        kuzzle.disconnect();
+    }
+
+}

kuzzle-sdk-java/.ci/doc/templates/empty.tpl.java

@@ -0,0 +1,15 @@
+import java.lang.System;
+import io.kuzzle.sdk.Kuzzle;
+import io.kuzzle.sdk.Protocol.WebSocket;
+import io.kuzzle.sdk.CoreClasses.Responses.*;
+import io.kuzzle.sdk.Exceptions.*;
+import java.util.concurrent.ConcurrentHashMap;
+
+public class Main {
+
+    public static void main(String[] args) throws Exception {
+        [snippet-code]
+        System.out.println("Success");
+    }
+
+}

kuzzle-sdk-java/.ci/doc/templates/empty_disconnect.tpl.java

@@ -0,0 +1,14 @@
+import java.lang.System;
+import io.kuzzle.sdk.Kuzzle;
+import io.kuzzle.sdk.Protocol.WebSocket;
+import java.util.concurrent.ConcurrentHashMap;
+
+public class Main {
+
+    public static void main(String[] args) throws Exception {
+        [snippet-code]
+        kuzzle.disconnect();
+        System.out.println("Success");
+    }
+
+}

kuzzle-sdk-java/.ci/doc/templates/kuzzle.tpl.java

@@ -0,0 +1,19 @@
+import java.lang.System;
+import io.kuzzle.sdk.Kuzzle;
+import io.kuzzle.sdk.Protocol.WebSocket;
+import io.kuzzle.sdk.CoreClasses.Responses.*;
+import io.kuzzle.sdk.Exceptions.*;
+import java.util.concurrent.ConcurrentHashMap;
+
+public class Main {
+
+    public static void main(String[] args) throws Exception {
+        WebSocket socket = new WebSocket("kuzzle");
+        Kuzzle kuzzle = new Kuzzle(socket);
+
+        kuzzle.connect();
+        [snippet-code]
+        System.out.println("Success");
+    }
+
+}

kuzzle-sdk-java/.ci/docker-compose.yml

@@ -0,0 +1,28 @@
+version: '3'
+
+services:
+  kuzzle:
+    image: kuzzleio/kuzzle:2
+    ports:
+      - "7512:7512"
+    cap_add:
+      - SYS_PTRACE
+    depends_on:
+      - redis
+      - elasticsearch
+    environment:
+      - kuzzle_services__storageEngine__client__host=http://elasticsearch:9200
+      - kuzzle_services__internalCache__node__host=redis
+      - kuzzle_services__memoryStorage__node__host=redis
+      - NODE_ENV=development
+
+  redis:
+    image: redis:5
+
+  elasticsearch:
+    image: kuzzleio/elasticsearch:7.4.0
+    ulimits:
+      nofile: 65536
+
+volumes:
+  snippets:

kuzzle-sdk-java/.ci/start_kuzzle.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -e
+# Download and launch custom Kuzzle stack
+
+docker-compose -f .ci/docker-compose.yml up -d
+
+
+printf 'Waiting for Kuzzle stack to be up and running'
+
+until $(curl --output /dev/null --silent --head --fail http://localhost:7512); do
+  printf '.'
+  sleep 5
+done

kuzzle-sdk-java/.ci/stop_kuzzle.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -e
+# Download and launch custom Kuzzle stack
+
+docker-compose -f .ci/docker-compose.yml stop

kuzzle-sdk-java/.settings/org.eclipse.buildship.core.prefs

@@ -0,0 +1,2 @@
+connection.project.dir=
+eclipse.preferences.version=1

kuzzle-sdk-java/doc/3/core-classes/kuzzle/connect/index.md

@@ -0,0 +1,24 @@
+---
+code: true
+type: page
+title: connect
+description: Connects to Kuzzle using the `host` property provided in the [websocket parameters](/sdk/java/3/protocols/websocket/constructor#arguments).
+---
+
+# connect
+
+Connects to Kuzzle using the `host` property provided in the [websocket parameters](/sdk/java/3/protocols/websocket/constructor#arguments). Subsequent calls have no effect if the SDK is already connected.
+
+## Arguments
+
+```java
+public void connect() throws Exception;
+```
+
+## Exceptions
+
+Throws an `Exception` when an error occurs during the connection.
+
+## Usage
+
+<<< ./snippets/connect.java

kuzzle-sdk-java/doc/3/core-classes/kuzzle/connect/snippets/connect.java

@@ -0,0 +1,6 @@
+
+WebSocket networkProtocol = new WebSocket("kuzzle");
+
+Kuzzle kuzzle = new Kuzzle(networkProtocol);
+
+kuzzle.connect();

kuzzle-sdk-java/doc/3/core-classes/kuzzle/connect/snippets/connect.test.yml

@@ -0,0 +1,7 @@
+name: kuzzle#connect
+description: Connects to Kuzzle using the `host` property provided in the constructor parameters. Subsequent call have no effect if the SDK is already connected.
+hooks:
+  before:
+  after:
+template: empty_disconnect
+expected: Success

kuzzle-sdk-java/doc/3/core-classes/kuzzle/constructor/index.md

@@ -0,0 +1,46 @@
+---
+code: true
+type: page
+title: constructor
+description: This constructor create a new instance of the SDK. Each instance represent a different connection to a Kuzzle server with specific options.
+---
+
+# constructor
+
+This constructor creates a new instance of the SDK. Each instance represents a different connection to a Kuzzle server with specific options.
+
+## Arguments
+
+```java
+public Kuzzle(
+    AbstractProtocol networkProtocol
+) throws IllegalArgumentException;
+
+public Kuzzle(
+    AbstractProtocol networkProtocol,
+    KuzzleOptions options
+) throws IllegalArgumentException;
+```
+
+| Argument   | Type                      | Description                       |
+|------------|---------------------------|-----------------------------------|
+| `protocol` | <pre>AbstractProtol</pre> | Protocol used by the SDK instance |
+| `options`  | <pre>KuzzleOptions</pre>  | Kuzzle object configuration       |
+
+### options
+
+| Argument                 | Type<br>(default)                                                                                              | Description                                                           |
+|--------------------------|----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
+| `maxQueueSize`           | <pre>int</pre><br>(`-1`)                                                                                       | The maximum amount of elements that the queue can contain.           |
+| `minTokenDuration`       | <pre>int</pre><br>(`3600000`)                                                                                  | The minimum duration of a Token before being automatically refreshed. |
+| `refreshedTokenDuration` | <pre>int</pre><br>(`3600000`)                                                                                  | The minimum duration of a Token after refresh.                        |
+| `maxRequestDelay`        | <pre>int</pre><br>(`1000`)                                                                                     | The maximum delay between two requests to be replayed.                |
+| `filter`                 | <pre>Predicate<ConcurrentHashMap<String, Object>></pre><br>(`(ConcurrentHashMap<String, Object> obj) -> true`) | Filter the replayed queries                                           |
+
+## Return
+
+A `Kuzzle` SDK instance
+
+## Usage
+
+<<< ./snippets/constructor.java

kuzzle-sdk-java/doc/3/core-classes/kuzzle/constructor/snippets/constructor.java

@@ -0,0 +1,4 @@
+
+WebSocket networkProtocol = new WebSocket("kuzzle");
+
+Kuzzle kuzzle = new Kuzzle(networkProtocol);

kuzzle-sdk-java/doc/3/core-classes/kuzzle/constructor/snippets/constructor.test.yml

@@ -0,0 +1,7 @@
+name: kuzzle#constructor
+description: This constructor creates a new instance of the SDK. Each instance represents a different connection to a Kuzzle server with specific options.
+hooks:
+  before:
+  after:
+template: empty
+expected: Success

kuzzle-sdk-java/doc/3/core-classes/kuzzle/disconnect/index.md

@@ -0,0 +1,22 @@
+---
+code: true
+type: page
+title: disconnect
+description: Closes the current connection to Kuzzle.
+---
+
+# disconnect
+
+Closes the current connection to Kuzzle. The SDK then enters the `offline` state. A call to `disconnect()` will not trigger a `disconnected` event. This event is only triggered on unexpected disconnection.
+
+If there are still pending requests during the `disconnect` call, a `discarded` event will be issued for each of them.
+
+## Arguments
+
+```java
+public void disconnect();
+```
+
+## Usage
+
+<<< ./snippets/disconnect.java

kuzzle-sdk-java/doc/3/core-classes/kuzzle/disconnect/snippets/disconnect.java

@@ -0,0 +1 @@
+kuzzle.disconnect();

kuzzle-sdk-java/doc/3/core-classes/kuzzle/disconnect/snippets/disconnect.test.yml

@@ -0,0 +1,7 @@
+name: kuzzle#disconnect
+description: Disconnect kuzzle.
+hooks:
+  before:
+  after:
+template: kuzzle
+expected: Success