Sync /lib with master

Author: Christopher Jones

lib/connection.js

@@ -24,6 +24,7 @@ var QueryStream = require('./querystream.js');
 var nodbUtil = require('./util.js');
 var executePromisified;
 var commitPromisified;
+var createLobPromisified;
 var rollbackPromisified;
 var releasePromisified;
 var breakPromisified;
@@ -146,6 +147,18 @@ function commit(commitCb) {
 
 commitPromisified = nodbUtil.promisify(commit);
 
+// This createLob function is just a place holder to allow for easier extension later.
+function createLob(type, createLobCb) {
+  var self = this;
+
+  nodbUtil.assert(arguments.length === 2, 'NJS-009');
+  nodbUtil.assert(typeof createLobCb === 'function', 'NJS-006', 2);
+
+  self._createLob.apply(self, arguments);
+}
+
+createLobPromisified = nodbUtil.promisify(createLob);
+
 // This rollback function is just a place holder to allow for easier extension later.
 function rollback(rollbackCb) {
   var self = this;
@@ -159,23 +172,19 @@ function rollback(rollbackCb) {
 rollbackPromisified = nodbUtil.promisify(rollback);
 
 // This release function is used to override the release method of the Connection
-// class, which is defined in the C layer. Currently the main difference is that
-// connections obtained from a pool need to invoke the pool's _onConnectionRelease
-// method so the pool can dequeue the next connection request.
+// class, which is defined in the C layer.
 function release(releaseCb) {
   var self = this;
 
   nodbUtil.assert(arguments.length === 1, 'NJS-009');
   nodbUtil.assert(typeof releaseCb === 'function', 'NJS-006', 1);
 
   self._release(function(err) {
-    releaseCb(err);
-
-    // pool will only exist for connections obtained from a pool.
-    if (self._pool && self._pool.queueRequests !== false) {
-      self._pool._onConnectionRelease();
+    if (!err) {
+      self.emit('_after_close');
     }
 
+    releaseCb(err);
   });
 }
 
@@ -198,6 +207,8 @@ breakPromisified = nodbUtil.promisify(module.break);
 // custom properties and method overrides. References to the original methods are
 // maintained so they can be invoked by the overriding method at the right time.
 function extend(conn, oracledb, pool) {
+  nodbUtil.makeEventEmitter(conn);
+
   // Using Object.defineProperties to add properties to the Connection instance with
   // special properties, such as enumerable but not writable.
   Object.defineProperties(
@@ -206,7 +217,7 @@ function extend(conn, oracledb, pool) {
       _oracledb: { // storing a reference to the base instance to avoid circular references with require
         value: oracledb
       },
-      _pool: {
+      _pool: { // storing a reference to the pool, if any, from which the connection was obtained
         value: pool
       },
       _execute: {
@@ -230,6 +241,14 @@ function extend(conn, oracledb, pool) {
         enumerable: true,
         writable: true
       },
+      _createLob: {
+        value: conn.createLob
+      },
+      createLob: {
+        value: createLobPromisified,
+        enumerable: true,
+        writable: true
+      },
       _rollback: {
         value: conn.rollback
       },

lib/lob.js

@@ -21,19 +21,27 @@
 
 var Duplex = require('stream').Duplex;
 var util = require('util');
+var nodbUtil = require('./util.js');
+var closePromisified;
 
 util.inherits(Lob, Duplex);
 
 // The Lob class is used to support the streaming of LOB data to/from the database.
-function Lob(iLob, opt) {
+function Lob(iLob, opt, oracledb) {
   Duplex.call(this, opt);
 
   this.iLob = iLob;
-  this.once('finish', this.close);
 
   Object.defineProperties(
     this,
     {
+      _oracledb: { // _oracledb property used by promisify () in util.js
+        value: oracledb
+      },
+      _autoCloseLob: { // Tells whether to close at the end of stream or not
+        value: iLob.autoCloseLob,
+        writable: false
+      },
       chunkSize: {
         value: iLob.chunkSize,
         writable: false
@@ -55,8 +63,17 @@ function Lob(iLob, opt) {
         get: function() {
           return iLob.type;
         }
+      },
+      close: {
+        value: closePromisified,
+        enumerable: true,
+        writable: true
       }
     });
+
+  if (this._autoCloseLob) {
+    this.once('finish', this._closeSync);
+  }
 }
 
 Lob.prototype._read = function() {
@@ -65,24 +82,29 @@ Lob.prototype._read = function() {
   self.iLob.read(
     function(err, str) {
       if (err) {
-        self.close(); // Ignore if any error occurs during close
+        if (self._autoCloseLob) {
+          // Ignore if any error occurs during close
+          // Emits 'close' event after closing LOB
+          self._closeSync();
+        }
+
         self.emit('error', err);
-        self.emit('close');
         return;
       }
 
       self.push(str);
 
-      if (!str) {
-        process.nextTick(function() {
-          err = self.close();
-
-          if (err) {
-            self.emit('error', err);
-          }
+      if (self._autoCloseLob) {
+        if (!str) {
+          process.nextTick(function() {
+            err = self._closeSync(); // Emits 'close' event after closing LOB
 
-          self.emit('close');
-        });
+            if (err) {
+              self.emit('error', err);
+              return;
+            }
+          });
+        }
       }
     }
   );
@@ -95,32 +117,57 @@ Lob.prototype._write = function(data, encoding, cb) {
     data,
     function(err) {
       if (err) {
-        self.close();   // Ignore if any error occurs during close
-        return cb(err);
+        self._closeSync();   // Ignore if any error occurs during close
+        cb(err);
+        return;
       }
 
       cb();
     }
   );
 };
 
-Lob.prototype.close = function(cb) {
+// This function will be deprecated in the future
+// This internal function used to close the LOB at the end of writable
+// stream in synchronus way to avoid race condition between this function and
+// application's listener function on 'finish' event.
+Lob.prototype._closeSync = function() {
   var self = this;
 
-  if (cb) {
-    this.once('close', cb);
-  }
-
-  if (self.iLob != null) {
+  if (self.iLob !== null) {
     try {
       self.iLob.release();
     } catch(err) {
-        self.iLob = null;
-        return err;
+      self.iLob = null;
+      return err;
     }
 
-    self.iLob = null;
+    self.emit('close');
   }
 };
 
+Lob.prototype.close = function(closeCb) {
+  var self = this;
+
+  nodbUtil.assert(arguments.length === 1, 'NJS-009');
+  nodbUtil.assert(typeof closeCb === 'function', 'NJS-006', 1);
+
+  // Return if LOB already closed to support multiple close() calls should be
+  // no-op
+  if (!self.iLob.valid) {
+    closeCb(null);
+    return;
+  }
+
+  self.iLob.close(function(err) {
+    if (!err) {
+      self.emit('close');
+    }
+
+    closeCb(err);
+  });
+};
+
+closePromisified = nodbUtil.promisify(Lob.prototype.close);
+
 module.exports.Lob = Lob;