Skip to content

Configuration

Jump to bottom Edit New page
Mustafa Iman edited this page Feb 21, 2018 · 2 revisions

You can configure Hazelcast Node.js Client declaratively (JSON) or programmatically (API).

  • Programmatic configuration
  • Declarative configuration (JSON file)

Programmatic Configuration

Refer to Hazelcast Node.js Client API Docs for programmatic configuration.

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 environment variable HAZELCAST_CLIENT_CONFIG. If it exists, the client looks for configuration file in specified location.
  2. Current working directory: If there is no environment variable set, client tries to load hazelcast-client.json from current working directory.
  3. Default configuration: If above methods fail, the client starts with default configuration.

A sample JSON config file is below:

{
    "group": {
        "name": "hazel",
        "password": "cast"
    },
    "properties": {
        "hazelcast.client.heartbeat.timeout": 10000,
        "hazelcast.client.invocation.retry.pause.millis": 4000,
        "hazelcast.client.invocation.timeout.millis": 180000,
        "hazelcast.invalidation.reconciliation.interval.seconds": 50,
        "hazelcast.invalidation.max.tolerated.miss.count": 15,
        "hazelcast.invalidation.min.reconciliation.interval.seconds": 60
    },
    "network": {
        "clusterMembers": [
            "127.0.0.1:5701"
        ],
        "smartRouting": true,
        "connectionTimeout": 6000,
        "connectionAttemptPeriod": 4000,
        "connectionAttemptLimit": 3
    }
}

Group Configuration

Clients should provide a group name and password in order to connect to the cluster. You can configure them as shown below.

{
    "group": {
        "name": "hazel",
        "password": "cast"
    }
}

Client Network

All network related configuration of Hazelcast Java Client is performed via the network element in the declarative configuration file. Let's first give the an example for these network configuration. Then we will look at its properties.

{
    "network": {
        "clusterMembers": [
            "127.0.0.9",
            "127.0.0.2:5702"
        ],
        "smartRouting": false,
        "connectionTimeout": 6000,
        "connectionAttemptPeriod": 4000,
        "connectionAttemptLimit": 3,
        "ssl": {
            "enabled": true,
            "factory": {
                "path": "path/to/file",
                "exportedName": "exportedName",
                "properties": {
                    "userDefinedProperty1": "userDefinedValue"
                }
            }
        }
    }
}

Configuring address list

Address list is the initial list of cluster addresses to which the client will connect. The client uses this list to find an alive member. Although it may be enough to give only one address of a member in the cluster (since all members communicate with each other), it is recommended that you give the addresses for all the members.

{
    "network": {
        "clusterMembers": [
            "127.0.0.9",
            "127.0.0.2:5702"
        ]
    }
}

If the port part is omitted, then 5701, 5702, and 5703 will be tried in random order.

Default address is 127.0.0.1.

Setting smart routing

Smart routing defines whether the client mode is smart or unisocket. The following is an example configuration.

{
    "network": {
        "smartRouting": true
    }
}

Default is smart routing mode.

Setting connection timeout

Connection timeout is the timeout value in milliseconds for members to accept client connection requests.

{
    "network": {
        "connectionTimeout": 6000
    }
}

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, 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.

{
    "network": {
        "connectionAttemptLimit": 3
    }
}

Default value is 2.

Setting connection attempt period

Connection timeout period is the duration in milliseconds between the connection attempts defined by connection attempt limit.

{
    "network": {
        "connectionAttemptPeriod": 4000
    }
}

Default value is 3000.

Enabling client tls/ssl

You can use TLS/SSL to secure the connection between the client and the members. If you want TLS/SSL enabled for the client-cluster connection, you should set a 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 tls.connect of Node.js. There are two ways to provide this object to the client;

  1. Using builtin BasicSSLOptionsFactory bundled with the client.
  2. Writing a SSLOptionsFactory.

1. Using builtin BasicSSLOptionsFactory

Hazelcast Node.js Client includes a utility factory class that creates neccessary options object out of supplied properties. All you need to do is specify your factory as BasicSSLOptionsFactory and provide the following options.

certPath
caPath
servername
rejectUnauthorized
ciphers

Refer to tls.connect of Node.js for meaning of each option.

certPath and caPath defines file path to respective file that store such information.

{
    "network": {
        "ssl": {
            "enabled": true,
            "factory": {
                "exportedName": "BasicSSLOptionsFactory",
                "properties": {
                    "caPath": "ca.pem",
                    "certPath": "cert.pem",
                    "rejectUnauthorized": false
                }
            }
        }
    }
}

