From 83ca2a223e27427d1726a4052723cda40aa42962 Mon Sep 17 00:00:00 2001 From: scottinet Date: Thu, 7 Dec 2017 16:28:36 +0100 Subject: [PATCH] remove autoconnection from sdk code examples --- src/guide/essentials/user-authentication.md | 42 +++++------- src/guide/getting-started/index.md | 65 ++++++++++--------- src/sdk-reference/essentials/offline-first.md | 4 +- src/sdk-reference/kuzzle/connect.md | 36 ++++++---- src/sdk-reference/kuzzle/index.md | 31 +-------- 5 files changed, 83 insertions(+), 95 deletions(-) diff --git a/src/guide/essentials/user-authentication.md b/src/guide/essentials/user-authentication.md index a96a87bfa..92d25ef00 100644 --- a/src/guide/essentials/user-authentication.md +++ b/src/guide/essentials/user-authentication.md @@ -18,33 +18,27 @@ If you have no users in your Kuzzle Backend yet, you can read the documentation Create a `login.js` file, NPM-install the Kuzzle SDK and start coding: ```javascript -var Kuzzle = require('kuzzle-sdk') - -var kuzzle = new Kuzzle('localhost', () => { - kuzzle - .loginPromise('local', { - username: 'admin', - password: 'test' - }) - .then(() => { - console.log('logged!') - }) - .catch(err => { - console.error(err.message) - }) -}) - +const Kuzzle = require('kuzzle-sdk') + +const kuzzle = new Kuzzle('localhost') + +kuzzle + .connectPromise() + .then(() => loginPromise('local', {username: '', password: ''}) + .then(() => { + console.log('logged!') + }) + .catch(err => { + console.error(err.message) + }) ``` -Assuming that you have an `admin` user with `test` password in your Kuzzle Backoffice, the code above does the following: -* loads the `Kuzzle` SDK from it NPM package, -* instantiates the SDK by connecting it to the Kuzzle Backoffice running on `localhost`, -* _after the SDK connected to Kuzzle Backend_, it performs a login for the `admin` user, -* displays to console a success message or an error message whether the login has succeeded or failed. +The code above does the following: - +* loads the `Kuzzle` SDK from the NPM package, +* instantiates a new SDK object +* connects it to a remote Kuzzle server +* performs a login with the provided username and password --- diff --git a/src/guide/getting-started/index.md b/src/guide/getting-started/index.md index c8f1c9b4d..73033f8a3 100644 --- a/src/guide/getting-started/index.md +++ b/src/guide/getting-started/index.md @@ -103,26 +103,26 @@ Then, create a `init.js` file and start coding: ```javascript const Kuzzle = require('kuzzle-sdk') -// connect to the Kuzzle server +// create a new kuzzle object const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'}) -kuzzle.once('connected', () => { - kuzzle - .createIndexPromise('playground') - .then(() => kuzzle.collection('mycollection').createPromise()) - .then(() => { - console.log('playground/mycollection ready') - }) - .catch(err => { - console.error(err.message) - }) - .finally(() => kuzzle.disconnect()) -}) +kuzzle + .connectPromise() + .then(() => kuzzle.createIndexPromise('playground')) + .then(() => kuzzle.collection('mycollection').createPromise()) + .then(() => { + console.log('playground/mycollection ready') + }) + .catch(err => { + console.error(err.message) + }) + .finally(() => kuzzle.disconnect()) ``` This code does the following: * loads the `Kuzzle` SDK from its NPM package, -* creates an instance of the SDK and connects it to the Kuzzle Backoffice running on `localhost` (and selects the `playground` as default index), +* creates an instance of the SDK, +* connects the SDK to a remote Kuzzle server running on `localhost` (and selects the `playground` as default index), * creates the `playground` index, * creates the `mycollection` collection (within the `playground` index), * disconnect from Kuzzle to end the script. @@ -144,23 +144,22 @@ Create a `create.js` file with following code: ```javascript const Kuzzle = require('kuzzle-sdk') -// connect to the Kuzzle server +// create a new Kuzzle SDK object const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'}) // get message from command line arguments const message = {message: process.argv[2]} -kuzzle.once('connected', () => { - kuzzle.collection('mycollection') - .createDocumentPromise(message) - .then(res => { - console.log('the following document has been successfully created:\n', message) - }) - .catch(err => { - console.error(err.message) - }) - .finally(() => kuzzle.disconnect()) -}) +kuzzle + .connectPromise() + .then(() => kuzzle.collection('mycollection').createDocumentPromise(message)) + .then(res => { + console.log('the following document has been successfully created:\n', message) + }) + .catch(err => { + console.error(err.message) + }) + .finally(() => kuzzle.disconnect()) ``` This code does the following: @@ -197,7 +196,7 @@ Open a new termnial in the playground directory you created before and create th ```javascript const Kuzzle = require('kuzzle-sdk') -// connect to the Kuzzle server +// create a new kuzzle object const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'}) // create a reference to the data collection @@ -211,10 +210,16 @@ const filter = { } // create a subscription on the collection matching given filters -collection.subscribe(filter, result => { +collection + .subscribe(filter, result => { // this function is called each time kuzzle notifies us with a document matching our filters - console.log('message received from kuzzle:', result) -}) + console.log('Message received from kuzzle:', result) + }) + .onDone(() => console.log('Subscription active. Waiting for messages...')) + +// Connects the client to a remote Kuzzle server and plays the previously +// configured subscriptions +kuzzle.connect() ``` Run your file in NodeJS diff --git a/src/sdk-reference/essentials/offline-first.md b/src/sdk-reference/essentials/offline-first.md index 8c106bc3e..a96c2a0bd 100644 --- a/src/sdk-reference/essentials/offline-first.md +++ b/src/sdk-reference/essentials/offline-first.md @@ -15,7 +15,7 @@ Our goal is to provide our users with the right tools to handle such situations. There are two ways to handle a network disconnection: -* Stop all further communication with Kuzzle and invalidate the current instance and all its children. The application will have to manually instantiate a new Kuzzle object once the network has recovered. To do so, simply pass the ``autoReconnect`` option to ``false`` when starting a new Kuzzle instance. +* Stop all further communication with Kuzzle and invalidate the current instance and all its children. The application will have to manually reconnect once the network has recovered. To do so, simply pass the ``autoReconnect`` option to ``false`` when starting a new Kuzzle instance. * Reconnect automatically to Kuzzle when possible, and enter *offline mode* in the meantime. This is the default behavior. Offline mode simply refers to the time between a ``disconnected`` and a ``reconnected`` event (see [Events]({{ site_base_path }}sdk-reference/essentials/events)). @@ -46,7 +46,7 @@ The queue itself can be configured using the ``queueTTL`` and ``queueMaxSize`` o --- -## Filtering requests to be queued +## Filter requests to be queued After request queuing is activated, by default, all requests are queued. diff --git a/src/sdk-reference/kuzzle/connect.md b/src/sdk-reference/kuzzle/connect.md index 38ff53c68..816dcce3b 100644 --- a/src/sdk-reference/kuzzle/connect.md +++ b/src/sdk-reference/kuzzle/connect.md @@ -11,11 +11,32 @@ title: connect # connect ```js -kuzzle.connect(); +// Using callbacks (NodeJS or Web Browser) +kuzzle.connect(function (err, kuzzle) { + if (err) { + console.log('Unable to connect: ', err.message); + } else { + console.log('Connected!'); + } +}); + +// Using promises (NodeJS only) +kuzzle.connectPromise() + .then(() => console.log('Connected!')); ``` ```java -kuzzle.connect(); +kuzzle.connect(new ResponseListener() { + @Override + public void onSuccess(Void object) { + // invoked once connected + } + + @Override + public void onError(JSONObject error) { + // Handle connection error + } +}); ``` ```php @@ -24,17 +45,10 @@ kuzzle.connect(); // not implemented (this SDK uses HTTP and is thus stateless) ``` -Connects to the Kuzzle instance using the provided `host` in the constructor. -Has no effect if ``connect`` is set to ``auto``, unless ``disconnect`` has been called first. - ---- - -## Return value - -Returns the `Kuzzle` object to allow chaining. +Connects to the Kuzzle instance using the `host` and `port` parameters provided to the constructor. --- ## Callback response -If a callback has been provided to the `Kuzzle` constructor, it will be called with the `Kuzzle` instance once successfully connected +Resolves with nothing once connected to a remote Kuzzle server. diff --git a/src/sdk-reference/kuzzle/index.md b/src/sdk-reference/kuzzle/index.md index eca3f2490..67070e84b 100644 --- a/src/sdk-reference/kuzzle/index.md +++ b/src/sdk-reference/kuzzle/index.md @@ -20,11 +20,6 @@ var kuzzle = new Kuzzle('localhost', { autoReconnect: true, port: 7512 }); - -// A callback is also available and will be invoked once connected to the Kuzzle instance: -kuzzle = new Kuzzle('localhost', function (err, res) { - // ... -}); ``` ```java @@ -37,17 +32,7 @@ options.setDefaultIndex("some index") .setAutoReconnect(true), .setPort(7512); -Kuzzle kuzzle = new Kuzzle("localhost", options, new ResponseListener() { - @Override - public void onSuccess(Void object) { - // invoked once connected, object contains the kuzzle instance - } - - @Override - public void onError(JSONObject error) { - // Handle connection error - } -}); +Kuzzle kuzzle = new Kuzzle("localhost", options); ``` ```php @@ -66,13 +51,12 @@ This is the main entry point to communicate with Kuzzle. Every other objects inh --- -## Kuzzle(host, [options], [callback]) +## Kuzzle(host, [options]) | Arguments | Type | Description | |---------------|---------|----------------------------------------| | ``host`` | string | The server name (or the IP address) of a Kuzzle instance | | ``options`` | JSON object | Optional Kuzzle connection configuration | -| ``callback`` | function | Optional callback | --- @@ -84,7 +68,6 @@ This is the main entry point to communicate with Kuzzle. Every other objects inh | ``autoReconnect`` | boolean | Automatically reconnect after a connection loss | ``true`` | | ``autoReplay`` | boolean | Automatically replay queued requests on a ``reconnected`` event | ``false`` | | ``autoResubscribe`` | boolean | Automatically renew all subscriptions on a ``reconnected`` event | ``true`` | -| ``connect`` | string | Manually or automatically connect to the Kuzzle instance | ``auto`` | | ``defaultIndex`` | string | Set the default index to use | | | ``offlineMode`` | string | Offline mode configuration | ``manual`` | | ``protocol`` | string | (Javascript only) Network protocol to use to connect to Kuzzle (``websocket`` | ``socketio``) | ``websocket``| @@ -126,18 +109,10 @@ This is the main entry point to communicate with Kuzzle. Every other objects inh **Notes:** -* if ``connect`` is set to ``manual``, the ``connect`` method will have to be called manually -* the kuzzle instance will automatically queue all requests, and play them automatically once a first connection is established, regardless of the ``connect`` or offline mode option values. +* newly instantiated Kuzzle objects automatically start in [offline mode]({{ site_base_path }}sdk-reference/essentials/offline-first/) * multiple methods allow passing specific ``volatile`` data. These ``volatile`` data will be merged with the global Kuzzle object ``volatile`` when sending the request, with the request specific ``volatile`` taking priority over the global ones. * the ``queueFilter`` property is a function taking a JSON object as an argument. This object is the request sent to Kuzzle, following the [Kuzzle API]({{ site_base_path }}api-documentation/query-syntax) format * if ``queueTTL`` is set to ``0``, requests are kept indefinitely * The offline buffer acts like a FIFO queue, meaning that if the ``queueMaxSize`` limit is reached, older requests are discarded to make room for new requests * if ``queueMaxSize`` is set to ``0``, an unlimited number of requests is kept until the buffer is flushed * the ``offlineQueueLoader`` must be set with a function, taking no argument, and returning an array of objects containing a `query` member with a Kuzzle query to be replayed, and an optional `cb` member with the corresponding callback to invoke with the query result - ---- - -## Callback response - -If the connection succeeds, resolves to the `Kuzzle` object itself. -If the `connect` option is set to `manual`, the callback will be called after the `connect` method is resolved.