Two Phase Commit support in Thin mode

Author: sharadraju

doc/src/api_manual/connection.rst

@@ -315,23 +315,13 @@ The properties of a *Connection* object are listed below.
     This read/write attribute is a string that specifies the internal name
     that is used by the connection when logging two-phase commit transactions.
 
-    .. note::
-
-        This property can only be used in the node-oracledb Thick mode. See
-        :ref:`enablingthick`.
-
 .. attribute:: connection.tpcExternalName
 
     .. versionadded:: 5.3
 
     This read/write attribute is a string that specifies the external name
     that is used by the connection when logging two-phase commit transactions.
 
-    .. note::
-
-        This property can only be used in the node-oracledb Thick mode. See
-        :ref:`enablingthick`.
-
 .. attribute:: connection.transactionInProgress
 
     .. versionadded:: 6.3
@@ -2343,11 +2333,6 @@ Connection Methods
 
     See :ref:`Two-Phase Commits (TPC) <twopc>`.
 
-    .. note::
-
-        This method is only supported in node-oracledb Thick mode. See
-        :ref:`enablingthick`.
-
     The parameters of the ``connection.tpcBegin()`` method are:
 
     .. _tpcbegin:
@@ -2427,11 +2412,6 @@ Connection Methods
     ignored and ``tpcCommit()`` has the same behavior as a regular
     ``connection.commit()`` call.
 
-    .. note::
-
-        This method is only supported in node-oracledb Thick mode. See
-        :ref:`enablingthick`.
-
     Note: When using an external transaction manager with two-phase commits,
     :attr:`autocommitting <oracledb.autoCommit>` should be disabled.
 
@@ -2497,11 +2477,6 @@ Connection Methods
     If ``xid`` is not passed, the transaction identifier used by the
     previous ``connection.tpcBegin()`` call is used.
 
-    .. note::
-
-        This method is only supported in node-oracledb Thick mode. See
-        :ref:`enablingthick`.
-
     The parameters of the ``connection.tpcEnd()`` method are:
 
     .. _tpcend:
@@ -2623,11 +2598,6 @@ Connection Methods
 
     Returns a boolean indicating the transaction requires a commit.
 
-    .. note::
-
-        This method is only supported in node-oracledb Thick mode. See
-        :ref:`enablingthick`.
-
     After calling this function, no further activity should take place on
     this connection until either
     :meth:`connection.tpcCommit()` or
@@ -2700,11 +2670,6 @@ Connection Methods
     (XIDs) suitable for use with :meth:`connection.tpcCommit()`
     or :meth:`connection.tpcRollback()`.
 
-    .. note::
-
-        This method is only supported in node-oracledb Thick mode. See
-        :ref:`enablingthick`.
-
     This function is a convenience wrapper that queries the view
     ``DBA_PENDING_TRANSACTIONS``. It requires SELECT privilege on that view.
 

doc/src/release_notes.rst

@@ -43,6 +43,8 @@ Thin Mode Changes
     provided for `Issue #1565 <https://github.com/oracle/node-oracledb/issues/
     1565>`__.
 
+#)  Added :ref:`Two-Phase Commits <tpc>` support.
+
 Thick Mode Changes
 +++++++++++++++++++
 

doc/src/user_guide/appendix_a.rst

@@ -243,7 +243,7 @@ node-oracledb Thin and Thick modes. For more details see :ref:`modediff`.
       - No
       - Yes
     * - Two-phase Commit (TPC) (see :ref:`twopc`)
-      - No
+      - Yes
       - Yes
     * - REF CURSORs (see :ref:`refcursors`)
       - Yes

doc/src/user_guide/two_phase_commit.rst

@@ -9,11 +9,6 @@ support distributed transactions. See `Two-Phase Commit Mechanism
 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-8152084F-4760
 -4B89-A91C-9A84F81C23D1>`__ in the Oracle Database documentation.
 
-.. note::
-
-    In this release, TPC is only supported in node-oracledb Thick mode. See
-    :ref:`enablingthick`.
-
 Distributed transaction protocols attempt to keep multiple data sources
 consistent with one another by ensuring updates to the data sources
 participating in a distributed transaction are all performed, or none of

lib/connection.js

@@ -1412,7 +1412,7 @@ class Connection extends EventEmitter {
   async tpcBegin(xid, flag, timeout) {
     errors.assertArgCount(arguments, 1, 3);
     errors.assertParamValue(nodbUtil.isXid(xid), 1);
-
+    const normalizedXid = nodbUtil.normalizeXid(xid);
     if (arguments.length < 3) {
       timeout = 60;   // seconds
     } else {
@@ -1423,9 +1423,14 @@ class Connection extends EventEmitter {
       flag = constants.TPC_BEGIN_NEW;
     } else {
       errors.assertParamValue(typeof flag === 'number', 2);
+      const options = [constants.TPC_BEGIN_NEW, constants.TPC_BEGIN_JOIN,
+        constants.TPC_BEGIN_RESUME, constants.TPC_BEGIN_PROMOTE];
+      if (options.indexOf(flag) < 0) {
+        errors.throwErr(errors.ERR_INVALID_TPC_BEGIN_FLAGS);
+      }
     }
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
-    await this._impl.tpcBegin(xid, flag, timeout);
+    await this._impl.tpcBegin(normalizedXid, flag, timeout);
   }
 
   //---------------------------------------------------------------------------
@@ -1441,11 +1446,13 @@ class Connection extends EventEmitter {
     } else {
       errors.assertParamValue(typeof onePhase === 'boolean', 2);
     }
+    let normalizedXid;
     if (arguments.length >= 1) {
       errors.assertParamValue(nodbUtil.isXid(xid), 1);
+      normalizedXid = nodbUtil.normalizeXid(xid);
     }
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
-    await this._impl.tpcCommit(xid, onePhase);
+    await this._impl.tpcCommit(normalizedXid, onePhase);
   }
 
   //---------------------------------------------------------------------------
@@ -1460,14 +1467,19 @@ class Connection extends EventEmitter {
       flag = constants.TPC_END_NORMAL;
     } else {
       errors.assertParamValue(typeof flag === 'number', 2);
+      const options = [constants.TPC_END_NORMAL, constants.TPC_END_SUSPEND];
+      if (!options.includes(flag)) {
+        errors.throwErr(errors.ERR_INVALID_TPC_END_FLAGS);
+      }
     }
-
+    let normalizedXid;
     if (arguments.length >= 1) {
       errors.assertParamValue(nodbUtil.isXid(xid), 1);
+      normalizedXid = nodbUtil.normalizeXid(xid);
     }
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
 
-    await this._impl.tpcEnd(xid, flag);
+    await this._impl.tpcEnd(normalizedXid, flag);
   }
 
   //---------------------------------------------------------------------------
