Add support to fetch XML as a String in Thin mode

Author: sharadraju

doc/src/release_notes.rst

@@ -25,7 +25,8 @@ Common Changes
 
 #)  Added constant ``oracledb.DB_TYPE_XMLTYPE`` to represent data of type
     ``SYS.XMLTYPE`` in metadata ``fetchType`` and ``dbType`` attributes.
-    Previously the constant used was ``oracledb.DB_TYPE_LONG`` in Thick mode.
+    Previously the constant used was ``oracledb.DB_TYPE_LONG`` in Thick mode
+    and ``oracledb.DB_TYPE_OBJECT`` in Thin mode.
 
 #)  Added support for using the Azure and Oracle Cloud Infrastructure (OCI)
     Software Development Kits (SDKs) to generate
@@ -59,6 +60,10 @@ Common Changes
 Thin Mode Changes
 ++++++++++++++++++
 
+#)  Added support for fetching SYS.XMLTYPE data as strings. Note that unlike in
+    Thick mode, fetching longer values does not require using
+    ``XMLTYPE.GETCLOBVAL()``.
+
 #)  Fixed bug in parsing SQL statements containing multi-line comments
     with multiple asterisks before the closing slash.
     `Issue #1625 <https://github.com/oracle/node-oracledb/issues/1625>`__.

doc/src/user_guide/appendix_a.rst

@@ -764,7 +764,7 @@ when binding numeric values.
       - Thick mode only
     * - XMLType
       - DB_TYPE_XMLTYPE
-      - Thick mode only
+      - Yes
 
 .. _testingmode:
 

lib/errors.js

@@ -136,6 +136,7 @@ const ERR_WRONG_VALUE_FOR_DBOBJECT_ELEM = 135;
 const ERR_WRONG_CRED_FOR_EXTAUTH = 136;
 const ERR_MISSING_BIND_VALUE = 137;
 const ERR_SERVER_VERSION_NOT_SUPPORTED = 138;
+const ERR_UNEXPECTED_XML_TYPE = 139;
 
 // Oracle Net layer errors start from 500
 const ERR_CONNECTION_CLOSED = 500;
@@ -393,6 +394,8 @@ messages.set(ERR_MISSING_BIND_VALUE,                    // NJS-137
   'a bind variable replacement value for placeholder ":%s" was not provided');
 messages.set(ERR_SERVER_VERSION_NOT_SUPPORTED,          // NJS-138
   'connections to this database server version are not supported by node-oracledb in Thin mode');
+messages.set(ERR_UNEXPECTED_XML_TYPE,                   // NJS-139
+  'unexpected XML type with flag %d');
 
 // Oracle Net layer errors
 
