Add documentation updates for the new XMLType support and the future object created in node-oracledb 6.3

Author: sharadraju

doc/src/api_manual/oracledb.rst

@@ -3416,3 +3416,30 @@ Oracledb Methods
           - Description
         * - Error ``error``
           - If ``startup()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the :ref:`error message <errorobj>`.
+
+.. _oracledbfuture:
+
+Oracledb Future Object
+======================
+
+A special object that contains properties which control the behavior of
+node-oracledb, allowing use of new features.
+
+.. versionadded:: 6.3
+
+.. attribute:: oracledb.future.oldJsonColumnAsObj
+
+    This property is a boolean which when set to *true* while using Oracle
+    Database 12c (or later), fetches VARCHAR2 and LOB columns that were
+    created with the ``IS JSON`` constraint in the same way that
+    :ref:`columns of type JSON <json21fetch>` are fetched when using
+    Oracle Database 21c (or later). The ``IS JSON`` constraint that is
+    specified when creating VARCHAR2 and LOB columns ensures that only JSON
+    data is stored in these columns.
+
+    The default value is *false*.
+
+    In a future version of node-oracledb, the setting of this attribute will
+    no longer be required since this will be the default behavior.
+
+    .. versionadded:: 6.3

doc/src/user_guide/appendix_a.rst

@@ -285,7 +285,7 @@ node-oracledb Thin and Thick modes. For more details see :ref:`modediff`.
       - Yes
       - Yes
     * - XMLType data type (see :ref:`xmltype`)
-      - Yes - May need to fetch as CLOB
+      - Yes
       - Yes - May need to fetch as CLOB
     * - BFILE data type
       - No

doc/src/user_guide/json_data_type.rst

@@ -15,52 +15,29 @@ For more information about using JSON in Oracle Database see the
 `Database JSON Developer’s Guide <https://www.oracle.com/pls/topic/
 lookup?ctx=dblatest&id=ADJSN>`__.
 
-**Oracle Database 12c JSON Data Type**
-
-Prior to Oracle Database 21, JSON in relational tables is stored as
-BLOB, CLOB or VARCHAR2 data, allowing easy access with node-oracledb.
-All of these types can be used with node-oracledb in Thin or Thick mode.
-
-The older syntax to create a table with a JSON column is like:
-
-.. code-block:: sql
-
-    CREATE TABLE j_purchaseorder (po_document BLOB CHECK (po_document IS JSON));
-
-The check constraint with the clause ``IS JSON`` ensures only JSON data
-is stored in that column.
-
-The older syntax can still be used in Oracle Database 21, however the
-recommendation is to move to the new JSON type. With the old syntax, the
-storage can be BLOB, CLOB, or VARCHAR2. Of these, BLOB is preferred to
-avoid character set conversion overheads.
+.. _json21ctype:
 
-**Oracle Database 21c JSON Data Type**
+Using the Oracle Database 21c JSON Type in node-oracledb
+========================================================
 
 Oracle Database 21c introduced a dedicated JSON data type with a new
 `binary storage format <https://blogs.oracle.com/database/post/
 autonomous-json-database-under-the-covers-oson-format>`__
-that improves performance and functionality. To use the new dedicated
-JSON type, you can use node-oracledb 5.1 or later. The 21c JSON data
-type can be used in both node-oracledb Thin and Thick modes. With Thick mode,
-the Oracle Client libraries must be version 21, or later.
+that improves performance and functionality. To take advantage of the new
+dedicated JSON type in Oracle Database 21c and later versions, use
+node-oracledb 5.1 or later. For Thick mode, you must additionally use
+Oracle Client 21c (or later).
 
-In Oracle Database 21 or later, to create a table with a column called
+In Oracle Database 21c or later, to create a table with a column called
 ``PO_DOCUMENT`` for JSON data:
 
 .. code-block:: sql
 
     CREATE TABLE j_purchaseorder (po_document JSON);
 
-.. _json21ctype:
+**Inserting JSON Data**
 
-Using the Oracle Database 21c JSON Type in node-oracledb
-========================================================
-
-Using node-oracledb Thin mode with Oracle Database 21c or later, or using
-node-oracledb Thick mode or node-oracledb 5.1 (or later) with Oracle Database
-21c (or later) and Oracle Client 21c (or later), you can insert JavaScript
-objects directly by binding as ``oracledb.DB_TYPE_JSON``:
+To insert JavaScript objects directly by binding as ``oracledb.DB_TYPE_JSON``:
 
 .. code-block:: javascript
 
@@ -71,6 +48,10 @@ objects directly by binding as ``oracledb.DB_TYPE_JSON``:
         { bv: {val: data, type: oracledb.DB_TYPE_JSON} }
     );
 
+.. _json21fetch:
+
+**Fetching JSON Data**
+
 To query a JSON column, use:
 
 .. code-block:: javascript
@@ -86,11 +67,11 @@ The output is::
         }
     ]
 
-Using Oracle Client Libraries 19 or Earlier
--------------------------------------------
+Using Oracle Client Libraries 19c or Earlier
+--------------------------------------------
 
-If node-oracledb Thick mode uses Oracle Client Libraries 19 (or earlier),
-querying an Oracle Database 21 (or later), then JSON column returns a
+If node-oracledb Thick mode uses Oracle Client Libraries 19c (or earlier),
+querying an Oracle Database 21c (or later), then JSON column returns a
 :ref:`Lob Class <lobclass>` BLOB. You can stream the Lob or use
 :meth:`lob.getData()`:
 
