Add lock() method for SODA document operations

doc/src/release_notes.rst

@@ -21,6 +21,9 @@ Thin Mode Changes
 Thick Mode Changes
 ++++++++++++++++++
 
+#)  Added lock() method on sodaOperation object.  An explicit commit/rollback
+    is required to unlock.
+
 #)  Fixed bug that throws an 'ORA-21525' error with dbObjects having one or
     more 'Number' attributes with precision less than or equal to 18 and scale
     as 0.

lib/sodaOperation.js

@@ -94,6 +94,22 @@ class SodaOperation {
     }
   }
 
+
+  //---------------------------------------------------------------------------
+  // lock()
+  //
+  //  Pessimistic locking - similar to SELECT FOR UPDATE, these documents
+  //  cannot be updated by other threads until an explicit commit/rollback is
+  //  called.  With autoCommit set to true is applicable only for one immediate
+  //  operation and is not recommended in this context
+  //---------------------------------------------------------------------------
+  lock()  {
+    errors.assertArgCount(arguments, 0, 0);
+    this._options.lock = true;
+    return this;
+  }
+
+
   //---------------------------------------------------------------------------
   // replaceOne()
   //

test/list.txt

@@ -5483,3 +5483,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet =  true
 
 284. errorUrl.js
     284.1 checks for error URL in ORA error message
+
+
+287. sodaOperationsLock.js
+    287.1 lock on sodaOperations

test/opts/.mocharc.yaml

@@ -267,3 +267,4 @@ spec:
   - test/aq7.js
   - test/aq5.js
   - test/errorUrl.js
+  - test/sodaOpLock.js

test/sodaOpLock.js

@@ -0,0 +1,82 @@
+/* Copyright (c) 2020, 2023, Oracle and/or its affiliates. */
+
+/******************************************************************************
+ *
+ * This software is dual-licensed to you under the Universal Permissive License
+ * (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+ * 2.0 as shown at https://www.apache.org/licenses/LICENSE-2.0. You may choose
+ * either license.
+ *
+ * If you elect to accept the software under the Apache License, Version 2.0,
+ * the following applies:
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    https://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
+ *   287. sodaOperationsLock.js
+ *
+ * DESCRIPTION
+ *  Test the fetch array size for fetching documents from a collection.
+ *
+ *****************************************************************************/
+'use strict';
+
+const oracledb  = require('oracledb');
+const assert    = require('assert');
+const dbConfig  = require('./dbconfig.js');
+const sodaUtil  = require('./sodaUtil.js');
+const testsUtil = require('./testsUtil.js');
+
+
+describe('287. sodaOperationsLock.js', () => {
+  let conn, soda, coll;
+
+  const collectionName = 'nodb_collection_286_1';
+
+  before(async function() {
+    const isSodaRunnable = await testsUtil.isSodaRunnable();
+    const clientVersion = testsUtil.getClientVersion();
+
+    let isClientOK;
+    if (clientVersion < 2000000000) {
+      isClientOK = false;
+    } else {
+      isClientOK = true;
+    }
+    const isRunnable = isClientOK && isSodaRunnable;
+    if (!isRunnable) {
+      this.skip();
+    }
+
+    await sodaUtil.cleanup();
+    conn = await oracledb.getConnection(dbConfig);
+    soda = conn.getSodaDatabase();
+    coll = await soda.createCollection(collectionName);
+
+    await conn.commit();
+  });     // before
+
+  after(async () => {
+    if (conn) {
+      ////const result = await coll.drop();
+      ////assert.strictEqual(result.dropped, true);
+      await conn.close();
+    }
+  });
+
+  it('287.1 lock on sodaOperations', async() => {
+       coll.find().lock();
+  });
+  
+
+});