About

Requirements

Installation

Install as a Project Dependency

<dependency>  <groupId>com.oracle.nosql.sdk</groupId>  <artifactId>nosqldriver</artifactId>  <version>5.4.17</version></dependency>

Download from GitHub

Documentation

Changes

Connect to the Oracle NoSQL Database

Connecting to the Oracle NoSQL Database Cloud Service

Authorizing with a User Principal

Authorizing with an Instance Principal

Authorizing with a Resource Principal

Connecting to the Oracle NoSQL Database On-premise

Connecting to the Oracle NoSQL Database Cloud Simulator

Logging

Quickstart

$ javac -cp <path-to-nosqldriver.jar> Quickstart.java

$ java -cp .:<path-to-nosqldriver.jar> Quickstart -service cloud -endpoint us-ashburn-1

$ java -cp .:<path-to-nosqldriver.jar> Quickstart -service onprem -endpoint http://localhost:8090

$ java -cp .:<path-to-nosqldriver.jar> Quickstart -service cloudsim -endpoint http://localhost:8080

/*- * Copyright (c) 2019, 2025 Oracle and/or its affiliates. All rights reserved. * * Licensed under the Universal Permissive License v 1.0 as shown at *  https://oss.oracle.com/licenses/upl/ */import java.io.IOException;import java.util.ArrayList;import oracle.nosql.driver.AuthorizationProvider;import oracle.nosql.driver.NoSQLHandle;import oracle.nosql.driver.NoSQLHandleConfig;import oracle.nosql.driver.NoSQLHandleFactory;import oracle.nosql.driver.iam.SignatureProvider;import oracle.nosql.driver.kv.StoreAccessTokenProvider;import oracle.nosql.driver.ops.GetRequest;import oracle.nosql.driver.ops.GetResult;import oracle.nosql.driver.ops.QueryRequest;import oracle.nosql.driver.ops.QueryResult;import oracle.nosql.driver.ops.PutRequest;import oracle.nosql.driver.ops.PutResult;import oracle.nosql.driver.ops.QueryIterableResult;import oracle.nosql.driver.ops.Request;import oracle.nosql.driver.ops.TableLimits;import oracle.nosql.driver.ops.TableRequest;import oracle.nosql.driver.values.MapValue;/** * A simple quickstart program to demonstrate Oracle NoSQL Database. * It does these things: * - create a table * - put a row * - get a row * - run a query using iterable/iterator * - run a query using partial results * - drop the table * * See the examples for more interesting operations. This quickstart is * intended to illustrate connecting to a service and performing a few * operations. * * This program can be run against: *  1. the cloud service *  2. the on-premises proxy and Oracle NoSQL Database instance, secure or *  not secure. *  3. the cloud simulator (CloudSim) * * To run: *   java -cp .:../lib/nosqldriver.jar Quickstart \ *      -service <cloud|onprem|cloudsim> -endpoint <endpoint-or-region> \ *      [-compartment <ocid>] * * The endpoint and arguments vary with the environment. * * This quick start does not directly support a secure on-premise * environment. See the examples for details on that environment. */public class Quickstart {    private String endpoint;    private String service;    /* required for Instance/Resource Principal auth and OKE workload identity */    private String compartment = null; // an OCID    /* alternative cloud authorization mechanisms */    private final static boolean useUserPrincipal = true;    private final static boolean useInstancePrincipal = false;    private final static boolean useResourcePrincipal = false;    private final static boolean useSessionToken = false;    private final static boolean useOkeWorkloadIdentity = false;    private Quickstart(String[] args) {        /*         * parse arguments         */        for (int i = 0; i < args.length; i++) {            if (args[i].equals("-service")) {                service = args[++i];            } else if (args[i].equals("-endpoint")) {                endpoint = args[++i];            } else if (args[i].equals("-compartment")) {                compartment = args[++i];            } else {                System.err.println("Unknown argument: " + args[i]);                usage();            }        }        if (service == null || endpoint == null) {            System.err.println("-service and -endpoint are required");            usage();        }    }    private static void usage() {        System.err.println(            "Usage: java -cp <path-to-nosqldriver.jar> Quickstart \\ \n" +            " -service <cloud|onprem|cloudsim> -endpoint <endpoint-or-region>" +            " \\ \n[-compartment <ocid>]");        System.exit(1);    }    private NoSQLHandle getHandle() {        NoSQLHandleConfig config = new NoSQLHandleConfig(endpoint);        if (compartment != null) {            config.setDefaultCompartment(compartment);        }        /*         * By default the handle will log to the console at level INFO.         * The default logger can be configured using a logging properties         * file specified on the command line, e.g.:         *   -Djava.util.logging.config.file=logging.properties         * If a user-provided Logger is desired, create and set it here:         *  Logger logger = Logger.getLogger("...");         *  config.setLogger(logger);         * NOTE: the referenced classes must be imported above         */        config.setRequestTimeout(5000);        configureAuth(config);        NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);        System.out.println("Acquired handle for service " + service +                           " at endpoint " + endpoint);        return handle;    }    /*     * This method contains all service-specific code in this program     */    private void configureAuth(NoSQLHandleConfig config) {        if (service.equals("cloud")) {            try {                SignatureProvider authProvider = null;                if (useUserPrincipal) {                    /*                     * Use User Principal authorization using a config                     * file in $HOME/.oci/config                     */                    authProvider = new SignatureProvider();                    /*                     * Credentials can be provided directly by editing the                     * appropriate information into the parameters below                       authProvider = new SignatureProvider(tenantId, // OCID                       userId,         // OCID                       fingerprint, // String                       privateKeyFile, // File                       passphrase);  // char[]                    */                } else if (useSessionToken) {                    /*                     * There are additional constructors for Session Token,                     * see the javadoc                     */                    authProvider = SignatureProvider.createWithSessionToken();                } else {                    if (compartment == null) {                        throw new IllegalArgumentException(                            "Compartment is required for Instance/Resource " +                            "Principal authorization");                    }                    /*                     * There are additional constructors for both Instance and                     * Resource Principal, see the javadoc                     */                    if (useInstancePrincipal) {                        authProvider =                            SignatureProvider.createWithInstancePrincipal();                    } else if (useResourcePrincipal) {                        authProvider =                            SignatureProvider.createWithResourcePrincipal();                    } else if (useOkeWorkloadIdentity) {                        authProvider =                            SignatureProvider.createWithOkeWorkloadIdentity();                    } else {                        throw new IllegalArgumentException(                            "Authorization method is required");                    }                }                config.setAuthorizationProvider(authProvider);            } catch (IOException ioe) {                System.err.println("Unable to configure authentication: " +                                   ioe);                System.exit(1);            }        } else if (service.equals("onprem")) {            config.setAuthorizationProvider(new StoreAccessTokenProvider());        } else if (service.equals("cloudsim")) {            /* cloud simulator */            config.setAuthorizationProvider(new AuthorizationProvider() {                    @Override                    public String getAuthorizationString(Request request) {                        return "Bearer cloudsim";                    }                    @Override                    public void close() {                    }                });        } else {            System.err.println("Unknown service: " + service);            usage();        }    }    public static void main(String[] args) {        final String tableName = "JavaQuickstart";        /*         * The Quickstart instance configures and acquires a handle         */        Quickstart qs = new Quickstart(args);        /*         * Configure and get a NoSQLHandle. All service specific configuration         * is handled here         */        try (NoSQLHandle handle = qs.getHandle()) {            /*             * Create a simple table with an integer key, string name and             * JSON data             */            final String createTableStatement =                "create table if not exists " + tableName +                "(id integer, name string, data json, primary key(id))";            TableRequest tableRequest = new TableRequest()                .setStatement(createTableStatement)                .setTableLimits(new TableLimits(10, 10, 10));            /* this call will succeed or throw an exception */            handle.doTableRequest(tableRequest,                                  20000, /* wait up to 20 sec */                                  1000); /* poll once per second */            System.out.println("Created table " + tableName + " ...");            /*             * Construct a row to put             */            MapValue value = new MapValue()                .put("id", 123)                .put("name", "joe")                .putFromJson("data", "{\"a\": 1, \"b\": 2}", null);            PutRequest putRequest = new PutRequest()                .setValue(value)                .setTableName(tableName);            PutResult putRes = handle.put(putRequest);            System.out.println("Put row, result " + putRes);            /*             * Get a row using the primary key             */            MapValue key = new MapValue().put("id", 123);            GetRequest getRequest = new GetRequest()                .setKey(key)                .setTableName(tableName);            GetResult getRes = handle.get(getRequest);            System.out.println("Got row, result " + getRes);            /*             * Perform a query using iterable and iterator             *             * To ensure the query resources are closed properly, use             * try-with-resources statement.             */            try (                QueryRequest queryRequest = new QueryRequest()                    .setStatement("select * from " + tableName);                QueryIterableResult results =                    handle.queryIterable(queryRequest)) {                System.out.println("Query results:");                for (MapValue res : results) {                    System.out.println("\t" + res);                }            }            /*             * Perform a query using partial results             */            try (                QueryRequest queryRequest = new QueryRequest()                    .setStatement("select * from " + tableName) ) {                /*                 * Because a query can return partial results execution must occur                 * in a loop, accumulating or processing results                 */                ArrayList<MapValue> results = new ArrayList<MapValue>();                do {                    QueryResult queryResult = handle.query(queryRequest);                    results.addAll(queryResult.getResults());                } while (!queryRequest.isDone());                System.out.println("Query results again:");                for (MapValue res : results) {                    System.out.println("\t" + res);                }            }            /*             * Drop the table             */            tableRequest = new TableRequest()                .setStatement("drop table if exists " + tableName);            handle.doTableRequest(tableRequest,                                  20000,                                  1000);            System.out.println("Dropped table " + tableName + ", done...");        }    }}

Examples

Running Examples from a Repository Clone

$ mvn -pl examples exec:java -Dexec.mainClass=BasicTableExample \  -Dexec.args="http://localhost:8080"

$ mvn -pl examples exec:java -Dexec.mainClass=BasicTableExample \  -Dexec.args="http://localhost:8090 -useKVProxy"

$ mvn -pl examples exec:java -Dexec.mainClass=BasicTableExample \  -Dexec.args="us-ashburn-1"

Compile and Run Examples using a Downloaded Release

$ cd examples$ javac -cp ../lib/nosqldriver.jar *.java

Run using the Oracle NoSQL Database Cloud Service

[DEFAULT]tenancy=<User OCID>user=<Tenancy OCID>fingerprint=<Public key fingerprint>key_file=<PEM private key file>pass_phrase=<Private key passphrase>

$ java -cp .:../lib/nosqldriver.jar BasicTableExample <region>    e.g.$ java -cp .:../lib/nosqldriver.jar BasicTableExample us-ashburn-1

Run using the Oracle NoSQL Database On-premise

$ java -cp .:../lib/nosqldriver.jar BasicTableExample http://localhost:80 -useKVProxy

$ java -Djavax.net.ssl.trustStorePassword=123456 \     -Djavax.net.ssl.trustStore=driver.trust -cp .:../lib/nosqldriver.jar \     BasicTableExample https://localhost:443 -useKVProxy -user driver \    -password Driver.User@01

Run using the Oracle NoSQL Database Cloud Simulator

$ java -cp .:../lib/nosqldriver.jar BasicTableExample localhost:8080

License

Help

Contributing

Security