Added new APIs for Simple Oracle Document Access (SODA)

Author: cjbj

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## node-oracledb v3.0.0-dev (DD Mon YYYY)
 
+- Added new APIs for Simple Oracle Document Access ([SODA](https://github.com/oracle/node-oracledb/blob/master/doc/api.md#sodaoverview)), available when using Oracle Database 18.1 and Oracle client libraries version 18.3, or later.
+
 - Added a `drainTime` argument to
   [`pool.close()`](https://github.com/oracle/node-oracledb/blob/master/doc/api.md#poolclose),
   allowing pools to be force-closed after a specified number of

binding.gyp

@@ -11,6 +11,12 @@
              "src/njsSubscription.cpp",
              "src/njsMessages.cpp",
              "src/njsIntLob.cpp",
+             "src/njsSodaDatabase.cpp",
+             "src/njsSodaCollection.cpp",
+             "src/njsSodaDocument.cpp",
+             "src/njsSodaOperation.cpp",
+             "src/njsSodaDocCursor.cpp",
+             "src/njsUtils.cpp",
              "odpi/src/dpiConn.c",
              "odpi/src/dpiContext.c",
              "odpi/src/dpiData.c",

doc/api.md

@@ -0,0 +1,133 @@
+/* Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved. */
+
+/******************************************************************************
+ *
+ * You may not use the identified files except in compliance with the Apache
+ * License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * NAME
+ *   soda1.js
+ *
+ * DESCRIPTION
+ *   Basic Simple Oracle Document Access (SODA) example.
+ *
+ *   Creates and uses a SODA collection.
+ *   Requires Oracle client 18.3 and Oracle Database 18.1, or higher.
+ *   The user must have been granted the SODA_APP privilege.
+ *   See https://oracle.github.io/node-oracledb/doc/api.html#sodaoverview
+ *
+ *   This uses Node 8's async/await syntax but could be rewritten to
+ *   use callbacks.
+ *
+ *****************************************************************************/
+
+var oracledb = require('oracledb');
+var dbConfig = require('./dbconfig.js');
+
+// The general recommendation for simple SODA usage is to enable autocommit
+oracledb.autoCommit = true;
+
+async function run() {
+  let conn, collection;
+
+  try {
+    let soda, indexSpec, content, doc, key, documents, res;
+
+    conn = await oracledb.getConnection(dbConfig);
+
+    // Create the parent object for SODA
+    soda = conn.getSodaDatabase();
+
+    // Create a new SODA collection and index
+    // This will open an existing collection, if the name is already in use.
+    collection = await soda.createCollection("mycollection");
+    indexSpec = { "name": "CITY_IDX",
+      "fields": [ {
+        "path": "address.city",
+        "datatype": "string",
+        "order": "asc" } ] };
+    await collection.createIndex(indexSpec);
+
+    // Insert a document.
+    // A system generated key is created by default.
+    content = {name: "Matilda", address: {city: "Melbourne"}};
+    doc = await collection.insertOneAndGet(content);
+    key = doc.key;
+    console.log("The key of the new SODA document is: ", key);
+
+    // Fetch the document back
+    doc = await collection.find().key(key).getOne(); // A SodaDocument
+    content = doc.getContent();                      // A JavaScript object
+    console.log('Retrieved SODA document as an object:');
+    console.log(content);
+    content = doc.getContentAsString();              // A JSON string
+    console.log('Retrieved SODA document as a string:');
+    console.log(content);
+
+    // Replace document contents
+    content = {name: "Matilda", address: {city: "Sydney"}};
+    await collection.find().key(key).replaceOne(content);
+
+    // Insert some more documents without caring about their keys
+    content = {name: "Venkat", address: {city: "Bengaluru"}};
+    await collection.insertOne(content);
+    content = {name: "May", address: {city: "London"}};
+    await collection.insertOne(content);
+    content = {name: "Sally-Ann", address: {city: "San Francisco"}};
+    await collection.insertOne(content);
+
+    // Find all documents with city names starting with 'S'
+    console.log('Cities starting with S');
+    documents = await collection.find()
+      .filter({"address.city": {"$like": "S%"}})
+      .getDocuments();
+
+    for (let i = 0; i < documents.length; i++) {
+      content = documents[i].getContent();
+      console.log('  city is: ', content.address.city);
+    }
+
+    // Count all documents
+    res = await collection.find().count();
+    console.log('Collection has ' + res.count + ' documents');
+
+    // Remove documents with cities containing 'o'
+    console.log('Removing documents');
+    res = await collection.find().filter({"address.city": {"$regex": ".*o.*"}}).remove();
+    console.log('Dropped ' + res.count + ' documents');
+
+    // Count all documents
+    res = await collection.find().count();
+    console.log('Collection has ' + res.count + ' documents');
+
+  } catch (err) {
+    console.error(err);
+  } finally {
+    if (collection) {
+      // Drop the collection
+      let res = await collection.drop();
+      if (res.dropped) {
+        console.log('Collection was dropped');
+      }
+    }
+    if (conn) {
+      try {
+        await conn.close();
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+}
+
+run();

examples/soda1.js

@@ -22,6 +22,8 @@
 var resultset = require('./resultset.js');
 var QueryStream = require('./querystream.js');
 var nodbUtil = require('./util.js');
+var sodaDatabase = require ('./sodaDatabase.js' ) ;
+
 var executePromisified;
 var executeManyPromisified;
 var getStatementInfoPromisified;
@@ -356,6 +358,16 @@ function unsubscribe(name, cb) {
 unsubscribePromisified = nodbUtil.promisify(unsubscribe);
 
 
+// To obtain a SodaDatabase object (high-level SODA object associated with
+// current connection)
+function getSodaDatabase() {
+  nodbUtil.assert(arguments.length === 0, 'NJS-009');
+  let db = this._getSodaDatabase();
+  sodaDatabase.extend(db, this);
+  return db;
+}
+
+
 // The extend method is used to extend the Connection instance from the C layer with
 // custom properties and method overrides. References to the original methods are
 // maintained so they can be invoked by the overriding method at the right time.
@@ -478,6 +490,14 @@ function extend(conn, oracledb, pool) {
         value: unsubscribePromisified,
         enumerable: true,
         writable: true
+      },
+      _getSodaDatabase: {
+        value: conn.getSodaDatabase
+      },
+      getSodaDatabase:  {
+        value: getSodaDatabase,
+        enumerable: true,
+        writable: true
       }
     }
   );

lib/connection.js

@@ -616,6 +616,10 @@ function extend(oracledb) {
         value: 4002,
         enumerable: true
       },
+      SODA_COLL_MAP_MODE: {
+        value: 5001,
+        enumerable : true
+      },
       POOL_STATUS_OPEN: {
         value: 6000,
         enumerable: true