First merge of named Oracle type query and binding support

Author: cjbj

CHANGELOG.md

@@ -13,19 +13,30 @@
     - The string representation of classes has changed to `[Object Object]` as a consequence of using N-API.  Use `Object.getPrototypeOf()` to get class information.
     - The C compiler required for building from source code no longer needs C++11 compatibility.  The node-oracledb source code is now pure C.
 
+- Added support for querying and binding Oracle Database objects and
+  collections, see [Oracle Database Objects and
+  Collections](https://oracle.github.io/node-oracledb/doc/api.html#objects).
+
 - Oracle Advanced Queuing (AQ):
 
     - Added support for "RAW" queues, allowing String and Buffer
       messages to be used.
 
+    - Added support for object queues, allowing Oracle Database object
+      messages to be used.
+
     - Added support for notifications with `oracledb.SUBSCR_NAMESPACE_AQ`.
 
 - Added support for Implicit Results, allowing query results to be
   returned from PL/SQL without needing parameters or bind variables.
 
-- Added
+- Added asynchronous method
   [`lob.getData()`](https://oracle.github.io/node-oracledb/doc/api.html#lobgetdata)
-  to return data from a Lob instance.
+  to return all data from a Lob readable stream.
+
+- Added a new `dbTypeName` attribute to `extendedMetaData` output.  It
+  contains the name of the type the column has in the database, such
+  as "VARCHAR2".
 
 - Enhanced BIND_IN of PL/SQL Collection Associative Arrays (Index-by)
   so a bind definition object can be omitted (see

binding.gyp

@@ -9,6 +9,7 @@
              "src/njsAqQueue.c",
              "src/njsBaton.c",
              "src/njsConnection.c",
+             "src/njsDbObject.c",
              "src/njsErrors.c",
              "src/njsLob.c",
              "src/njsModule.c",

doc/api.md

@@ -51,6 +51,7 @@ File Name                   | Description
 ----------------------------|----------------------------------------------------------------------------------
 aqoptions.js                | Oracle Advanced Queuing (AQ) example setting options and message attributes
 aqmulti.js                  | Oracle Advanced Queuing (AQ) example passing multiple messages
+aqobject.js                 | Oracle Advanced Queuing (AQ) example passing an Oracle Database object
 aqraw.js                    | Basic Oracle Advanced Queuing (AQ) example passing text messages
 blobhttp.js                 | Simple web app that streams an image
 calltimeout.js              | Shows how to cancel a SQL statement if it doesn't complete in a specified time
@@ -66,7 +67,7 @@ demo.sql                    | SQL script to create extra schema objects for the
 demodrop.sql                | SQL script to drop the extra schema objects for the examples
 dmlrupd1.js                 | Example of DML RETURNING with a single row match
 dmlrupd2.js                 | Example of DML RETURNING where multiple rows are matched
-em_batcherrors.js           | ``executeMany()`` example showing handling data errors
+em_batcherrors.js           | `executeMany()` example showing handling data errors
 em_dmlreturn1.js            | `executeMany()` example of DML RETURNING that returns single values
 em_dmlreturn2.js            | `executeMany()` example of DML RETURNING that returns multiple values
 em_insert1.js               | Array DML example using `executeMany()` with bind-by-name syntax
@@ -91,6 +92,7 @@ metadata.js                 | Shows the metadata available after executing SELEC
 plsqlarray.js               | Examples of binding PL/SQL "INDEX BY" tables
 plsqlfunc.js                | How to call a PL/SQL function
 plsqlproc.js                | How to call a PL/SQL procedure
+plsqlrecord.js              | Shows binding of PL/SQL RECORDS
 raw1.js                     | Shows using a Buffer to insert and select a RAW
 refcursor.js                | Shows using a ResultSet to fetch rows from a REF CURSOR
 refcursortoquerystream.js   | Converts a REF CURSOR returned from `execute()` to a query stream.
@@ -100,9 +102,12 @@ resultsettoquerystream.js   | Converts a ResultSet returned from `execute()` int
 rowlimit.js                 | Shows ways to limit the number of records fetched by queries
 select1.js                  | Executes a basic query without using a connection pool or ResultSet
 select2.js                  | Executes queries to show array and object output formats
+selectgeometry.js           | Insert and query Oracle Spatial geometries
 selectjson.js               | Shows some JSON features of Oracle Database
 selectjsonblob.js           | Shows how to use a BLOB as a JSON column store
+selectobject.js             | Insert and query a named Oracle database object
 selectstream.js             | Executes a basic query using a Readable Stream
+selectvarray.js             | Shows inserting and selecting from a VARRAY column
 sessionfixup.js             | Shows a pooled connection callback to efficiently set session state
 sessiontagging1.js          | Simple pooled connection tagging for setting session state
 sessiontagging2.js          | More complex example of pooled connection tagging for setting session state

examples/README.md

@@ -40,7 +40,7 @@ async function enq() {
 
   try {
     connection = await oracledb.getConnection(dbConfig);
-    let queue = connection.queue(queueName);
+    const queue = await connection.queue(queueName);
     queue.enqOptions.visibility = oracledb.AQ_VISIBILITY_IMMEDIATE; // Send a message without requiring a commit
 
     console.log('Enqueuing messages');
@@ -74,12 +74,12 @@ async function deq() {
 
   try {
     connection = await oracledb.getConnection(dbConfig);
-    const queue = connection.queue(queueName);
+    const queue = await connection.queue(queueName);
     queue.deqOptions.visibility = oracledb.AQ_VISIBILITY_IMMEDIATE; // Change the visibility so no explicit commit is required
 
     const messages = await queue.deqMany(5);  // get at most 5 messages
     console.log("Dequeued " + messages.length + " messages");
-    for (let msg of messages) {
+    for (const msg of messages) {
       console.log(msg.payload.toString());
     }
 

examples/aqmulti.js

@@ -0,0 +1,94 @@
+/* Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved. */
+
+/******************************************************************************
+ *
+ * You may not use the identified files except in compliance with the Apache
+ * License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at
+ * http://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.
+ *
+ * NAME
+ *   aqobject.js
+ *
+ * DESCRIPTION
+ *   Oracle Advanced Queuing (AQ) example passing an Oracle Database object
+ *
+ *   Before running this, a queue allowing an Oracle Database object
+ *   payloads must be created, see
+ *   https://oracle.github.io/node-oracledb/doc/api.html#aqobjexample
+ *
+ *   This example requires node-oracledb 4 or later.
+ *
+ *   This example uses Node 8's async/await syntax.
+ *
+ *****************************************************************************/
+
+const oracledb = require('oracledb');
+const dbConfig = require('./dbconfig.js');
+
+const queueName = "ADDR_QUEUE";
+
+async function enq() {
+  let connection;
+
+  // The message to send.
+  // The attributes correspond to the USER_ADDRESS_TYPE fields.
+  const addrData = {
+    NAME: "scott",
+    ADDRESS: "The Kennel"
+  };
+
+  try {
+    connection = await oracledb.getConnection(dbConfig);
+    const queue = await connection.queue(queueName, {payloadType: "USER_ADDRESS_TYPE"});
+    const message = new queue.payloadTypeClass(addrData);
+    console.log('Enqueuing: ', addrData);
+    await queue.enqOne(message);
+    await connection.commit();
+  } catch (err) {
+    console.error(err);
+  } finally {
+    if (connection) {
+      try {
+        await connection.close();
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+}
+
+async function deq() {
+  let connection;
+
+  try {
+    connection = await oracledb.getConnection(dbConfig);
+    const queue = await connection.queue(queueName, {payloadType: "USER_ADDRESS_TYPE"});
+    const msg = await queue.deqOne();  // wait for a message
+    await connection.commit();
+    if (msg) {
+      console.log('Dequeued:  ', msg.payload);
+    }
+  } catch (err) {
+    console.error(err);
+  } finally {
+    if (connection) {
+      try {
+        await connection.close();
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+}
+
+enq();
+deq();

examples/aqobject.js

@@ -41,7 +41,7 @@ async function enq() {
   try {
     connection = await oracledb.getConnection(dbConfig);
 
-    let queue = connection.queue(queueName);
+    const queue = await connection.queue(queueName);
     queue.enqOptions.visibility = oracledb.AQ_VISIBILITY_IMMEDIATE; // Send a message immediately without requiring a commit
 
     const messageString = 'This is my other message';
@@ -70,7 +70,7 @@ async function deq() {
   try {
     connection = await oracledb.getConnection(dbConfig);
 
-    const queue = connection.queue(queueName);
+    const queue = await connection.queue(queueName);
     Object.assign(
       queue.deqOptions,
       {

examples/aqoptions.js

@@ -40,7 +40,7 @@ async function enq() {
 
   try {
     connection = await oracledb.getConnection(dbConfig);
-    let queue = connection.queue(queueName);
+    const queue = await connection.queue(queueName);
     const messageString = 'This is my message';
     console.log('Enqueuing: ' + messageString);
     await queue.enqOne(messageString);
@@ -63,7 +63,7 @@ async function deq() {
 
   try {
     connection = await oracledb.getConnection(dbConfig);
-    const queue = connection.queue(queueName);
+    const queue = await connection.queue(queueName);
     const msg = await queue.deqOne();  // wait for a message
     await connection.commit();
     if (msg) {

examples/aqraw.js

@@ -0,0 +1,131 @@
+/* Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved. */
+
+/******************************************************************************
+ *
+ * You may not use the identified files except in compliance with the Apache
+ * License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at
+ * http://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.
+ *
+ * NAME
+ *   plsqlrecord.js
+ *
+ * DESCRIPTION
+ *   Shows binding of PL/SQL RECORDS
+ *
+ *   This example requires node-oracledb 4 or later.
+ *
+ *   This example uses Node 8's async/await syntax.
+ *
+ *****************************************************************************/
+
+'use strict';
+
+const oracledb = require('oracledb');
+const dbConfig = require('./dbconfig.js');
+
+async function run() {
+  let connection, binds, options, result, obj;
+
+  // The PL/SQL that is called in each example
+  const plsql = `CALL rectest.myproc(:inbv, :outbv)`;
+
+  try {
+
+    connection = await oracledb.getConnection(dbConfig);
+
+    // Create a PL/SQL package that uses a RECORD
+
+    await connection.execute(
+      `CREATE OR REPLACE PACKAGE rectest AS
+         TYPE rectype IS RECORD (name VARCHAR2(40), pos NUMBER);
+         PROCEDURE myproc (p_in IN rectype, p_out OUT rectype);
+       END rectest;`);
+
+    await connection.execute(
+      `CREATE OR REPLACE PACKAGE BODY rectest AS
+         PROCEDURE myproc (p_in IN rectype, p_out OUT rectype) AS
+         BEGIN
+           p_out := p_in;
+           p_out.pos := p_out.pos * 2;
+         END;
+       END rectest;`);
+
+
+    // Get the RECORD prototype object
+
+    const RecTypeClass = await connection.getDbObjectClass("RECTEST.RECTYPE");
+    // console.log(RecTypeClass.prototype);
+
+
+    //
+    // Single execution
+    //
+
+    console.log('Using the constructor to create an object:');
+    obj = new RecTypeClass({ NAME: 'Ship', POS: 12 });
+
+    binds = {
+      inbv: obj,
+      outbv: { type: RecTypeClass, dir: oracledb.BIND_OUT }
+    };
+
+    result = await connection.execute(plsql, binds);
+    console.log(result.outBinds.outbv);
+
+    console.log('\nBinding the record values directly:');
+
+    binds = {
+      inbv: { type: RecTypeClass, val: { NAME: 'Plane', POS: 34 } },
+      outbv: { type: RecTypeClass, dir: oracledb.BIND_OUT }
+    };
+
+    result = await connection.execute(plsql, binds);
+    console.log(result.outBinds.outbv);
+
+    //
+    // executeMany()
+    //
+
+    console.log('\nExample with executeMany():');
+
+    binds = [
+      { inbv: { NAME: 'Car', POS: 56 } },
+      { inbv: { NAME: 'Train', POS: 78 } },
+      { inbv: { NAME: 'Bike', POS: 83 } }
+    ];
+
+    options = {
+      bindDefs: {
+        inbv: { type: RecTypeClass },
+        outbv: { type: RecTypeClass, dir: oracledb.BIND_OUT },
+      }
+    };
+
+    result = await connection.executeMany(plsql, binds, options);
+    for (const b of result.outBinds) {
+      console.log(b.outbv);
+    }
+
+  } catch (err) {
+    console.error(err);
+  } finally {
+    if (connection) {
+      try {
+        await connection.close();
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+}
+
+run();