From 28acb2165e07e865c017d741c63d53d0dcdaedfe Mon Sep 17 00:00:00 2001 From: furkansenharputlu Date: Tue, 31 Jul 2018 15:13:13 +0300 Subject: [PATCH] update readme and add cloud discovery sample (#320) --- CONFIG.md | 48 ++++++++++++++----- README.md | 1 + code_samples/README.md | 2 + code_samples/hazelcast_cloud_discovery.js | 57 +++++++++++++++++++++++ 4 files changed, 96 insertions(+), 12 deletions(-) create mode 100644 code_samples/hazelcast_cloud_discovery.js diff --git a/CONFIG.md b/CONFIG.md index 928fe6d43..c01b8c684 100644 --- a/CONFIG.md +++ b/CONFIG.md @@ -20,7 +20,7 @@ Refer to [Hazelcast Node.js Client API Docs](http://hazelcast.github.io/hazelcas # Declarative Configuration (JSON) For declarative configuration, the Hazelcast client looks at the following places for the client configuration file. -1. Environment variable: The client first looks for the environment variable `HAZELCAST_CLIENT_CONFIG`. If it exists, +1. Environment variable: The client first looks for the environment variable `HAZELCAST_CLIENT_CONFIG`. If it exists, the client looks for the configuration file in the specified location. 2. Current working directory: If there is no environment variable set, the client tries to load `hazelcast-client.json` from the current working directory. @@ -147,7 +147,7 @@ Default value is 5000 milliseconds. ### Setting Connection Attempt Limit While the client is trying to connect initially to one of the members in the address list, that member -might not be available at that moment. Instead of giving up, throwing an error and stopping the client, +might not be available at that moment. Instead of giving up, throwing an error and stopping the client, the client will retry as many as connection attempt limit times. This is also the case when the previously established connection between the client and that member goes down. @@ -178,10 +178,10 @@ Default value is 3000. ### Enabling Client TLS/SSL You can use TLS/SSL to secure the connection between the client and members. If you want TLS/SSL enabled -for the client-cluster connection, you should set an SSL configuration. Once set, the connection (socket) is +for the client-cluster connection, you should set an SSL configuration. Once set, the connection (socket) is established out of an `options` object supplied by the user. -Hazelcast Node.js Client uses a user supplied SSL `options` object to pass to +Hazelcast Node.js Client uses a user supplied SSL `options` object to pass to [`tls.connect` of Node.js](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback). There are two ways to provide this object to the client: @@ -245,7 +245,7 @@ An example configuration: "exportedName": "SSLFactory", "properties": { "caPath": "ca.pem", - "keyPath": "key.pem", + "keyPath": "key.pem", "certPath": "cert.pem", "keepOrder": true } @@ -262,14 +262,14 @@ And your own factory, `My_Factory.js`: ```javascript function SSLFactory() { } - + SSLFactory.prototype.init = function(props) { this.caPath = props.caPath; this.keyPath = props.keyPath; this.certPath = props.certPath; this.keepOrder = props.userDefinedProperty1; }; - + SSLFactory.prototype.getSSLOptions = function() { var sslOpts = { servername: 'foo.bar.com', @@ -291,6 +291,30 @@ the properties section in the JSON configuration file. Lastly, the client calls For information about the path resolution, please refer to the [Path Resolution](#path-resolution-and-object-loading) section. +### Enabling Hazelcast Cloud Discovery +The purpose of Hazelcast Cloud Discovery is to provide clients to use IP addresses provided by `hazelcast orchestrator`. To enable Hazelcast Cloud Discovery, specify a token for the `discoveryToken` field and set the `enabled` field to "true". + +Hazelcast Cloud configuration is as follows: + +```json +{ + "group": { + "name": "hazel", + "password": "cast" + }, + + "network": { + "hazelcastCloud": { + "discoveryToken": "EXAMPLE_TOKEN", + "enabled": true + } + } +} + +``` + +To be able to connect to the provided IP addresses, you should use secure TLS/SSL connection between the client and members. Therefore, you should set an SSL configuration as described in the previous section. + ## Serialization Configuration This section shows how to configure Hazelcast serialization declaratively. Please refer to [Hazelcast IMDG Reference Manual](http://docs.hazelcast.org/docs/latest/manual/html-single/index.html#serialization) @@ -341,7 +365,7 @@ Serialization configuration is as follows: One important aspect of Node.js Client's serialization is `defaultNumberType`. Hazelcast servers use 4 different primitive numeric types; `int`, `long`, `float` and `double`. However, Javascript has only one numeric type which is `number`. Number is a floating point type. If you do not work with heterogenous clients (multiple languages), -you do not need to worry about this setting. However, if your numeric data is accessed by the clients in different +you do not need to worry about this setting. However, if your numeric data is accessed by the clients in different languages, you need to map `number` type to one of the numeric types recognized by the Java servers. Hazelcast handles type conversions automatically. Accepted values for `defaultNumberType` are `integer`, `float` and `double`. You may use `long` module for working with longs. [long module](https://www.npmjs.com/package/long) is included @@ -389,7 +413,7 @@ You may configure flake id generators as the following: ``` For meanings of configuration options refer to FlakeIdGenerator's API documantation [API Documentation](http://hazelcast.github.io/hazelcast-nodejs-client/api/current/docs) -> Note: Since Javascript cannot represent numbers greater than 2^53, you need to put long numbers in quotes as a string. +> Note: Since Javascript cannot represent numbers greater than 2^53, you need to put long numbers in quotes as a string. ## Composing Declarative Configuration @@ -435,12 +459,12 @@ shown below. } ``` -> Note: Use `import` element on top level of JSON hierarchy. +> Note: Use `import` element on top level of JSON hierarchy. ## Path Resolution and Object Loading -For configuration elements that require you to specify a code piece, you will need to specify the path to the +For configuration elements that require you to specify a code piece, you will need to specify the path to the code and name of the exported element that you want the client to use. This configuration is set as follows: ```json @@ -464,7 +488,7 @@ Let's say your project's directory structure is as follows: my_app/hazelcast-client.json my_app/node_modules/ my_app/node_modules/hazelcast-client - + In `factory_utils.js`, you have multiple exported functions. ```javascript diff --git a/README.md b/README.md index 57076e040..82ca1f7ec 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,7 @@ Hazelcast Node.js client supports the following data structures and features: * Hazelcast Native Serialization * Lifecycle Service * SSL connection support (requires enterprise server) +* Hazelcast Cloud Discovery # Installing the Client diff --git a/code_samples/README.md b/code_samples/README.md index ea68a7009..b36dc738e 100644 --- a/code_samples/README.md +++ b/code_samples/README.md @@ -14,6 +14,8 @@ This folder contains an extensive collection of Hazelcast Node.js Client code sa **global_serializer.js** — Creating and adding global serializer to serialization configuration. +**hazelcast-cloud-discovery.js** — Usage of cloud discovery. + **lifecycle_listener.js** — Listening to lifecycle events of the Hazelcast instance. **list.js** — Usage of distributed list. diff --git a/code_samples/hazelcast_cloud_discovery.js b/code_samples/hazelcast_cloud_discovery.js new file mode 100644 index 000000000..d61ddc21e --- /dev/null +++ b/code_samples/hazelcast_cloud_discovery.js @@ -0,0 +1,57 @@ +/* + * Copyright (c) 2008-2018, Hazelcast, Inc. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +var Client = require('hazelcast-client').Client; +var ClientConfig = require('hazelcast-client').Config.ClientConfig; +var fs = require('fs'); +var Path = require('path'); + + +function createClientConfigWithSSLOpts(key, cert, ca) { + var sslOpts = { + servername: 'Hazelcast-Inc', + rejectUnauthorized: true, + ca: fs.readFileSync(Path.join(__dirname, ca)), + key: fs.readFileSync(Path.join(__dirname, key)), + cert: fs.readFileSync(Path.join(__dirname, cert)) + }; + var cfg = new ClientConfig(); + cfg.networkConfig.sslOptions = sslOpts; + cfg.networkConfig.connectionAttemptLimit = 1000; + + var token = 'EXAMPLE_TOKEN'; + + cfg.networkConfig.cloudConfig.enabled = true; + cfg.networkConfig.cloudConfig.discoveryToken = token; + cfg.groupConfig.name = 'hazel'; + cfg.groupConfig.password = 'cast'; + return cfg; +} + +var cfg = createClientConfigWithSSLOpts('./key.pem', './cert.pem', './ca.pem'); + +Client.newHazelcastClient(cfg).then(function (hazelcastClient) { + var mp = hazelcastClient.getMap("testMap"); + + mp.put('key', 'value').then(function () { + return mp.get('key'); + }).then((res) => { + console.log(res); + }); +}); + + +