App Initialization Steps

All apps contain these initialization steps to configure interactions with a cluster:

  • Establish the app’s access to the Node.js API.
  • Establish access to a cluster.

Establish Access to the Node.js API

In your app, establish access to the Node.js API. Early in your app’s source code, include the following require statement:

var gemfire = require('gemfire');

Establish Access to a Cluster

As you develop your app, you will test the app with a cluster. That cluster may be a Cloud Cache service instance or a Pivotal GemFire cluster (for development). Your app connects to the cluster through the creation of a pool, by specifying the address (host name or IP address) and port number of one or more locators.

Prior to doing region operations, your app must follow these steps:

  1. Instantiate a CacheFactory, setting properties of interest such as log-file and the credentials needed for authentication. Instantiate a CacheFactory and set its characteristics:

    cacheFactory = gemfire.createCacheFactory()

    For a Cloud Cache service instance, parse the VCAP_SERVICES environment variable to extract the credentials that will be used for authentication. VCAP_SERVICES is a JSON string from the Cloud Cache service key provided to the app when deployed with cf push.

    Use the credentials to set the properties:

    cacheFactory.setAuthentication((properties, server) => {
        properties['security-username'] = username
        properties['security-password'] = password
    }, () => {
        console.log("Set auth done called!")

    The properties will be used in authentication when the app connects to the Cloud Cache service instance.

  2. Create a cache and use it to instantiate a PoolFactory. In a local development environment, specify the hostname and port for the locator:

    cache = await cacheFactory.create();
    poolFactory = await cache.getPoolManager().createFactory()
    poolFactory.addLocator('localhost', 10337)

    For a Cloud Cache service instance, start with the VCAP_SERVICES environment variable for locators. Here are the relevant lines of code for specifying locators from the book-service example at

    const vcap = JSON.parse(process.env.VCAP_SERVICES);
    const jsonPathLocators = "$.p-cloudcache[0].credentials.locators";
    var locators = JSONPath({path: jsonPathLocators, json: vcap})[0];
    var poolFactory = await cache.getPoolManager().createFactory()
    for (i = 0; i < locators.length; i++) {
       var serverPort = locators[i].split(/[[\]]/);
       poolFactory.addLocator(serverPort[0], parseInt(serverPort[1]));
  3. Create a named pool of network connections.

  4. Instantiate the client-side region. It is likely to be of type CACHING_PROXY or PROXY. Connect the region to its counterpart on the cluster’s servers:

    region = await cache.createRegion("test", { type: 'PROXY', poolName: 'pool' })

Once the connection pool and the region are in place, your app is ready to do operations on data in the region.

Node.js apps should always call close() on a cache instance, when the cache instance is no longer used, in order to prevent the leaks of resources (such as memory and N-API handles) that can occur in a Node.js environment.