Getting Started with the Node.js OJAI Client
This section describes the software required to run the Node.js OJAI client, client/server security, and how to specify your connection string. It also provides links to documentation that shows you how to write Node.js OJAI applications.
The Node.js OJAI client is available starting in the EEP 6.0 release.
Software Requirements
You must have the following software installed to run the client:
Client Software | Installation Notes |
---|---|
Node.js | Supported versions:
|
Node.js OJAI client | Install the client by using the following command:
|
You also must have access to the following software:
- MapR/Data Fabric cluster 6.1 or later
- Data Access Gateway 2.0 or later
To run a Node.js OJAI application, you simply need to install and configure the Data Access Gateway:
Node.js OJAI Client Security
The client supports username/password authentication. The initial connection (and token renewal) use these credentials. Subsequent communication uses JWT.
When connecting to a secure cluster, the client uses:
- X.509 certificates to authenticate with the Data Access Gateway
- TLS v1.2 to encrypt communication between the client and the Data Access Gateway
Node.js OJAI Client Connection String
The string you use to connect your OJAI client to the cluster must have the following format:
"[ojai:mapr:thin:v1@]<hostname>[:<port>][?<option_name>=<option_value>;...]"
The prefix ojai:mapr:thin:v1@
is optional.
<hostname>
- Name of the Data Access Gateway host. For information about the host name, see Configuring SSL for OJAI Clients.
<port>
- Port number (see Ports Used by HPE Ezmeral Data Fabric Software) that gRPC clients use to connect to
the Data Access Gateway
Default: 5678
auth=<scheme_name>
-
The authentication scheme for the current connection; currently, only
basic
user=<username>
-
The user name for
basic
authentication password=<password>
-
The password for
basic
authentication ssl=true|false
-
Whether to establish a secure connection using SSL/TLS
An error is returned if there is a mismatch between your client and Data Access Gateway security settings. The default for this option is
true
, which is the required setting if connecting to a secure Data Access Gateway. If connecting to a non-secure Data Access Gateway, set it tofalse
.If set to
false
, the other SSL parameters are ignored.Note that the
grpc.service.ssl.enabled
property controls the SSL setting for the Data Access Gateway. For more information, see Administering the Data Access Gateway. sslCA=<path to PEM file containing CA certificate>
-
Path to a local file containing Certificate Authority (CA) signed certificates in PEM format. For information about the PEM format, see Configuring SSL for OJAI Clients.
Required when the
ssl
option is set totrue
. sslTargetNameOverride=<CA certificate common name>
-
Fully qualified domain name specified in the SSL server certificate, which is different from the
<hostname>
in the connection string.For example, imagine that you are using the following:
- Public network host name is
ec2-203-0-113-25.compute-1.amazonaws.com
. - Internal DNS is
node1.mydomain.com
. - CA signed certificate is issued to
node1.mydomain.com
.
Using these names, you must specify the following connection string:
"ec2-203-0-113-25.compute-1.amazonaws.com:5678?ssl=true;sslCA=/opt/app/conf/rootca.pem;sslTargetNameOverride=node1.mydomain.com"
Other examples of connection strings are the following:
"ojai:mapr:thin:v1@localhost:5678?auth=basic;user=fred;password=george;sslCA=/opt/app/conf/rootca.pem" "localhost:5678?ssl=false;auth=basic;user=fred;password=george"
- Public network host name is
Node.js OJAI Connection Retry Options
If your OJAI client cannot connect to your cluster, it waits 10 ms. After 10 ms, it makes a second connection attempt. If that fails, it continues the attempts up to a configurable number of retries. The following parameters control the number of retries and the wait time between attempts:
Connection Option Parameter | Description | Default Value |
---|---|---|
ojai.mapr.rpc.wait-multiplier |
Multiplier that determines the wait time for subsequent attempts after the initial 10 ms wait. The previous wait time is multiplied by this parameter. | 1000 |
ojai.mapr.rpc.wait-max-attempt |
Maximum wait time between attempts regardless of the multiplier parameter | 18000 ms |
ojai.mapr.rpc.max-retries |
Maximum number of retry attempts | 7 |
The following examples demonstrate how these parameters work, including the default case:
Attempt # | Wait Time (in ms) for each Retry Attempt | |
---|---|---|
Default Parameters:
|
|
|
1 | 10 | 10 |
2 | 10*1000 = 10000 | 10*2 = 20 |
3 | 18000 10000*1000 = 10,000,000, which exceeds 18000 | 20*2 = 40 |
4 | 18000 | 40*2 = 80 |
5 | 18000 | 90 80*2 = 160, which exceeds 90 |
6 | 18000 | Error |
7 | 18000 | N/A |
8 | Error | N/A |
To set these retry options, you must pass them in the
ConnectionManager.getConnection
call:
const connectionString = 'localhost:5678?' + 'auth=basic;' + 'user=mapr;' + 'password=mapr;' + 'ssl=true;' + 'sslCA=/opt/mapr/conf/ssl_truststore.pem;' + 'sslTargetNameOverride=node1.mapr.com'; const options = { 'ojai.mapr.rpc.wait-multiplier': 5, 'ojai.mapr.rpc.wait-max-attempt': 50, 'ojai.mapr.rpc.max-retries': 3 } let connection; ConnectionManager.getConnection(connectionString,options) .then((conn) => { connection = conn; // Get a store return connection.getStore('/demo_table'); })
Writing Node.js OJAI Applications
For information about writing a Node.js OJAI application, see the Node.js sections in the following topics:
- Querying in OJAI Applications
-
Provides an introduction to the basic flow of an OJAI application that queries a HPE Ezmeral Data Fabric Database JSON table
- Examples: Querying JSON Documents
-
Contains code samples of OJAI applications that query HPE Ezmeral Data Fabric Database JSON tables
- Managing JSON Documents
-
Describes how to perform CRUD (create, query, update, and delete) operations on JSON documents in HPE Ezmeral Data Fabric Database JSON tables