@@ -772,6 +775,7 @@ module.exports = {
   ERR_WRONG_CRED_FOR_EXTAUTH,
   ERR_MISSING_BIND_VALUE,
   ERR_SERVER_VERSION_NOT_SUPPORTED,
+  ERR_UNEXPECTED_XML_TYPE,
   ERR_CONNECTION_CLOSED_CODE: `${ERR_PREFIX}-${ERR_CONNECTION_CLOSED}`,
   assert,
   assertArgCount,

lib/impl/resultset.js

@@ -147,6 +147,17 @@ class ResultSetImpl {
         } else if (metadata.dbType === types.DB_TYPE_RAW) {
           converter = (v) => (v === null) ? null : v.toString('hex').toUpperCase();
         }
+      } else if (metadata.dbType === types.DB_TYPE_XMLTYPE) {
+        const xmlConverter = async function(val) {
+          if (!val) {
+            return val;
+          }
+          if (typeof val === 'string') {
+            return val;
+          }
+          return await val.getData();
+        };
+        converter = xmlConverter;
       }
       if (userConverter && converter) {
         const internalConverter = converter;

lib/thin/dbObject.js

@@ -32,6 +32,7 @@ const errors = require('../errors.js');
 const types = require('../types.js');
 const DbObjectImpl = require('../impl/dbObject.js');
 const { GrowableBuffer } = require('./protocol/buffer.js');
+const ThinLobImpl = require('./lob.js');
 
 class DbObjectPickleBuffer extends GrowableBuffer {
 
@@ -652,4 +653,37 @@ class ThinDbObjectImpl extends DbObjectImpl {
 
 }
 
-module.exports = ThinDbObjectImpl;
+//---------------------------------------------------------------------------
+// readXML()
+//
+// Decodes the raw Bytes to XML string or LOB object.
+//
+//---------------------------------------------------------------------------
+function readXML(conn, buf) {
+  let colValue;
+
+  const xmlObj = new DbObjectPickleBuffer(buf);
+  const tempobj = {};
+  xmlObj.readHeader(tempobj);
+  xmlObj.skipBytes(1);
+  const xmlflag = xmlObj.readUInt32BE();
+  if (xmlflag & constants.TNS_XML_TYPE_FLAG_SKIP_NEXT_4) {
+    xmlObj.skipBytes(4);
+  }
+  const numBytesLeft = xmlObj.numBytesLeft();
+  const ptr = xmlObj.readBytes(numBytesLeft);
+  if (xmlflag & constants.TNS_XML_TYPE_STRING) {
+    colValue = ptr.toString();
+  } else if (xmlflag & constants.TNS_XML_TYPE_LOB) {
+    const lobImpl = new ThinLobImpl();
+    const locator = Buffer.from(ptr);
+    lobImpl.init(conn, locator, types.DB_TYPE_CLOB, 0, 0);
+    colValue = lobImpl;
+  } else {
+    // We only support String and Clob type.
+    errors.throwErr(errors.ERR_UNEXPECTED_XML_TYPE, xmlflag);
+  }
+  return colValue;
+}
+
+module.exports = { ThinDbObjectImpl, readXML };

lib/thin/index.js

@@ -30,7 +30,7 @@ const ThinConnectionImpl = require('./connection.js');
 const ThinResultSetImpl = require('./resultSet.js');
 const ThinPoolImpl = require('./pool.js');
 const ThinLobImpl = require('./lob.js');
-const ThinDbObjectImpl = require('./dbObject.js');
+const { ThinDbObjectImpl } = require('./dbObject.js');
 
 const impl = require('../impl');
 impl.ConnectionImpl = ThinConnectionImpl;

lib/thin/protocol/messages/withData.js

@@ -30,7 +30,7 @@ const { Buffer } = require('buffer');
 const utils = require("../utils");
 const constants = require("../constants.js");
 const Message = require("./base.js");
-const ThinDbObjectImpl = require("../../dbObject.js");
+const { ThinDbObjectImpl, readXML } = require("../../dbObject.js");
 const ThinLobImpl = require("../../lob.js");
 const errors = require('../../../errors');
 const types = require('../../../types.js');
@@ -277,6 +277,9 @@ class MessageWithData extends Message {
         if (fetchInfo.dbTypeClass.partial) {
           this.connection._partialDbObjectTypes.push(fetchInfo.dbTypeClass);
         }
+        if (fetchInfo.dbTypeClass.isXmlType) {
+          fetchInfo.dbType = types.DB_TYPE_XMLTYPE;
+        }
         break;
       default:
         break;
@@ -483,9 +486,14 @@ class MessageWithData extends Message {
       if (obj.packedData) {
         const objType = (variable.fetchInfo) ? variable.fetchInfo.dbTypeClass :
           variable.typeClass;
-        colValue = new ThinDbObjectImpl(objType, obj.packedData);
-        colValue.toid = obj.toid;
-        colValue.oid = obj.oid;
+
+        if (variable.type === types.DB_TYPE_XMLTYPE) {
+          colValue = readXML(this.connection, obj.packedData);
+        } else {
+          colValue = new ThinDbObjectImpl(objType, obj.packedData);
+          colValue.toid = obj.toid;
+          colValue.oid = obj.oid;
+        }
       }
     } else {
       errors.throwErr(errors.ERR_UNSUPPORTED_DATA_TYPE, dbType.num,

test/dataTypeXML.js

@@ -54,9 +54,6 @@ describe('181. dataTypeXML.js', function() {
     '</Warehouse>\n';
 
   before('create table and insert a row', async function() {
-    if (oracledb.thin) {
-      this.skip();
-    }
 
     const connection = await oracledb.getConnection(dbConfig);
 
@@ -74,8 +71,9 @@ describe('181. dataTypeXML.js', function() {
       "    EXECUTE IMMEDIATE (' \n" +
       "        CREATE TABLE " + tableName + " ( \n" +
       "            num        number(9) not null, \n" +
-      "            content    xmltype not null \n" +
-      "        ) \n" +
+      "            content    xmltype not null, \n" +
+      "            embedLOBXML xmltype          \n" +
+      "        ) XMLTYPE embedLOBXML STORE AS CLOB\n" +
       "    '); \n" +
       "END; ";
     await connection.execute(sql);
@@ -106,19 +104,17 @@ describe('181. dataTypeXML.js', function() {
   it('181.1 basic case, insert XML data and query back', async () => {
     const conn = await oracledb.getConnection(dbConfig);
     const sql = "select content from " + tableName + " where num = :id";
-    const expectedMetadata = {
-      name: 'CONTENT',
-      dbType: oracledb.DB_TYPE_XMLTYPE,
-      nullable: false,
-      isJson: false,
-      dbTypeName: 'XMLTYPE',
-      fetchType: oracledb.DB_TYPE_XMLTYPE
-    };
     const bindVar = { id: testRowID };
     const options = { outFormat: oracledb.OUT_FORMAT_OBJECT };
-    const result = await conn.execute(sql, bindVar, options);
-    assert.strictEqual(result.rows[0].CONTENT, testXMLData);
-    assert.deepStrictEqual(result.metaData[0], expectedMetadata);
+
+    // test execute and re-execute
+    for (let i = 0; i < 2; i++) {
+      const result = await conn.execute(sql, bindVar, options);
+      assert.strictEqual(result.rows[0].CONTENT, testXMLData);
+      assert.strictEqual(result.metaData[0].dbType, oracledb.DB_TYPE_XMLTYPE);
+      assert.strictEqual(result.metaData[0].fetchType, oracledb.DB_TYPE_XMLTYPE);
+    }
+
     await conn.close();
   }); // 181.1
 
@@ -182,9 +178,7 @@ describe('181. dataTypeXML.js', function() {
     await conn.close();
   }); // 181.4
 
-  // ORA-19011: Character string buffer too small
-  it.skip('181.5 inserts data that is larger than 4K', async () => {
-
+  it('181.5 inserts data that is larger than 4K', async () => {
     const ID = 50;
     const str = 'a'.repeat(31 * 1024);
     const head = '<data>', tail = '</data>\n';
@@ -197,13 +191,60 @@ describe('181. dataTypeXML.js', function() {
     let result = await conn.execute(sql, bindValues);
     assert.strictEqual(result.rowsAffected, 1);
 
-    sql = "select content from " + tableName + " where num = :id";
     const bindVar = { id: ID };
     const options = { outFormat: oracledb.OUT_FORMAT_OBJECT };
-    result = await conn.execute(sql, bindVar, options);
-    assert.strictEqual(result.rows[0].CONTENT, xml);
+    if (oracledb.thin) {
+      sql = "select content from " + tableName + " where num = :id";
+      result = await conn.execute(sql, bindVar, options);
+      assert.strictEqual(result.rows[0].CONTENT, xml);
+    } else {
+      // For thick, we get an error ORA-19011: Character string buffer too small, so use getclobval
+      options.fetchInfo = { "OBJ": { type: oracledb.STRING } };
+      sql = "select xmltype.getclobval(content) as obj from " + tableName + " where num = :id";
+      result = await conn.execute(sql, bindVar, options);
+      assert.strictEqual(result.rows[0].OBJ, xml);
+    }
     await conn.commit();
     await conn.close();
   }); // 181.5
 
+  it('181.6 Insert and Verify Embedded LOB locator inside XML', async () => {
+    const ID = 51;
+    const largestr = 'a'.repeat(64 * 1024);
+    const smallstr = 'a'.repeat(1 * 1024);
+    const head = '<data>', tail = '</data>\n';
+    const xml = head.concat(smallstr).concat(tail);
+    const largexml = head.concat(largestr).concat(tail);
+
+    const conn = await oracledb.getConnection(dbConfig);
+    const lob = await conn.createLob(oracledb.CLOB);
+    await lob.write(largexml);
+
+    let sql = `insert into  ${tableName}  ( num, content, embedLOBXML )
+      values(:id, XMLType(:bv1), XMLType(:bv2))`;
+    const bindValues = { id: ID, bv1: xml, bv2: {type: oracledb.CLOB, val: lob }};
+    let result = await conn.execute(sql, bindValues);
+    assert.strictEqual(result.rowsAffected, 1);
+
+    const bindVar = { id: ID };
+    const options = { outFormat: oracledb.OUT_FORMAT_OBJECT };
+
+    if (oracledb.thin) {
+      sql = "select embedlobxml as OBJ from " + tableName + " where num = :id";
+    } else {
+      options.fetchInfo = {"OBJ": {type: oracledb.STRING}};
+      sql = "select xmltype.getclobval(embedlobxml) as OBJ from " + tableName + " where num = :id";
+    }
+    result = await conn.execute(sql, bindVar, options);
+    assert.strictEqual(result.rows[0].OBJ, largexml);
+
+    // free  temp lob
+    await new Promise((resolve) => {
+      lob.once('close', resolve);
+      lob.destroy();
+    });
+    await conn.commit();
+    await conn.close();
+  }); // 181.6
+
 });

test/dbObject1.js

@@ -120,7 +120,14 @@ describe('200. dbObject1.js', () => {
     assert.strictEqual(result.rowsAffected, 1);
     await conn.commit();
 
+    const options = {};
     sql = `SELECT * FROM ${TABLE} WHERE num = ${seq}`;
+    options.fetchInfo = {"PERSON": { type: oracledb.STRING }};
+    await assert.rejects(
+      async () => await conn.execute(sql, [], options),
+      /NJS-119:/
+    );
+
     result = await conn.execute(sql);
 
     assert.strictEqual(result.rows[0][0], seq);