Documentation for centralized config provider, JSON Relational Duality View and other updates with formatting improvements

Author: sharadraju

doc/src/.static/custom.css

@@ -54,3 +54,9 @@ li div.highlight-default.notranslate, li div.highlight-shell.notranslate, li div
     font-size: 11pt;
     font-weight: bold;
 }
+
+/* Added code to override the default content width in ReadtheDocs and break long words */
+.wy-nav-content {
+    max-width: none;
+    word-break: break-word;
+}

doc/src/_ext/constants_table.py

@@ -0,0 +1,52 @@
+#------------------------------------------------------------------------------
+# Copyright (c) 2024, 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 http://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.
+#------------------------------------------------------------------------------
+
+#------------------------------------------------------------------------------
+# constants_table.py
+#
+# Defines a directive (constants-table) that creates a table with a specific
+# configuration on top of the extended "list-table-with-summary" directive.
+#------------------------------------------------------------------------------
+
+from docutils.statemachine import ViewList
+
+import table_with_summary
+
+class ConstantsTable(table_with_summary.ListTableWithSummary):
+
+    def run(self):
+        self.options["summary"] = \
+            "The first column displays the name of the constant. The " \
+            "second column displays the value of the constant. The third " \
+            "column displays the description of the constant."
+        self.options["header-rows"] = 1
+        self.options["class"] = ["wy-table-responsive"]
+        self.options["widths"] = [40, 15, 45]
+        self.options["width"] = "100%"
+        headings = ViewList(['* - Constant Name', '  - Value', '  - Description'])
+        self.content = headings + self.content
+        return super().run()
+
+def setup(app):
+    app.add_directive('constants-table', ConstantsTable)

doc/src/api_manual/connection.rst

@@ -676,6 +676,7 @@ Connection Methods
         :class: wy-table-responsive
         :align: center
         :widths: 10 10 30
+        :width: 100%
         :summary: The first column displays the name of the parameter. The second column displays the data type of the parameter. The third column displays the description of the parameter.
 
         * - Parameter
@@ -842,7 +843,7 @@ Connection Methods
         :header-rows: 1
         :class: wy-table-responsive
         :align: center
-        :widths: 10 10 20 30
+        :widths: 10 15 20 25
         :summary: The first column displays the Node.js Type. The second
          column displays the Database type. The third column displays the
          Bind type value. The fourth column displays the notes.
@@ -972,7 +973,7 @@ Connection Methods
         :header-rows: 1
         :class: wy-table-responsive
         :align: center
-        :widths: 5 10 35
+        :widths: 10 10 30
         :summary: The first column displays the property. The second column
          displays the data type of the property. The third column displays
          the description of the property.
@@ -1511,7 +1512,8 @@ Connection Methods
         :header-rows: 1
         :class: wy-table-responsive
         :align: center
-        :widths: 10 12 45
+        :widths: 10 10 30
+        :width: 100%
         :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.
@@ -1712,7 +1714,8 @@ Connection Methods
         :header-rows: 1
         :class: wy-table-responsive
         :align: center
-        :widths: 10 15 40
+        :widths: 10 10 30
+        :width: 100%
         :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.
@@ -2257,6 +2260,7 @@ Connection Methods
         :class: wy-table-responsive
         :align: center
         :widths: 10 10 30
+        :width: 100%
         :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.
@@ -2814,6 +2818,7 @@ Connection Methods
         :class: wy-table-responsive
         :align: center
         :widths: 10 10 30
+        :width: 100%
         :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.

doc/src/api_manual/deprecations.rst

@@ -15,7 +15,7 @@ desupported features are listed first.
     :header-rows: 1
     :class: wy-table-responsive
     :align: center
-    :widths: 10 25 20
+    :widths: 20 20 15
     :width: 100%
     :summary: The first column displays the deprecated API method, property, or constant. The second column displays the node-oracledb version in which the API method, property, or constant was deprecated or desupported. The third column displays the API property, method, or constant to use instead, if applicable.
 

doc/src/api_manual/lob.rst

@@ -146,6 +146,7 @@ Lob Methods
         :class: wy-table-responsive
         :align: center
         :widths: 15 30
+        :width: 100%
         :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.

doc/src/api_manual/oracledb.rst

@@ -668,7 +668,8 @@ Pool Methods
         :header-rows: 1
         :class: wy-table-responsive
         :align: center
-        :widths: 10 55
+        :widths: 15 35
+        :width: 100%
         :summary: The first column displays the name of the attribute. The
           second column displays the description of the attribute.
 

doc/src/api_manual/pool.rst

@@ -337,6 +337,7 @@ SodaDatabase Methods
         :class: wy-table-responsive
         :align: center
         :widths: 10 10 40
