Update Tests and Documentation for the latest features in 6.7

Author: sharadraju

doc/src/api_manual/connection.rst

@@ -85,6 +85,23 @@ The properties of a *Connection* object are listed below.
         This property can only be used in the node-oracledb Thick mode. See
         :ref:`enablingthick`.
 
+.. attribute:: connection.connectString
+
+    .. versionadded:: 6.7
+
+    This read-only property is a string that identifies the connect string
+    used to connect to Oracle Database.
+
+.. attribute:: connection.connectTraceConfig
+
+    .. versionadded:: 6.7
+
+    This read-only property is an object that returns connection related
+    information. The connection information returned by node-oracledb Thin
+    mode includes connectString, user, serviceName, instanceName, pdbName,
+    hostName, port, and protocol. The Thick mode returns connectString, user,
+    serviceName, instanceName, and pdbName.
+
 .. attribute:: connection.currentSchema
 
     .. versionadded:: 4.0
@@ -155,6 +172,17 @@ The properties of a *Connection* object are listed below.
         This property can only be used in the node-oracledb Thick mode. See
         :ref:`enablingthick`.
 
+.. attribute:: connection.hostName
+
+    .. versionadded:: 6.7
+
+    This read-only property is a string that identifies the host name of
+    Oracle Database.
+
+    .. note::
+
+        This property can only be used in node-oracledb Thin mode.
+
 .. attribute:: connection.instanceName
 
     .. versionadded:: 6.1
@@ -217,6 +245,28 @@ The properties of a *Connection* object are listed below.
     or later, client libraries. Otherwise it will show the base release such
     as “18.0.0.0.0” instead of “18.3.0.0.0”.
 
+.. attribute:: connection.port
+
+    .. versionadded:: 6.7
+
+    This read-only property is a number that identifies the port to which the
+    client is connected.
+
+    .. note::
+
+        This property can only be used in node-oracledb Thin mode.
+
+.. attribute:: connection.protocol
+
+    .. versionadded:: 6.7
+
+    This read-only property is a string which identifies the protocol used to
+    connect to Oracle Database.
+
+    .. note::
+
+        This property can only be used in node-oracledb Thin mode.
+
 .. attribute:: connection.serviceName
 
     .. versionadded:: 6.3
@@ -332,6 +382,13 @@ The properties of a *Connection* object are listed below.
     value is *False*, then the specified connection does not have an active
     transaction.
 
+.. attribute:: connection.user
+
+    .. versionadded:: 6.7
+
+    This read-only property is a string that identifies the user provided to
+    connect to Oracle Database.
+
 .. attribute:: connection.warning
 
     .. versionadded:: 6.3

doc/src/api_manual/oracledb.rst

@@ -2035,8 +2035,7 @@ Oracledb Methods
           - Both
           - .. _createpoolpoolattrsconnectstring:
 
-            The Oracle database instance used by connections in the pool. The string can be an Easy Connect string, or a Net Service Name from a ``tnsnames.ora`` file, or the name of a local Oracle Database instance. See :ref:`Connection Strings
-            <connectionstrings>` for examples.
+            The Oracle database instance used by connections in the pool. The string can be an Easy Connect string, or a Net Service Name from a ``tnsnames.ora`` file, or the name of a local Oracle Database instance. See :ref:`Oracle Net Services Connection String <connectionstrings>` for examples.
 
             .. versionadded:: 2.1
 
@@ -2811,7 +2810,7 @@ Oracledb Methods
           - Both
           - .. _getconnectiondbattrsconnectstring:
 
-            The Oracle database instance to connect to. The string can be an Easy Connect string, or a Net Service Name from a ``tnsnames.ora`` file, or the name of a local Oracle database instance. See :ref:`Connection Strings <connectionstrings>` for examples.
+            The Oracle database instance to connect to. The string can be an Easy Connect string, or a Net Service Name from a ``tnsnames.ora`` file, or the name of a local Oracle database instance. See :ref:`Oracle Net Services Connection String <connectionstrings>` for examples.
 
             The two properties are aliases for each other. Use only one of the properties.
 
