oracledb 6.2.0 → 6.4.0

package/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2015, 2023 Oracle and/or its affiliates.
+Copyright (c) 2015, 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

package/NOTICE.txt

@@ -1 +1 @@
-Copyright (c) 2015, 2023, Oracle and/or its affiliates.
+Copyright (c) 2015, 2024, Oracle and/or its affiliates.

package/README.md

@@ -1,10 +1,10 @@
-# node-oracledb version 6.2.0
+# node-oracledb version 6.4.0
 
 The node-oracledb add-on for Node.js powers high performance Oracle Database
 applications.  Applications can be written in TypeScript, or directly in
 JavaScript.
 
-Use node-oracledb 6.2.0 to connect Node.js 14.6, or later, to Oracle
+Use node-oracledb 6.4.0 to connect Node.js 14.6, or later, to Oracle
 Database.  Older versions of node-oracledb may work with older versions of
 Node.js.
 
@@ -48,7 +48,7 @@ vulnerability disclosure process.
 
 ## License
 
-Copyright (c) 2015, 2023, Oracle and/or its affiliates.
+Copyright (c) 2015, 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

package/build/Release/oracledb-6.4.0-darwin-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-6.4.0-darwin-x64.node v18.17.0 df971fa2503fcf9ab4a63f2f2508f5fb5780c0e1 31cd3b6682f32ad860df63d1dd06e3bf1c5e62aa Thu, 29 Feb 2024 13:53:47 GMT

package/build/Release/oracledb-6.4.0-js-buildinfo.txt

@@ -0,0 +1 @@
+df971fa2503fcf9ab4a63f2f2508f5fb5780c0e1

package/build/Release/oracledb-6.4.0-linux-arm64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-6.4.0-linux-arm64.node v18.19.0 df971fa2503fcf9ab4a63f2f2508f5fb5780c0e1 31cd3b6682f32ad860df63d1dd06e3bf1c5e62aa Thu, 29 Feb 2024 15:01:23 GMT

package/build/Release/oracledb-6.4.0-linux-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-6.4.0-linux-x64.node v16.20.2 df971fa2503fcf9ab4a63f2f2508f5fb5780c0e1 31cd3b6682f32ad860df63d1dd06e3bf1c5e62aa Thu, 29 Feb 2024 14:56:18 GMT

package/build/Release/oracledb-6.4.0-win32-x64.node-buildinfo.txt

@@ -0,0 +1 @@
+oracledb-6.4.0-win32-x64.node v18.16.0 df971fa2503fcf9ab4a63f2f2508f5fb5780c0e1 31cd3b6682f32ad860df63d1dd06e3bf1c5e62aa Thu, 29 Feb 2024 15:35:39 GMT

package/examples/README.md

@@ -1,8 +1,7 @@
 # Node-oracledb Examples
 
