Update Release notes and documentation for the SODA lock method

Author: sharadraju

doc/src/api_manual/sodacollection.rst

@@ -451,6 +451,39 @@ with the key “c” is matched.
     The ``limit()`` method cannot be used in conjunction with
     :meth:`~sodaOperation.count()`.
 
+.. method:: sodaOperation.lock()
+
+    .. versionadded:: 6.2
+
+    .. code-block:: javascript
+
+        lock()
+
+    Locks the documents fetched from the collection.
+
+    Using ``lock()`` allows for pessimistic locking, that is, only the current
+    user that performed the lock can modify the documents in the collection.
+    Other users can only perform operations on these documents once they are
+    unlocked. The functionality of this method is equivalent to the
+    ``SELECT FOR UPDATE`` clause.
+
+    The documents can be unlocked with an explicit call to
+    :meth:`~connection.commit()` or :meth:`~connection.rollback()` on the
+    connection. Ensure that the :attr:`oracledb.autoCommit` is
+    set to *false* for the connection. Otherwise, the documents will be
+    unlocked immediately after the operation is complete.
+
+    This method should only be used with read operations (other than
+    :meth:`~sodaOperation.count()`), and should not be used in conjunction
+    with non-terminal methods :meth:`~sodaOperation.skip()` and
+    :meth:`~sodaOperation.limit()`.
+
+    If this method is specified in conjunction with a write operation, then
+    this method is ignored.
+
+    This method is only supported in Oracle Client 21.3 and Oracle Client
+    19.11 (or later).
+
 .. method:: sodaOperation.skip()
 
     .. versionadded:: 3.0

doc/src/release_notes.rst

@@ -21,12 +21,15 @@ Thin Mode Changes
 Thick Mode Changes
 ++++++++++++++++++
 
-#)  Fixed segfault while populating object Collection having BLOB property.
-    `https://node-oracledb.slack.com/archives/CCM8AMSF7/p1694544451676639`--.
-
-#)  Added lock() method on sodaOperation object to disable modification on any
-    SODA document. An explicit commit/rollback is required to unlock and
-    modify any corresponding SODA document.
+#)  Fixed bug where a segmentation fault (segfault) occurred while populating
+    object Collection having BLOB property. See
+    `node-oracledb public Slack channel <https://node-oracledb.slack.com/
+    archives/CCM8AMSF7/p1694544451676639>`__.
+
+#)  Added :meth:`sodaOperation.lock()` method on
+    :ref:`SodaOperation <sodaoperationclass>` object to disable modification
+    on any SODA document. An explicit commit or rollback is required to unlock
+    and modify any corresponding SODA document.
 
 #)  Fixed bug that throws an 'ORA-21525' error with dbObjects having one or
     more 'Number' attributes of precision less than or equal to 18 and scale

doc/src/user_guide/soda.rst

@@ -119,6 +119,7 @@ Note:
 - When :attr:`oracledb.autoCommit` is *true*,
   most SODA methods will issue a commit before successful return.
 - SODA provides optimistic locking, see :meth:`sodaOperation.version()`.
+- SODA provides pessimistic locking, see :meth:`sodaOperation.lock()`.
 - When mixing SODA and relational access, any commit or rollback on the
   connection will affect all work.
 
@@ -397,6 +398,21 @@ Other examples of chained read and write operations include:
 
     const n = collection.find().count();
 
+- To lock the documents in a collection:
+
+  .. code-block:: javascript
+
+    collection.find().lock();
+
+  Using :meth:`~sodaOperation.lock()` allows pessimistic locking, so that the
+  :meth:`~sodaCollection.find()` terminal method does not allow anyone else to
+  modify the documents in the collection other than the current user.
+
+  After all the documents have been modified, explicitly call
+  :meth:`~connection.commit()` in your application to unlock the documents.
+  Also, an explicit call to :meth:`~connection.rollback()` will unlock the
+  documents in the collection.
+
 - When using :meth:`~sodaOperation.getCursor()` and
   :meth:`~sodaOperation.getDocuments()` to return a
   number of documents, performance of document retrieval can be tuned