@@ -3686,3 +3685,212 @@ Global_Objects/Uint8Array>`__ and can be instantiated in the same way as an
 Uint8Array datatype object.
 
 .. versionadded:: 6.5
+
+.. _tracehandlerinterface:
+
+Oracledb TraceHandler Interface
+===============================
+
+The :ref:`TraceHandlerBase class <tracehandlerbaseclass>` acts as an
+interface which provides abstract methods that can be implemented by derived
+classes. The implemented methods can use the ``traceContext`` in/out parameter
+with OpenTelemetry.
+
+.. versionadded:: 6.7
+
+.. _tracehandlerbaseclass:
+
+TraceHandlerBase Class
+----------------------
+
+TraceHandlerBase Methods
+++++++++++++++++++++++++
+
+.. method:: traceHandlerBase.disable()
+
+    .. code-block:: javascript
+
+        disable();
+
+    Disables invoking the Abstract methods with traceContext data. Note that
+    this is a synchronous method.
+
+.. method:: traceHandlerBase.enable()
+
+    .. code-block:: javascript
+
+        enable();
+
+    Enables invoking the Abstract methods with traceContext data. Note that
+    this is a synchronous method.
+
+.. method:: traceHandlerBase.isEnabled()
+
+    .. code-block:: javascript
+
+        isEnabled();
+
+    Determines if the abstract methods will be invoked.
+
+.. method:: onEnterFn()
+
+    .. code-block:: javascript
+
+        onEnterFn([Object traceContext]);
+
+    This method is invoked before a public method passes the traceContext.
+    Note that this is a synchronous method.
+
+    .. _onenterfn:
+
+    .. list-table-with-summary:: onEnterFn() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the parameter. The second column
+         displays the data type of the parameter. The third column displays
+         the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``traceContext``
+          - Object
+          - The trace context details. This includes connection configuration details, call level details, and additional attribute details.
+
+.. method:: onExitFn()
+
+    .. code-block:: javascript
+
+        onExitFn(Object traceContext);
+
+    This method is invoked after a public method completes passing the
+    traceContext. Note that this is a synchronous method.
+
+    .. _onexitfn:
+
+    .. list-table-with-summary:: onExitFn() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the parameter. The second column
+         displays the data type of the parameter. The third column displays
+         the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``traceContext``
+          - Object
+          - The trace context details. This includes connection configuration details, call level details, and additional attribute details.
+
+.. method:: onBeginRoundTrip()
+
+    .. code-block:: javascript
+
+        onBeginRoundTrip([Object traceContext]);
+
+    Called when a round trip begins. OpenTelemetry will start a new span as a
+    child of the public API span.
+
+    .. _onbeginroundtrip:
+
+    .. list-table-with-summary:: onBeginRoundTrip() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the parameter. The second column
+         displays the data type of the parameter. The third column displays
+         the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``traceContext``
+          - Object
+          - The trace context details. This includes connection configuration details, call level details, and additional attribute details.
+
+.. method:: onEndRoundTrip()
+
+    .. code-block:: javascript
+
+        onEndRoundTrip([Object traceContext]);
+
+    Called when a round trip ends. OpenTelemetry will end the span. The
+    traceContext object passed in :meth:`onBeginRoundTrip()` is also passed
+    in this method.
+
+    .. _onendroundtrip:
+
+    .. list-table-with-summary:: onEndRoundTrip() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the parameter. The second column
+         displays the data type of the parameter. The third column displays
+         the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``traceContext``
+          - Object
+          - The trace context details. This includes connection configuration details, call level details, and additional attribute details.
+
+.. _tracehandler:
+
+TraceHandler Methods
+--------------------
+
+.. method:: oracledb.traceHandler.getTraceInstance()
+
+    .. code-block:: javascript
+
+        getTraceInstance();
+
+    Returns the user-defined instance implementing the TraceHandlerBase class.
+    Note that this is a synchronous method.
+
+.. method:: oracledb.traceHandler.isEnabled()
+
+    .. code-block:: javascript
+
+        isEnabled();
+
+    Checks if an instance implementing the
+    :ref:`TraceHandlerBase class <tracehandlerbaseclass>` is registered and if
+    the abstract methods will be invoked. Note that this is a synchronous
+    method.
+
+.. method:: oracledb.traceHandler.setTraceInstance()
+
+    .. code-block:: javascript
+
+        setTraceInstance([Object obj]);
+
+    Sets the user-defined implementation of the TraceHandlerBase class. Note
+    that this is a synchronous method.
+
+    The parameters of the ``oracledb.traceHandler.setTraceInstance()`` method are:
+
+    .. _settraceinstance:
+
+    .. list-table-with-summary:: oracledb.traceHandler.setTraceInstance() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the parameter. The second column
+         displays the data type of the parameter. The third column displays
+         the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``obj``
+          - Object
+          - The singleton object pointing to the traceHandler instance.

doc/src/api_manual/pool.rst

@@ -53,6 +53,14 @@ values.
     See :ref:`connectString <createpoolpoolattrsconnectstring>` parameter of
     :meth:`oracledb.createPool()`.
 
+.. attribute:: pool.connectTraceConfig
+
+    .. versionadded:: 6.7
+
+    This read-only property is an object that returns connection related
+    information. The connection information returned includes connectString,
+    user, poolMin, poolMax, and poolIncrement.
+
 .. attribute:: pool.edition
 
     This read-only property is a string which identifies the edition name

doc/src/index.rst

@@ -1,16 +1,9 @@
-Welcome to node-oracledb's documentation!
-=========================================
+Welcome to node-oracledb's documentation
+========================================
 
 The `node-oracledb <https://www.npmjs.com/package/oracledb>`__ add-on
 for Node.js powers high performance Oracle Database applications.
 
-**node-oracledb** is distributed under an open-source :ref:`license
-<license>`. Changes in the node-oracledb releases can be found in the
-:ref:`release notes <releasenotes>`.
-
-This module is currently tested with Node.js 16, 18, and 20 against Oracle
-Database 23ai, 21c, 19c, 12c, and 11gR2.
-
 You can use assistive technology products, such as screen readers, while you
 work with the node-oracledb documentation. You can also use the keyboard
 instead of the mouse.

doc/src/user_guide/appendix_a.rst

@@ -413,14 +413,14 @@ See :ref:`tnsadmin` and :ref:`oraaccess` for more information.
 Connection Strings
 ++++++++++++++++++
 
-The node-oracledb Thin mode accepts connection strings in the same formats as
-the Oracle Client libraries used by Thick mode does, but not all Oracle Net
-keywords will be supported.
+Node-oracledb Thin mode accepts :ref:` Oracle Net Services connection strings
+<connectionstrings>` in the same formats as the Oracle Client libraries used by
+Thick mode does, but not all Oracle Net keywords will be supported.
 
 The following table lists the parameters that are recognized in Thin mode
-either in Easy Connect Strings or in Full Connect Descriptor Strings that are
-either explicitly passed or referred to by a ``tnsnames.ora`` alias.  All
-unrecognized parameters are ignored.
+either in :ref:`Easy Connect <easyconnect>` strings, or in
+:ref:`Connect Descriptors <embedtns>` that are either explicitly passed, or
+are in a ``tnsnames.ora`` file.  All unrecognized parameters are ignored.
 
 .. list-table-with-summary::  Oracle Net Keywords Supported in the node-oracledb Thin Mode
     :header-rows: 1