-The directory in node-oracledb's [Github repository](https://github.com/oracle/node-oracledb/tree/main/examples) contains a lot of [node-oracledb](https://www.npmjs.com/package/oracledb)
-examples.  Documentation is
-[here](https://node-oracledb.readthedocs.io/en/latest/).
+The directory in node-oracledb's [Github repository](https://github.com/oracle/node-oracledb/tree/main/examples) contains a lot of [node-oracledb](https://www.npmjs.com/package/oracledb) examples.
+Documentation is [here](https://node-oracledb.readthedocs.io/en/latest/).
 
 To run the examples:
 
@@ -11,18 +10,37 @@ To run the examples:
 - Ensure that you navigate to the `examples` directory in your terminal window
   or IDE, where you are running the samples.
 
-- Review `dbconfig.js`.  In your terminal window or IDE, set the environment
-  variables.  For example, set `NODE_ORACLEDB_PASSWORD` to the value of your
-  database password.
+- Review `dbconfig.js`.
 
-- Review the samples and then run them individually.  For example, to see what
+In your terminal window or IDE, set the following environment variables to
+provide credentials for the `dbconfig.js` file.
+
+- `NODE_ORACLEDB_USER` must be set to the database user.
+
+- `NODE_ORACLEDB_PASSWORD` must be set to the database password.
+
+- `NODE_ORACLEDB_CONNECTIONSTRING` must be set to the connection string that points to your database's location.
+
+- `NODE_ORACLEDB_EXTERNALAUTH` provides the options for enabling external authentication. Setting this environment variable to "true" will enable external authentication. To ensure external authentication works, firstly make sure the Oracle external authentication service is correctly configured. See [Documentation for External Authentication](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#extauth) for details.
+
+- `NODE_ORACLEDB_DRIVER_MODE` provides an option to set the 'Thin' or 'Thick' modes of node-oracledb. Setting this environment variable to "thick" will enable Thick mode.
+Setting it to "thin" will retain the Thin mode. The default mode is Thin.
+
+- `NODE_ORACLEDB_WALLET_LOCATION` must be set to the local directory name for the wallets that may be required for mutual TLS (mTLS) connections, especially to Oracle Cloud
+Autonomous Databases optionally. The wallet location can also be provided as a part of the database connect string.
+
+- `NODE_ORACLEDB_WALLET_PASSWORD` must set to the password for the wallets that may be required for mutual TLS (mTLS) connections, especially to Oracle Cloud Autonomous Databases.
+
+- `NODE_ORACLEDB_CLIENT_LIB_DIR` provides an optional path for the Oracle Client libraries to be used on Windows and macOS platforms, when using Thick mode in node-oracledb.
+
+Review the examples and then run them individually.  For example, to see what
   the file `example.js` does, use:
 
   ```
   node example.js
   ```
 
-- After running examples, the demonstration objects can be dropped with
+After running the examples, the demonstration objects can be dropped with
   `demodrop.js`:
 
   ```
@@ -45,6 +63,7 @@ File Name                                                 | Description
 [`aqobject.js`](aqobject.js)                              | Oracle Advanced Queuing (AQ) example passing an Oracle Database object
 [`aqoptions.js`](aqoptions.js)                            | Oracle Advanced Queuing (AQ) example setting options and message attributes
 [`aqraw.js`](aqraw.js)                                    | Basic Oracle Advanced Queuing (AQ) example passing text messages
+[`aqutil.js`](aqutil.js)                                  | Common file to setup the user credentials for all the Advanced Queuing (AQ) examples.
 [`blobhttp.js`](blobhttp.js)                              | Simple web app that streams an image
 [`calltimeout.js`](calltimeout.js)                        | Shows how to cancel a SQL statement if it doesn't complete in a specified time
 [`connect.js`](connect.js)                                | Basic example for creating a standalone (non-pooled) connection
@@ -94,6 +113,8 @@ File Name                                                 | Description
 [`resultset2.js`](resultset2.js)                          | Executes a query and uses a ResultSet to fetch batches of rows with `getRows()`
 [`resultsettoquerystream.js`](resultsettoquerystream.js)  | Converts a ResultSet returned from `execute()` into a Readable Stream.
 [`rowlimit.js`](rowlimit.js)                              | Shows ways to limit the number of records fetched by queries
+[`sampleazuretokenauth.js`](sampleazuretokenauth.js)      | Shows connection pooling with Azure token based authentication.
+[`sampleocitokenauth.js`](sampleocitokenauth.js)          | Shows connection pooling with OCI OAuth 2.0 token based authentication.
 [`select1.js`](select1.js)                                | Executes a basic query without using a connection pool or ResultSet
 [`select2.js`](select2.js)                                | Executes queries to show array and object output formats
 [`selectgeometry.js`](selectgeometry.js)                  | Insert and query Oracle Spatial geometries

package/examples/dbconfig.js

@@ -26,17 +26,16 @@
  *   dbconfig.js
  *
  * DESCRIPTION
- *   Holds the credentials used by node-oracledb examples to connect
- *   to the database.  Production applications should consider using
- *   External Authentication to avoid hard coded credentials.
+ *   Holds the credentials used by node-oracledb examples to connect to the
+ *   database. Production applications should consider using External
+ *   Authentication to avoid hard coded credentials.
  *
  *   To create a database user, see
  *   https://blogs.oracle.com/sql/post/how-to-create-users-grant-them-privileges-and-remove-them-in-oracle-database
  *
- *   Applications can set the connectString value to an Easy Connect
- *   string, or a Net Service Name from a tnsnames.ora file or
- *   external naming service, or it can be the name of a local Oracle
- *   database instance.
+ *   Applications can set the connectString value to an Easy Connect string,
+ *   or a Net Service Name from the tnsnames.ora file or an external naming
+ *   service, or it can be the name of a local Oracle Database instance.
  *
  *   If node-oracledb is linked with Instant Client, then an Easy
  *   Connect string is generally appropriate.  The basic syntax is:
@@ -50,20 +49,20 @@
  *   refer to the latest Oracle documentation on Easy Connect syntax:
  *   https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-B0437826-43C1-49EC-A94D-B650B6A4A6EE
  *
- *   If using a tnsnames.ora file, the file can be in a default
- *   location such as $ORACLE_HOME/network/admin/tnsnames.ora or
- *   /etc/tnsnames.ora.  Alternatively set the TNS_ADMIN environment
- *   variable and put the file in $TNS_ADMIN/tnsnames.ora.
+ *   If using a tnsnames.ora file, the file can be in a default location such
+ *   as $ORACLE_HOME/network/admin/tnsnames.ora or /etc/tnsnames.ora.
+ *   Alternatively set the TNS_ADMIN environment variable and put the file in
+ *   $TNS_ADMIN/tnsnames.ora.
  *
- *   If connectString is not specified, the empty string "" is used
- *   which indicates to connect to the local, default database.
+ *   If connectString is not specified, the empty string "" is used which
+ *   indicates to connect to the local, default database.
  *
- *   External Authentication can be used by setting the optional
- *   property externalAuth to true.  External Authentication allows
- *   applications to use an external password store such as Oracle
- *   Wallet so passwords do not need to be hard coded into the
- *   application.  The user and password properties for connecting or
- *   creating a pool should not be set when externalAuth is true.
+ *   External Authentication can be used by setting the optional property
+ *   externalAuth to true. External Authentication allows applications to use
+ *   an external password store such as Oracle Wallet, so that passwords
+ *   do not need to be hard coded into the application. The user and password
+ *   application. The user and password properties for connecting or creating
+ *   a pool should not be set when externalAuth is true.
  *
  * TROUBLESHOOTING
  *   Refer to the Error Handling section in node-oracledb documentation
@@ -73,21 +72,46 @@
  *
  *****************************************************************************/
 
-module.exports = {
-  user          : process.env.NODE_ORACLEDB_USER,
+const config = {
+  user: process.env.NODE_ORACLEDB_USER,
 
   // Get the password from the environment variable
   // NODE_ORACLEDB_PASSWORD.  The password could also be a hard coded
   // string (not recommended), or it could be prompted for.
-  // Alternatively use External Authentication so that no password is
-  // needed.
-  password      : process.env.NODE_ORACLEDB_PASSWORD,
+  // Alternatively use External Authentication so that no password is needed.
+  password: process.env.NODE_ORACLEDB_PASSWORD,
 
   // For information on connection strings see:
   // https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connectionstrings
-  connectString : process.env.NODE_ORACLEDB_CONNECTIONSTRING,
+  connectString: process.env.NODE_ORACLEDB_CONNECTIONSTRING,
 
   // Setting externalAuth is optional.  It defaults to false.  See:
   // https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#extauth
-  externalAuth  : process.env.NODE_ORACLEDB_EXTERNALAUTH ? true : false,
+  externalAuth: process.env.NODE_ORACLEDB_EXTERNALAUTH ? true : false,
 };
+
+// Set the NODE_ORACLEDB_WALLET_LOCATION and NODE_ORACLEDB_WALLET_PASSWORD
+// environment variables for database connections that require wallets.
+// For example, creating and dropping a user.
+// See the README.md file in this directory for more details.
+if (process.env.NODE_ORACLEDB_WALLET_PASSWORD) {
+  config.walletPassword = process.env.NODE_ORACLEDB_WALLET_PASSWORD;
+}
+
+if (process.env.NODE_ORACLEDB_WALLET_LOCATION) {
+  config.walletLocation = process.env.NODE_ORACLEDB_WALLET_LOCATION;
+}
+
+// Set the NODE_ORACLEDB_DBA_USER and NODE_ORACLEDB_DBA_PASSWORD environment
+// variables for database operations which require SYSDBA privileges.
+// For example, creating and dropping a user. See the README.md file in this
+// directory for more details.
+if (process.env.NODE_ORACLEDB_DBA_USER) {
+  config.DBA_user = process.env.NODE_ORACLEDB_DBA_USER;
+}
+
+if (process.env.NODE_ORACLEDB_DBA_PASSWORD) {
+  config.DBA_password = process.env.NODE_ORACLEDB_DBA_PASSWORD;
+}
+
+module.exports = config;

package/examples/example.js

@@ -54,14 +54,16 @@ if (process.env.NODE_ORACLEDB_DRIVER_MODE === 'thick') {
   // is not correct, you will get a DPI-1047 error.  See the node-oracledb
   // installation documentation.
   let clientOpts = {};
-  if (process.platform === 'win32') {                                   // Windows
-    clientOpts = { libDir: 'C:\\oracle\\instantclient_19_17' };
-  } else if (process.platform === 'darwin' && process.arch === 'x64') { // macOS Intel
-    clientOpts = { libDir: process.env.HOME + '/Downloads/instantclient_19_8' };
+  // On Windows and macOS Intel platforms, set the environment
+  // variable NODE_ORACLEDB_CLIENT_LIB_DIR to the Oracle Client library path
+  if (process.platform === 'win32' || (process.platform === 'darwin' && process.arch === 'x64')) {
+    clientOpts = { libDir: process.env.NODE_ORACLEDB_CLIENT_LIB_DIR };
   }
   oracledb.initOracleClient(clientOpts);  // enable node-oracledb Thick mode
 }
 
+console.log(oracledb.thin ? 'Running in thin mode' : 'Running in thick mode');
+
 async function run() {
   let connection;
 

package/lib/aqQueue.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2019, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2019, 2024, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -169,7 +169,7 @@ class AqQueue {
     errors.assertArgCount(arguments, 1, 1);
     errors.assertParamValue(Number.isInteger(maxMessages) && maxMessages > 0,
       1);
-    const msgImpls = await this._impl.deqMany(maxMessages);
+    const msgImpls = await this._impl.deq(maxMessages);
     return  msgImpls.map(i => this._makeMessage(i));
   }
 
@@ -180,9 +180,9 @@ class AqQueue {
   //---------------------------------------------------------------------------
   async deqOne() {
     errors.assertArgCount(arguments, 0, 0);
-    const msgImpl = await this._impl.deqOne();
-    if (msgImpl)
-      return this._makeMessage(msgImpl);
+    const msgImpls = await this._impl.deq(1);
+    if (msgImpls)
+      return this._makeMessage(msgImpls[0]);
   }
 
   //---------------------------------------------------------------------------
@@ -212,7 +212,7 @@ class AqQueue {
     for (let i = 0; i < messages.length; i++) {
       verifiedMessages[i] = this._verifyMessage(messages[i]);
     }
-    const msgImpls = await this._impl.enqMany(verifiedMessages);
+    const msgImpls = await this._impl.enq(verifiedMessages);
     return msgImpls.map(i => this._makeMessage(i));
   }
 
@@ -224,8 +224,8 @@ class AqQueue {
   async enqOne(message) {
     errors.assertArgCount(arguments, 1, 1);
     message = this._verifyMessage(message);
-    const msgImpl = await this._impl.enqOne(message);
-    return this._makeMessage(msgImpl);
+    const msgImpls = await this._impl.enq([message]);
+    return this._makeMessage(msgImpls[0]);
   }
 
   //---------------------------------------------------------------------------

package/lib/connection.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2016, 2024, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -43,6 +43,7 @@ const constants = require('./constants.js');
 const settings = require('./settings.js');
 const transformer = require('./transformer.js');
 const types = require('./types.js');
+const oson = require('./impl/datahandlers/oson.js');
 
 // global mapping of subscriptions; these cannot be tied to a particular
 // connection or pool since subscriptions can be created with one connection
@@ -105,7 +106,10 @@ class Connection extends EventEmitter {
       const cls = this._getDbObjectClass(objType.elementTypeClass);
       objType.elementTypeClass = cls;
     }
-    nodbUtil.addTypeProperties(objType, "elementType");
+    if (objType.isCollection) {
+      nodbUtil.addTypeProperties(objType, "elementType");
+      objType.elementTypeInfo.type = objType.elementType;
+    }
     if (objType.attributes) {
       const props = {};
       for (const attr of objType.attributes) {
@@ -197,6 +201,9 @@ class Connection extends EventEmitter {
       typeof value === 'string' ||
       typeof value === 'boolean' ||
       Array.isArray(value) ||
+      value instanceof Float32Array ||
+      value instanceof Float64Array ||
+      value instanceof Int8Array ||
       Buffer.isBuffer(value) ||
       util.isDate(value) ||
       value instanceof Lob ||
@@ -833,6 +840,29 @@ class Connection extends EventEmitter {
     this._impl.setECID(value);
   }
 
+  //---------------------------------------------------------------------------
+  // decode()
+  //
+  // Decodes OSON Buffer to JS data type.
+  //---------------------------------------------------------------------------
+  decodeOSON(buf) {
+    errors.assertArgCount(arguments, 1, 1);
+    errors.assertParamValue(Buffer.isBuffer(buf), 1);
+    const decoder = new oson.OsonDecoder(buf);
+    return decoder.decode();
+  }
+
+
+  //---------------------------------------------------------------------------
+  // encode()
+  //
+  // Encodes the JS value into OSON bytes.
+  //---------------------------------------------------------------------------
+  encodeOSON(value) {
+    const encoder = new oson.OsonEncoder();
+    return encoder.encode(transformer.transformJsonValue(value));
+  }
+
   //---------------------------------------------------------------------------
   // execute()
   //
@@ -844,13 +874,24 @@ class Connection extends EventEmitter {
     let options = {};
 
     // process arguments
-    errors.assertArgCount(arguments, 1, 3);
-    errors.assertParamValue(typeof sql === 'string', 1);
-    if (arguments.length >= 2) {
-      binds = await this._processExecuteBinds(a2);
-    }
-    if (arguments.length == 3) {
-      options = this._verifyExecOpts(a3, false);
+    if (nodbUtil.isObject(sql) && typeof sql.statement === 'string') {
+      errors.assertArgCount(arguments, 1, 2);
+      if (sql.values) {
+        binds = await this._processExecuteBinds(sql.values);
+      }
+      sql = sql.statement;
+      if (arguments.length == 2) {
+        options = this._verifyExecOpts(a2, false);
+      }
+    } else {
+      errors.assertArgCount(arguments, 1, 3);
+      errors.assertParamValue(typeof sql === 'string', 1);
+      if (arguments.length >= 2) {
+        binds = await this._processExecuteBinds(a2);
+      }
+      if (arguments.length == 3) {
+        options = this._verifyExecOpts(a3, false);
+      }
     }
     this._addDefaultsToExecOpts(options);
     errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
@@ -865,6 +906,11 @@ class Connection extends EventEmitter {
       throw err;
     }
 
+    // convert ORA errors to NJS
+    if (result.warning) {
+      result.warning = errors.transformErr(result.warning);
+    }
+
     // process queries; if a result set is not desired, fetch all of the rows
     // from the result set and then destroy the result set
     if (result.resultSet !== undefined) {
@@ -941,6 +987,11 @@ class Connection extends EventEmitter {
     const result = await this._impl.execute(sql, numIters, binds, options,
       true);
 
+    // convert ORA warnings to NJS
+    if (result.warning) {
+      result.warning = errors.transformErr(result.warning);
+    }
+
     // process output binds
     if (result.outBinds !== undefined) {
       for (let i = 0; i < result.outBinds.length; i++) {
@@ -971,6 +1022,24 @@ class Connection extends EventEmitter {
     this._impl.setExternalName(value);
   }
 
+  //---------------------------------------------------------------------------
+  // dbDomain (READONLY)
+  //
+  // Property for identifying the dbDomain of the Oracle Database.
+  //---------------------------------------------------------------------------
+  get dbDomain() {
+    return this._impl && this._impl.getDbDomain();
+  }
+
+  //---------------------------------------------------------------------------
+  // dbName (READONLY)
+  //
+  // Property for identifying the dbName of the Oracle Database.
+  //---------------------------------------------------------------------------
+  get dbName() {
+    return this._impl && this._impl.getDbName();
+  }
+
   //---------------------------------------------------------------------------
   // getDbObjectClass()
   //
@@ -1080,6 +1149,30 @@ class Connection extends EventEmitter {
       this._impl.isHealthy());
   }
 
+  //---------------------------------------------------------------------------
+  // maxOpenCursors
+  //
+  // Returns maximum number of cursors that can be opened in one session.
+  //---------------------------------------------------------------------------
+  get maxOpenCursors() {
+    return this._impl && this._impl.getMaxOpenCursors();
+  }
+
+  //---------------------------------------------------------------------------
+  // warning
+  //
+  // Returns warningInfo.
+  //---------------------------------------------------------------------------
+  get warning() {
+    let warning = this._impl.getWarning();
+    if (warning) {
+      // Make sure that warning code attribute is populated and ORA error
+      // is converted to NJS, if required
+      warning = errors.transformErr(warning);
+    }
+    return this._impl && warning;
+  }
+
   //---------------------------------------------------------------------------
   // module
   //
@@ -1117,6 +1210,25 @@ class Connection extends EventEmitter {
     return undefined;
   }
 
+  //---------------------------------------------------------------------------
+  // serviceName
+  //
+  // Returns the Oracle Database service name associated with the connection.
+  //---------------------------------------------------------------------------
+  get serviceName() {
+    return this._impl && this._impl.getServiceName();
+  }
+
+  //---------------------------------------------------------------------------
+  // transactionInProgress
+  //
+  // Returns a boolean value based on the presence of an active transaction
+  // on the connection
+  //---------------------------------------------------------------------------
+  get transactionInProgress() {
+    return this._impl && this._impl.getTransactionInProgress();
+  }
+
   //---------------------------------------------------------------------------
   // ping()
   //

package/lib/constants.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -200,4 +200,10 @@ module.exports = {
   // TPC/XA two-phase commit flags
   TPC_END_NORMAL: 0,
   TPC_END_SUSPEND: 0x00100000,
+
+  // vector types
+  VECTOR_FORMAT_FLOAT32: 2,
+  VECTOR_FORMAT_FLOAT64: 3,
+  VECTOR_FORMAT_INT8: 4,
+
 };

package/lib/dbObject.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2019, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2019, 2024, Oracle and/or its affiliates.
 
 //----------------------------------------------------------------------------
 //
@@ -32,6 +32,48 @@ const errors = require('./errors.js');
 const types = require('./types.js');
 const util = require('util');
 
+//---------------------------------------------------------------------------
+// validatePropertyValue
+//
+// Validate the value based on metadata.
+// For object type, metaData corresponds to the attribute which is set.
+// For collection type, metaData corresponds to element in the collection.
+//---------------------------------------------------------------------------
+function validatePropertyValue(objType, metaData, value, index) {
+  let valueLen, lengthErr = false;
+
+  if (value) {
+    switch (metaData.type) {
+      case types.DB_TYPE_VARCHAR:
+      case types.DB_TYPE_NVARCHAR:
+      case types.DB_TYPE_NCHAR:
+      case types.DB_TYPE_CHAR:
+        valueLen = Buffer.byteLength(value);
+        if (valueLen > metaData.maxSize) {
+          lengthErr = true;
+        }
+        break;
+      case types.DB_TYPE_RAW:
+        valueLen = value.length;
+        if (valueLen > metaData.maxSize) {
+          lengthErr = true;
+        }
+        break;
+      default:
+        break;
+    }
+    if (lengthErr) {
+      if (index !== undefined) {
+        errors.throwErr(errors.ERR_WRONG_LENGTH_FOR_DBOBJECT_ELEM,
+          index, objType.fqn, valueLen, metaData.maxSize);
+      } else {
+        errors.throwErr(errors.ERR_WRONG_LENGTH_FOR_DBOBJECT_ATTR,
+          metaData.name, objType.fqn, valueLen, metaData.maxSize);
+      }
+    }
+  }
+}
+
 // define base database object class; instances of this class are never
 // instantiated; instead, classes subclassed from this one will be
 // instantiated; a cache of these classes are maintained on each connection
@@ -61,6 +103,7 @@ class BaseDbObject {
     };
     const options = {allowArray: false};
     value = transformer.transformValueIn(info, value, options);
+    validatePropertyValue(this._objType, attr, value);
     this._impl.setAttrValue(attr, value);
   }
 
@@ -124,6 +167,13 @@ class BaseDbObject {
     };
     const options = {allowArray: false};
     value = transformer.transformValueIn(info, value, options);
+    let index = this._impl.getLastIndex();
+    if (index) {
+      index = index + 1; // element will be appended at index + 1.
+    } else {
+      index = 0; // undefined for initial append, so set it to 0
+    }
+    validatePropertyValue(this._objType, this._objType.elementTypeInfo, value, index);
     this._impl.append(value);
   }
 
@@ -344,6 +394,7 @@ class BaseDbObject {
     };
     const options = {allowArray: false};
     value = transformer.transformValueIn(info, value, options);
+    validatePropertyValue(this._objType, this._objType.elementTypeInfo, value, index);
     this._impl.setElement(index, value);
   }
 
@@ -388,6 +439,25 @@ class BaseDbObject {
     return (this._toPojo());
   }
 
+  //---------------------------------------------------------------------------
+  // toMap()
+  //
+  // Returns the Map object where the collection’s indexes are the keys and
+  // the elements are its values.
+  //---------------------------------------------------------------------------
+  toMap() {
+    errors.assertArgCount(arguments, 0, 0);
+    if (!this.isCollection) {
+      errors.throwErr(errors.ERR_OBJECT_IS_NOT_A_COLLECTION,
+        this.name);
+    }
+    const result = new Map();
+    this.getKeys().forEach(element => {
+      result.set(element, this.getElement(element));
+    });
+    return result;
+  }
+
 }
 
 // method for transforming the error
@@ -421,6 +491,7 @@ wrapFns(BaseDbObject.prototype,
   "getNextIndex",
   "getPrevIndex",
   "getValues",
+  "toMap",
   "hasElement",
   "setElement",
   "trim"