To perform store operations, you must establish a network connection between your client code and the store. There are three pieces of information that you must provide:
The name of the store. The name provided here must be identical to the name used when the store was installed.
The network contact information for one or more helper hosts. These are the network name and port information for nodes currently running in the store. Multiple nodes can be identified. You can use one or many. Many does not hurt. The downside of using one is that the chosen host may be temporarily down, so it is a good idea to use more than one.
Identify the host and port where the proxy is running. You also do this using the configuration object.
If you are connecting to a secured store, you must also provide some authentication information. This is described in Setting the Security Properties for a Proxy Server.
For example, suppose you have an Oracle NoSQL Database store named "kvstore" and it has a node running on n1.example.org at port 5000. Further, suppose you are running your proxy on the localhost using port 7010. Then you would open and close a connection to the store in the following way:
//Include nosqldb-oraclejs module
var nosqldb = require('nosqldb-oraclejs');
// Create a configuration object
var configuration = new nosqldb.Configuration();
configuration.proxy.startProxy = false;
configuration.proxy.host = 'localhost:7010';
configuration.storeHelperHosts = ['n1.example.org:5000'];
configuration.storeName = 'kvstore';
// Create a store with the specified configuration
var store = nosqldb.createStore(configuration);
store.on('open', function () {
console.log('Store opened.');
// Perform store operations here
store.close();
}).on('close', function() {
console.log('Store closed.');
store.shutdownProxy();
}).on('error', function(error) {
console.log('Error in the store.');
console.log(error);
});
store.open();
If you are using a secure store, then your proxy server must first be configured to authenticate to the store. See Securing Oracle NoSQL Database Proxy Server for details.
Once your proxy server is capable of accessing the secure store,
you must at a minimum indicate which user your driver wants to
authenticate as when it performs store access. To do this, use
configuration.username.
For more information on using secure stores, see Working with a Secured Store .
//Include nosqldb-oraclejs module
var nosqldb = require('nosqldb-oraclejs');
// Create a configuration object
var configuration = new nosqldb.Configuration();
configuration.proxy.startProxy = false;
configuration.proxy.host = 'localhost:7010';
configuration.storeHelperHosts = ['n1.example.org:5000'];
configuration.storeName = 'kvstore';
configuration.username = 'jsapp-username';
// Create a store with the specified configuration
var store = nosqldb.createStore(configuration);
store.on('open', function () {
console.log('Store opened.');
// Perform store operations here
store.close();
}).on('close', function() {
console.log('Store closed.');
store.shutdownProxy();
}).on('error', function(error) {
console.log('Error in the store.');
console.log(error);
});
store.open();
Your client code can start the proxy server on the local
host when it opens the store using
configuration.proxy.startProxy. To do this,
set its value to true and also specify the location of the kvproxy.jar
using configuration.proxy.KVPROXY_JAR. Also,
specify the location of the kvclient.jar using
configuration.proxy.KVCLIENT_JAR.
For example:
var nosqldb = require('nosqldb-oraclejs');
var configuration = new nosqldb.Configuration();
configuration.proxy.startProxy = true;
configuration.proxy.host = 'localhost:7010';
configuration.proxy.KVCLIENT_JAR =
'node_modules/kvproxy/kvclient.jar';
configuration.proxy.KVPROXY_JAR =
'node_modules/kvproxy/kvproxy.jar';
configuration.storeHelperHosts = ['n1.example.org:5000'];
configuration.storeName = 'kvstore';
var store = nosqldb.createStore(configuration);
store.on('open', function () {
console.log('Store opened.');
// Perform store operations here
store.close();
}).on('close', function() {
console.log('Store closed.');
store.shutdownProxy();
}).on('error', function(error) {
console.log('Error in the store.');
console.log(error);
});
store.open();
Be aware that if your proxy is connecting to a secure store,
you also must indicate which user to authenticate as, and you must
indicate where the security properties file is located on the
host where the proxy server is running.
To do this, use
configuration.username and
configuration.proxy.securityFile.
var nosqldb = require('nosqldb-oraclejs');
var configuration = new nosqldb.Configuration();
configuration.proxy.startProxy = true;
configuration.proxy.host = 'localhost:7010';
configuration.proxy.KVCLIENT_JAR =
'node_modules/kvproxy/kvclient.jar';
configuration.proxy.KVPROXY_JAR =
'node_modules/kvproxy/kvproxy.jar';
configuration.storeHelperHosts = ['n1.example.org:5000'];
configuration.storeName = 'kvstore';
configuration.username = 'jsapp-username';
configuration.proxy.securityFile = 'KVROOT/security/client.security';
var store = nosqldb.createStore(configuration);
store.on('open', function () {
console.log('Store opened.');
// Perform store operations here
store.close();
}).on('close', function() {
console.log('Store closed.');
store.shutdownProxy();
}).on('error', function(error) {
console.log('Error in the store.');
console.log(error);
});
store.open();
For information on configuring your proxy server to connect to a secure store, see Securing Oracle NoSQL Database Proxy Server.
The
Configuration
class is used to
describe properties about a Store
handle. Most of the properties are optional; however, you must
identify the store name and helper hosts.
The properties that you can provide using
Configuration
are:
connectionAttempts
The number of attempts the driver will make to connect to the server before failing.
defaultConsistency
Consistency is a property that describes how likely it is that a record read from a replica node is identical to the same record stored on a master node. For more information, see Consistency Guarantees.
defaultDurability
Durability is a property that describes how likely it is that a write operation performed on the master node will not be lost if the master node is lost or is shut down abnormally. For more information, see Durability Guarantees.
iteratorBufferSize
The number of rows buffered by Iterators or Streams.
proxy
Proxy server configuration. See the next section.
readZones
An array of zone names to be used as read zones. For more information on read zones, see the Oracle NoSQL Database Administrator's Guide.
requestTimeout
Configures the amount of time the client will wait for an operation to complete before it times out.
storeHelperHosts
Helper hosts are hostname/port pairs that identify where nodes within the store can be contacted. Multiple hosts can be identified using an array of strings. Typically an application developer will obtain these hostname/port pairs from the store's deployer and/or administrator. For example:
var config = new nosqldb.Configuration(); config.storeHelperHosts=['n1.example.org:3333','n2.example.org:3333']
storeName
Identifies the name of the store.
username
The name of the user you want to authenticate to the store as. This property should only be used when your proxy server is configured to connect to a secure store.
The
ProxyConfiguration
class is used to describe properties about the proxy server you
are using to connect to the store.
The number of properties you can specify using this class are too numerous to describe here (see the Oracle NoSQL node.js Driver for Tables API Reference for a complete listing), but the most common properties you will set are:
startProxy
Boolean indicating whether the driver should automatically start the proxy server if it is not already running.
host
The hostname:port pair used to connect to the proxy server.
securityFile
The properties file containing the security information required to connect to a secure store. For information on secure stores and security properties, see Setting the Security Properties for a Proxy Server.
KVCLIENT_JAR
The path where the kvclient.jar file is located. This information is only required if you are attempting to automatically start the proxy server.
KVPROXY_JAR
The path where the kvproxy.jar file is located. This information is only required if you are attempting to automatically start the proxy server.