Obtaining a NoSQL Handle

Learn how to access tables using Oracle NoSQL Database Drivers. Start developing your application by creating a NoSQL Handle. Use the NoSQLHandle to access the tables and execute all operations.

To create a connection represented by a NoSQLHandle, obtain a handle using the NoSQLHandleFactory.createNoSQLHandle method and the NoSQLHandleConfig class. The NoSQLHandleConfig class allows an application to specify the handle configuration. See the Java API Reference Guide to learn more.

Use the following code to obtain a NoSQL handle:
/* Configure a handle for the desired Region and AuthorizationProvider.
 * By default this SignatureProvider constructor reads authorization
 * information from ~/.oci/config and uses the default user profile and
 * private key for request signing. Additional SignatureProvider
 * constructors are available if a config file is not available or
 * desirable. 
 */
AuthorizationProvider ap = new SignatureProvider();

/* Use the us-ashburn-1 region */
NoSQLHandleConfig config = new NoSQLHandleConfig(Region.US_ASHBURN_1, ap);
config.setAuthorizationProvider(ap);

/* Sets a default compartment for all requests from this handle. This 
 * may be overridden in individual requests or by using a
 * compartment-name prefixed table name.
 */
config.setDefaultCompartment("mycompartment");

// Open the handle
NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);

// Use the handle to execute operations

A handle has memory and network resources associated with it. Use the NoSQLHandle.close method to free up the resources when your application is done using the handle.

To minimize network activity and resource allocation and deallocation overheads, it's best to avoid creating and closing handles repeatedly. For example, creating and closing a handle around each operation would result in poor application performance. A handle permits concurrent operations, so a single handle is sufficient to access tables in a multi-threaded application. The creation of multiple handles incurs additional resource overheads without providing any performance benefit.

A handle is created by first creating a borneo.NoSQLHandleConfig instance to configure the communication endpoint, authorization information, as well as default values for handle configuration. borneo.NoSQLHandleConfig represents a connection to the service. Once created it must be closed using the method borneo.NoSQLHandle.close() in order to clean up resources. Handles are thread-safe and intended to be shared.

An example of acquiring a NoSQL Handle for the Oracle NoSQL Cloud Service:
from borneo import NoSQLHandle, NoSQLHandleConfig, Regions
from borneo.iam import SignatureProvider
# create AuthorizationProvider
provider = SignatureProvider()
# create handle config using the correct desired region
# as endpoint, add a default compartment.
config = NoSQLHandleConfig(Regions.US_ASHBURN_1).
set_authorization_provider(provider).
set_default_compartment('mycompartment')
# create the handle
handle = NoSQLHandle(config)

Note:

To reduce resource usage and overhead of handle creation it is best to avoid excessive creation and closing of borneo.NoSQLHandle instances.
The first step in any Oracle NoSQL Database Cloud Service go application is to create a nosqldb.Client handle used to send requests to the service. Instances of the Client handle are safe for concurrent use by multiple goroutines and intended to be shared in a multi-goroutines application. The handle is configured using your credentials and other authentication information.
provider, err := iam.NewSignatureProviderFromFile(cfgfile, profile, passphrase, compartment)
cfg := nosqldb.Config
{ 
   Region: "us-phoenix-1", AuthorizationProvider: provider,
}
client, err := nosqldb.NewClient(cfg)
// use client for all NoSQL DB operations

The NoSQLClient class represents the main access point to the service. To create instance of NoSQLClient you must provide appropriate configuration information. This information is represented by a Config object and can be provided to the constructor of the NoSQLClient class. Alternatively, you may choose to store this information in a JSON configuration file and the constructor of NoSQLClient with the path (absolute or relative to the application's current directory) to that file. For method details, see NoSQLClient class.

The first example below creates an instance of NoSQLClient for the Cloud Service using the Config object. It also adds a default compartment and overrides default timeout values in the configuration object.
import { NoSQLClient, Region } from 'oracle-nosqldb';

let client = new NoSQLClient({
    region: Region.US_ASHBURN_1,
    timeout: 20000,
    ddlTimeout: 40000,
    compartment: 'mycompartment',
    auth: {
        iam: {
            configFile: '~/myapp/.oci/config',
            profileName: 'Jane'
        }
    }
});

The second example stores the same configuration in a JSON file config.json and uses it to create NoSQLClient instance.

Sample config.json file:
{ 
"region": "US_ASHBURN_1",
 "timeout": 20000,
 "ddlTimeout": 40000,
 "compartment": "mycompartment", 
 "auth": { 
    "iam": { 
       "configFile": "~/myapp/.oci/config",
       "profileName": "Jane"
    } 
  }
}
Application code:
import { NoSQLClient } from 'oracle-nosqldb';
let client = new NoSQLClient('config.json');

Class NoSQLClient represents the main access point to the service. To create an instance of NoSQLClient you need to provide appropriate configuration information. This information is represented by NoSQLConfig class which instance can be provided to the constructor of NoSQLClient. Alternatively, you may choose to store the configuration information in a JSON configuration file and use the constructor of NoSQLClient that takes the path (absolute or relative to current directory) to that file.

The first example below creates instance of NoSQLClient for the Cloud Service using NoSQLConfig. It also adds a default compartment and overrides some default timeout values in NoSQLConfig.
var client = new NoSQLClient(
    new NoSQLConfig
    {
        Region = Region.US_ASHBURN_1,
        Timeout = TimeSpan.FromSeconds(10),
        TableDDLTimeout = TimeSpan.FromSeconds(20),
        Compartment = "mycompartment",
        AuthorizationProvider = new IAMAuthorizationProvider(
            "~/myapp/.oci/config", "Jane")
    });

The second example stores the same configuration in a JSON file config.json and uses it to create NoSQLClient instance.

config.json
{
    "Region": "us-ashburn-1",
    "Timeout": 20000,
    "TableDDLTimeout": 40000,
    "compartment": "mycompartment",
    "AuthorizationProvider":
    {
        "AuthorizationType": "IAM",
        "ConfigFile": "~/myapp/.oci/config",
        "ProfileName": "Jane"
    }
}
Application code:
var client = new NoSQLClient("config.json");

Related Topics