If this options are not enough for your application, you may write you own options factory and instruct the client to get the options from it.

Writing a SSL options factory

In order to use full range of options provided to tls.connect of Node.js, you may write your own factory object.

{
    "network": {
        "ssl": {
            "enabled": true,
            "factory": {
                "path": "my_factory.js",
                "exportedName": "SSLFactory",
                "properties": {
                    "caPath": "ca.pem",
                    "certPath": "cert.pem",
                    "keepOrder": true
                }
            }
        }
    }
}

my_factory.js

function SSLFactory() {
}
 
SSLFactory.prototype.init = function(props) {
    this.keyPath = props.keyPath;
    this.caPath = props.caPath;
    this.keepOrder = props.userDefinedProperty1;
};
 
SSLFactory.prototype.getSSLOptions = function() {
    var sslOpts = {
        servername: 'foo.bar.com',
        rejectUnauthorized: true,
        cert: fs.readFileSync(this.keyPath),
        ca: fs.readFileSync(this.caPath)
    };
    if (this.keepOrder) {
        sslOpts.honorCipherOrder = true;
    }
    return sslOpts;
}
exports.SSLFactory = SSLFactory;

The client loads MyFactory.js at runtime and creates an instance of SSLFactory. It then, calls init method with the properties section in JSON config. Lastly, the client calls getSSLOptions method if SSLFactory to create the options object.

For information about path resolution, refer to Path Resolution

Serialization configuration

This section shows how to configure Hazelcast serialization declaratively. Please refer to Hazelcast Docs and Node.js client readme for learning about serialization.

Serialization configuration is as follows:

{
"serialization": {
        "defaultNumberType": "integer",
        "isBigEndian": false,
        "dataSerializableFactories": [
            {
                "path": "path/to/file",
                "exportedName": "exportedName",
                "factoryId": 0
            }
        ],
        "portableFactories": [
            {
                "path": "path/to/file",
                "exportedName": "exportedName",
                "factoryId": 1
            }
        ],
        "portableVersion": 1,
        "globalSerializer": {
            "path": "path/to/file",
            "exportedName": "exportedName"
        },
        "serializers": [
            {
                "path": "path/to/custom",
                "exportedName": "CustomSerializer1",
                "typeId": 2
            },
            {
                "path": "path/to/custom",
                "exportedName": "CustomSerializer2",
                "typeId": 3
            }
        ]
    }
}

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 clients in different languages, you need to map number type to one of the numeric types recognized by 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 module is included with Hazelcast Node.js client.

Related section: Path Resolution

Configuring near cache

You may configure near caches for your maps as the following:

{
    "nearCaches": [
        {
            "name": "nc-map",
            "invalidateOnChange": false,
            "maxIdleSeconds": 2,
            "inMemoryFormat": "object",
            "timeToLiveSeconds": 3,
            "evictionPolicy": "lru",
            "evictionMaxSize": 3000,
            "evictionSamplingCount": 4,
            "evictionSamplingPoolSize": 8
        }
    ]
}

nearCaches is an array that includes one configuration object for each near cache in the client. For meanings of configuration options refer to NearCacheConfig API Documentation

Path resolution and object loading

For configuration elements that require you to specify a code piece, you will need to specify the path to code and the name of the exported element that you want the client to use. This configuration is set by the following

{
    "path": "path/to/file",
    "exportedName": "MyObject"
}

In above configuration path shows the address to the file that you want the client to load. Unless this is an absolute path, it is relative to the location of hazelcast-config.json file.

In Javascript you can define and export as many objects as you want in a single file. Above configuration element is designed to load only one specified object from a file. Therefore exportedName specified the name of desired object.

Let's say your project directory structure is like the following:

my_app/
my_app/index.js
my_app/factory_utils.js
my_app/hazelcast-client.json
my_app/node_modules/
my_app/node_modules/hazelcast-client

In factory_utils.js, you have multiple exported functions.

exports.utilityFunction = function() {...}
exports.MySSLFactory = function() {...}

In order to load MySSLFactory in your ssl configuration, you should set path and exportedName as factory_utils.js and MySSLFactory respectively.

If you have only one export as the default export from factory_utils.js, just skip exportedName property and the client will load the default export from the file.

Add a custom footer
Add a custom sidebar
Clone this wiki locally