Update examples for node-oracledb 4.0 (oracle-samples#58)

Author: cjbj

javascript/node-oracledb/README.md

@@ -1,6 +1,6 @@
 # Node-oracledb Examples
 
-This directory contains [node-oracledb 3.1](https://www.npmjs.com/package/oracledb) examples.
+This directory contains [node-oracledb 4.0](https://www.npmjs.com/package/oracledb) examples.
 
 The node-oracledb add-on for Node.js powers high performance Oracle Database applications.
 
@@ -15,7 +15,7 @@ Slack](https://node-oracledb.slack.com/join/shared_invite/enQtNDU4Mjc2NzM5OTA2LT
 
 To run the examples:
 
-- [Install node-oracledb](https://oracle.github.io/node-oracledb/INSTALL.html).
+- [Install node-oracledb](https://oracle.github.io/node-oracledb/INSTALL.html#quickstart).
 
 
 - Use `demo.sql` to create schema objects used by the samples.  For
@@ -33,7 +33,7 @@ connection string:
   module.exports = {
       user: "hr",
       password: process.env.NODE_ORACLEDB_PASSWORD,
-      connectString:"localhost/orclpdb"
+      connectString:"localhost/orclpdb1"
   };
   ```
 
@@ -60,3 +60,77 @@ The demonstration objects can be dropped with `demodrop.sql`:
   ```
   sqlplus hr/welcome@localhost/orclpdb @demodrop.sql
   ```
+
+## Example Overview
+
+If this is your first time with node-oracledb, start with
+[`example.js`](example.js).
+
+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
+connect.js                  | Basic example for creating a standalone (non-pooled) connection
+connectionpool.js           | Basic example creating a pool of connections
+cqn1.js                     | Basic Continuous Query Notification (CQN) example
+cqn2.js                     | Continuous Query Notification with notification grouping
+date.js                     | Show some DATE and TIMESTAMP behaviors
+dbconfig.js                 | Common file used by examples for setting connection credentials
+dbmsoutputgetline.js        | Show fetching DBMS_OUTPUT by binding buffers
+dbmsoutputpipe.js           | Show fetching DBMS_OUTPUT by using a pipelined table
+demo.sql                    | SQL script to create extra schema objects for the examples
+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_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
+em_insert2.js               | Array DML example using `executeMany()` with bind by position
+em_plsql.js                 | `executeMany()` example calling PL/SQL multiple times with one call
+em_rowcounts.js             | `executeMany()` example showing how to find the number of rows affected by each input row
+endtoend.js                 | Example showing setting tracing attributes
+example.js                  | Basic example showing creating a table, inserting multiple rows, and querying rows
+fetchinfo.js                | Show how numbers and dates can be returned as strings using `fetchAsString` and `fetchInfo`
+impres.js                   | Shows PL/SQL 'Implict Results' returning multiple query results from PL/SQL code.
+insert1.js                  | Basic example creating a table and inserting data.  Shows DDL and DML
+insert2.js                  | Basic example showing auto commit behavior
+lobbinds.js                 | Demonstrates how to bind and query LOBs
+lobinsert1.js               | Shows inserting a file into a CLOB column
+lobinsert2.js               | Inserts text into a CLOB column using the RETURNING INTO method.
+lobinserttemp.js            | Writes data to a Temporary CLOB and then inserts it into the database
+lobplsqltemp.js             | Streams data into a Temporary CLOB and then passes it to PL/SQL
+lobselect.js                | Shows basic, non-streaming CLOB and BLOB queries
+lobstream1.js               | Shows how to stream LOBs to files
+lobstream2.js               | Shows using Stream data events to fetch a CLOB
+metadata.js                 | Shows the metadata available after executing SELECT statements
+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
+plsqlvarrayrecord.js        | Shows binding a VARRAY of RECORD in PL/SQL
+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.
+resultset1.js               | Executes a query and uses a ResultSet to fetch rows with `getRow()`
+resultset2.js               | Executes a query and uses a ResultSet to fetch batches of rows with `getRows()`
+resultsettoquerystream.js   | Converts a ResultSet returned from `execute()` into a Readable Stream.
+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
+soda1.js                    | Basic Simple Oracle Document Access (SODA) example
+version.js                  | Shows the node-oracledb version attributes
+webappawait.js              | A simple web application using a connection pool

javascript/node-oracledb/aqmulti.js

@@ -0,0 +1,100 @@
+/* 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
+ *   aqmulti.js
+ *
+ * DESCRIPTION
+ *   Oracle Advanced Queuing (AQ) example passing multiple messages.
+ *
+ *   Before running this, a queue allowing RAW payloads must be
+ *   created, see https://oracle.github.io/node-oracledb/doc/api.html#aqrawexample
+ *
+ *   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 = "DEMO_RAW_QUEUE";
+
+async function enq() {
+  let connection;
+
+  try {
+    connection = await oracledb.getConnection(dbConfig);
+    const queue = await connection.getQueue(queueName);
+    queue.enqOptions.visibility = oracledb.AQ_VISIBILITY_IMMEDIATE; // Send a message without requiring a commit
+
+    console.log('Enqueuing messages');
+
+    const messages = [
+      "Message 1",
+      "Message 2",
+      {
+        expiration: 5,
+        payload: "Message 3"
+      },
+      "Message 4"
+    ];
+    await queue.enqMany(messages);  // !! Review the enqMany() documentation's caveat before using it !!
+
+  } 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.getQueue(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 (const msg of messages) {
+      console.log(msg.payload.toString());
+    }
+
+  } catch (err) {
+    console.error(err);
+  } finally {
+    if (connection) {
+      try {
+        await connection.close();
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+}
+
+enq();
+deq();

javascript/node-oracledb/aqobject.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.getQueue(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.getQueue(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();