@@ -1479,9 +1491,10 @@ class Connection extends EventEmitter {
   async tpcForget(xid) {
     errors.assertArgCount(arguments, 1, 1);
     errors.assertParamValue(nodbUtil.isXid(xid), 1);
+    const normalizedXid = nodbUtil.normalizeXid(xid);
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
 
-    await this._impl.tpcForget(xid);
+    await this._impl.tpcForget(normalizedXid);
   }
 
   //---------------------------------------------------------------------------
@@ -1491,12 +1504,14 @@ class Connection extends EventEmitter {
   //---------------------------------------------------------------------------
   async tpcPrepare(xid) {
     errors.assertArgCount(arguments, 0, 1);
+    let normalizedXid;
     if (arguments.length >= 1) {
       errors.assertParamValue(nodbUtil.isXid(xid), 1);
+      normalizedXid = nodbUtil.normalizeXid(xid);
     }
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
 
-    return await this._impl.tpcPrepare(xid);
+    return await this._impl.tpcPrepare(normalizedXid);
   }
 
   //---------------------------------------------------------------------------
@@ -1541,12 +1556,14 @@ class Connection extends EventEmitter {
   //---------------------------------------------------------------------------
   async tpcRollback(xid) {
     errors.assertArgCount(arguments, 0, 1);
+    let normalizedXid;
     if (arguments.length == 1) {
       errors.assertParamValue(nodbUtil.isXid(xid), 1);
+      normalizedXid = nodbUtil.normalizeXid(xid);
     }
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
 
-    await this._impl.tpcRollback(xid);
+    await this._impl.tpcRollback(normalizedXid);
   }
 
   //---------------------------------------------------------------------------

lib/errors.js

@@ -156,6 +156,11 @@ const ERR_VECTOR_VERSION_NOT_SUPPORTED = 145;
 const ERR_OBJECT_IS_NOT_A_COLLECTION = 146;
 const ERR_CURSOR_HAS_BEEN_CLOSED = 147;
 const ERR_DML_RETURNING_DUP_BINDS = 149;
+const ERR_INVALID_TPC_BEGIN_FLAGS = 150;
+const ERR_INVALID_TPC_END_FLAGS = 151;
+const ERR_UNKNOWN_TRANSACTION_STATE = 152;
+const ERR_INVALID_TRANSACTION_SIZE = 153;
+const ERR_INVALID_BRANCH_SIZE = 154;
 
 // Oracle Net layer errors start from 500
 const ERR_CONNECTION_CLOSED = 500;
@@ -441,6 +446,16 @@ messages.set(ERR_CURSOR_HAS_BEEN_CLOSED,                // NJS-147
   'cursor has been closed by the database');
 messages.set(ERR_DML_RETURNING_DUP_BINDS,               // NJS-149
   'the bind variable placeholder "%s" cannot be used both before and after the RETURNING clause in a DML RETURNING statement');
+messages.set(ERR_INVALID_TPC_BEGIN_FLAGS,               // NJS-150
+  'invalid flags for tpcBegin() in Two Phase Commit');
+messages.set(ERR_INVALID_TPC_END_FLAGS,                 // NJS-151
+  'invalid flags for tpcEnd() in Two Phase Commit');
+messages.set(ERR_UNKNOWN_TRANSACTION_STATE,             // NJS-152
+  'internal error: unknown transaction state {state} in Two Phase Commit');
+messages.set(ERR_INVALID_TRANSACTION_SIZE,              // NJS-153
+  'size of the transaction ID is %d and cannot exceed 64');
+messages.set(ERR_INVALID_BRANCH_SIZE,              // NJS-154
+  'size of the branch ID is %d and cannot exceed 64');
 
 // Oracle Net layer errors
 
@@ -868,6 +883,11 @@ module.exports = {
   ERR_OBJECT_IS_NOT_A_COLLECTION,
   ERR_CURSOR_HAS_BEEN_CLOSED,
   ERR_DML_RETURNING_DUP_BINDS,
+  ERR_INVALID_TPC_BEGIN_FLAGS,
+  ERR_INVALID_TPC_END_FLAGS,
+  ERR_UNKNOWN_TRANSACTION_STATE,
+  ERR_INVALID_TRANSACTION_SIZE,
+  ERR_INVALID_BRANCH_SIZE,
   ERR_CONNECTION_CLOSED_CODE: `${ERR_PREFIX}-${ERR_CONNECTION_CLOSED}`,
   WRN_COMPILATION_CREATE,
   assert,