+        :width: 100%
         :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.

doc/src/api_manual/sodadb.rst

@@ -21,7 +21,8 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["table_with_summary", "oracle_desupported", 'sphinx_rtd_theme']
+extensions = ["table_with_summary", "oracle_desupported", "constants_table",
+              'sphinx_rtd_theme']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['.templates']

doc/src/conf.py

@@ -284,7 +284,7 @@ node-oracledb Thin and Thick modes. For more details see :ref:`modediff`.
     * - Oracle Database 21c JSON data type (see :ref:`json21ctype`)
       - Yes
       - Yes
-    * - Oracle Database 23ai JSON duality view
+    * - Oracle Database 23ai JSON-Relational Duality Views (see :ref:`jsondualityviews`)
       - Yes
       - Yes
     * - Oracle Database 23ai BOOLEAN data type (see :ref:`oracledbconstantsdbtype`)

doc/src/user_guide/appendix_a.rst

@@ -443,6 +443,83 @@ This produces::
     {"deptId":30,"name":"Purchasing"}
     {"deptId":40,"name":"Human Resources"}
 
+.. _jsondualityviews:
+
+JSON-Relational Duality Views
+=============================
+
+Oracle Database 23ai JSON-Relational Duality Views allow data to be stored as
+rows in tables to provide the benefits of the relational model and SQL access,
+while also allowing read and write access to data as JSON documents for
+application simplicity. See the `JSON-Relational Duality Developer's Guide
+<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=JSNVU>`__ for more
+information.
+
+For example, if the tables ``authorTable`` and ``bookTable`` exist::
+
+    CREATE TABLE authorTable (
+        authorId NUMBER GENERATED BY DEFAULT ON NULL AS IDENTITY PRIMARY KEY,
+        authorName VARCHAR2(100)
+    );
+
+    CREATE TABLE bookTable (
+        bookId NUMBER GENERATED BY DEFAULT ON NULL AS IDENTITY PRIMARY KEY,
+        bookTitle VARCHAR2(100),
+        authorId NUMBER REFERENCES authorTable (authorId)
+    );
+
+Then a JSON Duality View over the tables can be created using SQL*Plus::
+
+    CREATE OR REPLACE JSON RELATIONAL DUALITY VIEW bookDV AS
+    bookTable @insert @update @delete
+    {
+        _id: bookId,
+        book_title: bookTitle,
+        author: authorTable @insert @update
+        {
+            author_id: authorId,
+            author_name: authorName
+        }
+    };
+
+You can insert into JSON Duality Views using SQL*Plus::
+
+    INSERT INTO bookDV VALUES(
+        '{"book_title": My Book",
+          "author": {"author_name": "James"}}'
+    );
+
+Applications can choose whether to use relational access to the underlying
+tables, or use the duality view.
+
+Inserting JSON into the view will update the base relational tables:
+
+.. code-block:: javascript
+
+    const data = { "_id": 1000, "book_title": "My New Book",
+                   "author": { "author_id": 2000, "author_name": "John Doe" }};
+    await connection.execute(
+        `INSERT INTO bookDV VALUES (:bv)`,
+        { bv: {val: data, type: oracledb.DB_TYPE_JSON}
+    );
+
+You can use SQL/JSON to query the view and return JSON. The query uses the
+special column ``DATA``:
+
+.. code-block:: javascript
+
+    const sql = `SELECT b.data.book_title, b.data.author.author_name FROM
+                 bookDV b WHERE b.data.author.author_id = :1`;
+    const binds = [1];
+    const options = {
+        bindDefs: [ { type: oracledb.NUMBER } ]
+    };
+    const result = await connection.execute(sql, binds, options);
+    console.log(result.rows);
+
+This will print the book title and author name for the author whose id is
+``1``.
+
 Portable JSON
 =============
 

doc/src/user_guide/connection_handling.rst

@@ -215,7 +215,12 @@ BINARY format to define vectors. The BINARY format represents each dimension
 value as a binary value (0 or 1). Binary vectors require less memory storage.
 For example, a 16 dimensional vector with BINARY format requires only 2 bytes of
 storage while a 16 dimensional vector with INT8 format requires 16 bytes of
-storage. The BINARY vector support was introduced in node-oracledb 6.6.
+storage.
+
+Binary vectors require the database initialization parameter `COMPATIBLE
+<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-A2E90F08-BC9F-
+4688-A9D0-4A948DD3F7A9>`__ to be set to 23.5.0.0.0 or greater on Oracle
+Database. The BINARY vector support was introduced in node-oracledb 6.6.
 
 Binary vectors are represented as 8-bit unsigned integers. For the BINARY
 format, you must define the number of dimensions as a multiple of 8. To create