@@ -117,6 +98,26 @@ shown above.
 Using the Oracle Database 12c JSON Type in node-oracledb
 ========================================================
 
+In Oracle Database versions 12c or later (prior to Oracle Database 21c), JSON
+in relational tables is stored as BLOB, CLOB, or VARCHAR2 data. All of these
+types can be used with node-oracledb in Thin or Thick mode.
+
+The older syntax to create a table with a JSON column is like:
+
+.. code-block:: sql
+
+    CREATE TABLE j_purchaseorder (po_document BLOB CHECK (po_document IS JSON));
+
+The check constraint with the clause ``IS JSON`` ensures only JSON data
+is stored in that column.
+
+The older syntax can still be used in Oracle Database 21c. However the
+recommendation is to move to the new JSON type. With the old syntax, the
+storage can be BLOB, CLOB, or VARCHAR2. Of these, BLOB is preferred to
+avoid character set conversion overheads.
+
+**Inserting JSON Data**
+
 When using Oracle Database 12c or later with JSON using BLOB storage, you can
 insert JSON strings:
 
@@ -131,11 +132,27 @@ insert JSON strings:
         [b]  // bind the JSON string
     );
 
+**Fetching JSON Data**
+
+With Oracle Database 12c (or later), you can fetch VARCHAR2 and LOB columns
+that contain JSON data in the same way that
+:ref:`JSON type columns <json21fetch>` are fetched when using Oracle
+Database 21c (or later). This can be done by setting
+:attr:`oracledb.future.oldJsonColumnAsObj` to the value *true* as shown below.
+If you are using node-oracledb Thick mode, you must use Oracle Client 19c
+(or later) for this setting to work. For example:
+
+.. code-block:: javascript
+
+    oracledb.future.oldJsonColumnAsObj = true;
+    const r = await conn.execute(`SELECT po_document FROM j_purchaseorder`);
+    console.dir(r.rows, { depth: null });
+
 IN Bind Type Mapping
 ====================
 
 When binding a JavaScript object as ``oracledb.DB_TYPE_JSON`` for
-``oracledb.BIND_IN`` or ``oracledb.BIND_INOUT`` in Oracle Database 21
+``oracledb.BIND_IN`` or ``oracledb.BIND_INOUT`` in Oracle Database 21c
 (or later), JavaScript values are converted to JSON attributes as shown
 in the following table. The ‘SQL Equivalent’ syntax can be used in SQL
 INSERT and UPDATE statements if specific attribute types are needed but
@@ -221,7 +238,7 @@ might be like::
 Query and OUT Bind Type Mapping
 ===============================
 
-When getting Oracle Database 21 or later JSON values from the database, the
+When getting Oracle Database 21c or later JSON values from the database, the
 following attribute mapping occurs:
 
 .. list-table-with-summary::

doc/src/user_guide/xml_data_type.rst

@@ -4,22 +4,26 @@
 Using XMLType Data
 ******************
 
-``XMLType`` columns queried will return Strings by default, limited
-to the size of a VARCHAR2.
+Oracle XMLType columns are fetched as strings by default in node-oracledb Thin
+and Thick modes. Note that in Thick mode, you may need to use the
+``XMLTYPE.GETCLOBVAL()`` function as detailed below.
 
-However, if desired, the SQL query could be changed to return a CLOB,
-for example:
+The examples below demonstrate using ``XMLType`` data with node-oracledb. The
+following table will be used in these examples:
 
 .. code-block:: sql
 
-    const sql = `SELECT XMLTYPE.GETCLOBVAL(res) FROM resource_view`;
+    CREATE TABLE xwarehouses(
+        warehouse_id NUMBER,
+        warehouse_spec XMLTYPE
+    );
 
-The CLOB can be fetched in node-oracledb as a String or
-:ref:`Lob <lobclass>`.
+Inserting XML
+=============
 
-To insert into an ``XMLType`` column, directly insert a string
-containing the XML, or use a temporary LOB, depending on the data
-length.
+To insert into an ``XMLType`` column, you can directly insert a string
+containing the XML or use a temporary LOB, depending on the data
+length. For example:
 
 .. code-block:: javascript
 
@@ -42,5 +46,32 @@ length.
      { id: 1, bv: myxml }
     );
 
+Fetching XML
+============
+
+Fetching XML data can be done directly in node-oracledb Thin mode. This also
+works in Thick mode for values that are shorter than the `maximum allowed
+length of a VARCHAR2 column <https://docs.oracle.com/pls/topic/lookup?ctx=
+dblatest&id=GUID-D424D23B-0933-425F-BC69-9C0E6724693C>`__:
+
+.. code-block:: javascript
+
+    myxmldata = await connection.execute(`SELECT warehouse_spec FROM xwarehouses
+                        WHERE warehouse_id = :id`, [1]);
+    console.log(myxmldata);
+
+In Thick mode, for values that exceed the `maximum allowed length of a
+VARCHAR2 column <https://docs.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID
+-D424D23B-0933-425F-BC69-9C0E6724693C>`__, a CLOB must be returned by using
+the ``XMLTYPE.GETCLOBVAL()`` function:
+
+.. code-block:: javascript
+
+    myxmldata = connection.execute(`SELECT XMLTYPE.GETCLOBVAL(warehouse_spec)
+                                    AS mycontent FROM xwarehouses
+                                    WHERE warehouse_id = :id`, [1]);
+    console.log(myxmldata);
+
+The CLOB can be fetched in node-oracledb as a String or :ref:`Lob <lobclass>`.
 LOB handling is as discussed in the section :ref:`Working with CLOB, NCLOB and
 BLOB Data <lobhandling>`.