Added support for connection.ping()

Author: cjbj

doc/api.md

@@ -131,9 +131,10 @@ limitations under the License.
                 - 4.2.6.4.3 [`resultSet`](#execresultset)
                 - 4.2.6.4.4 [`rows`](#execrows)
                 - 4.2.6.4.5 [`rowsAffected`](#execrowsaffected)
-        - 4.2.7 [`queryStream()`](#querystream)
-        - 4.2.8 [`release()`](#release)
-        - 4.2.9 [`rollback()`](#rollback)
+        - 4.2.7 [`ping()`](#connectionping)
+        - 4.2.8 [`queryStream()`](#querystream)
+        - 4.2.9 [`release()`](#release)
+        - 4.2.10 [`rollback()`](#rollback)
 5. [Lob Class](#lobclass)
     - 5.1 [Lob Properties](#lobproperties)
         - 5.1.1 [`chunkSize`](#proplobchunksize)
@@ -2405,7 +2406,51 @@ the number of rows affected, for example the number of rows
 inserted. For non-DML statements such as queries, or if no rows are
 affected, then `rowsAffected` will appear as undefined.
 
-#### <a name="querystream"></a> 4.2.7 `connection.queryStream()`
+#### <a name="connectionping"></a> 4.2.7 `connection.ping()`
+
+##### Prototype
+
+Callback:
+```
+ping(function(Error error){});
+```
+Promise:
+```
+promise = ping();
+```
+
+##### Description
+
+This method checks that a connection is currently usable and the
+network to the database is valid.  This call can be useful for system
+health checks.  A ping only confirms that a single connection is
+usable at the time of the ping.
+
+Pinging doesn't replace error checking during statement execution,
+since network or database failure may occur in the time between
+`ping()` and `execute()` calls.
+
+Pinging requires a 'round trip' to the database so unnecessary ping
+calls should be avoided.
+
+If `ping()` returns an error, the application should close the
+connection.
+
+This method was added in node-oracledb 2.2.
+
+##### Parameters
+
+```
+function(Error error)
+```
+
+The parameters of the callback function are:
+
+Callback function parameter | Description
+----------------------------|-------------
+*Error error* | If `ping()` succeeds, `error` is NULL.  If an error occurs, then `error` contains the [error message](#errorobj).
+
+#### <a name="querystream"></a> 4.2.8 `connection.queryStream()`
 
 ##### Prototype
 
@@ -2444,11 +2489,11 @@ This method was added in node-oracledb 1.8.
 
 See [execute()](#execute).
 
-#### <a name="release"></a> 4.2.8 `connection.release()`
+#### <a name="release"></a> 4.2.9 `connection.release()`
 
 An alias for [connection.close()](#connectionclose).
 
-#### <a name="rollback"></a> 4.2.9 `connection.rollback()`
+#### <a name="rollback"></a> 4.2.10 `connection.rollback()`
 
 ##### Prototype
 
@@ -3591,6 +3636,9 @@ allows a valid connection to be opened by some subsequent
 You can tune `poolPingInterval` to meet your quality of service
 requirements.
 
+Explicit pings on any connection can be performed at any time with
+[`connection.ping()`](#connectionping).
+
 ### <a name="drcp"></a> 8.4 Database Resident Connection Pooling (DRCP)
 
 [Database Resident Connection Pooling][24] (DRCP) enables database
@@ -3897,6 +3945,7 @@ application being aware of any service disruption.
 For a more information on FAN see the [whitepaper on Fast Application
 Notification][97].
 
+
 #### <a name="connectionrlb"></a> 8.9.2 Runtime Load Balancing (RLB)
 
 [Oracle Database RAC][93] users with [Oracle Database (RLB)][65]

lib/connection.js

@@ -29,6 +29,7 @@ var rollbackPromisified;
 var closePromisified;
 var breakPromisified;
 var changePasswordPromisified;
+var pingPromisified;
 
 // The queryStream function is similar to execute except that it immediately
 // returns a QueryStream.
@@ -265,6 +266,18 @@ function changePassword(user, password, newPassword, changePasswordCb) {
 
 changePasswordPromisified = nodbUtil.promisify(changePassword);
 
+// This ping function is just a place holder to allow for easier extension later.
+function ping(pingCb) {
+  var self = this;
+
+  nodbUtil.assert(arguments.length === 1, 'NJS-009');
+  nodbUtil.assert(typeof pingCb === 'function', 'NJS-006', 1);
+
+  self._ping.apply(self, arguments);
+}
+
+pingPromisified = nodbUtil.promisify(ping);
+
 // The extend method is used to extend the Connection instance from the C layer with
 // 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.
@@ -347,6 +360,14 @@ function extend(conn, oracledb, pool) {
         value: changePasswordPromisified,
         enumerable: true,
         writable: true
+      },
+      _ping: {
+        value: conn.ping
+      },
+      ping: {
+        value: pingPromisified,
+        enumerable: true,
+        writable: true
       }
     }
   );

src/njsConnection.cpp

@@ -86,6 +86,7 @@ void njsConnection::Init(Handle<Object> target)
     Nan::SetPrototypeMethod(tpl, "break", Break);
     Nan::SetPrototypeMethod(tpl, "createLob", CreateLob);
     Nan::SetPrototypeMethod(tpl, "changePassword", ChangePassword);
+    Nan::SetPrototypeMethod(tpl, "ping", Ping);
 
     Nan::SetAccessor(tpl->InstanceTemplate(),
             Nan::New<v8::String>("stmtCacheSize").ToLocalChecked(),
@@ -1764,6 +1765,41 @@ void njsConnection::Async_ChangePassword(njsBaton *baton)
 }
 
 
+//-----------------------------------------------------------------------------
+// njsConnection::Ping()
+//   Ping the database to see if it is "alive".
+//
+// PARAMETERS
+//   - JS callback which will receive (error)
+//-----------------------------------------------------------------------------
+NAN_METHOD(njsConnection::Ping)
+{
+    njsConnection *connection;
+    njsBaton *baton;
+
+    connection = (njsConnection*) ValidateArgs(info, 1, 1);
+    if (!connection)
+        return;
+    baton = connection->CreateBaton(info);
+    if (!baton)
+        return;
+    if (baton->error.empty())
+        baton->SetDPIConnHandle(connection->dpiConnHandle);
+    baton->QueueWork("Ping", Async_Ping, NULL, 1);
+}
+
+
+//-----------------------------------------------------------------------------
+// njsConnection::Async_Ping()
+//   Worker function for njsConnection::Ping() method.
+//-----------------------------------------------------------------------------
+void njsConnection::Async_Ping(njsBaton *baton)
+{
+    if (dpiConn_ping(baton->dpiConnHandle) < 0)
+        baton->GetDPIError();
+}
+
+
 //-----------------------------------------------------------------------------
 // njsConnection::GetStmtCacheSize()
 //   Get accessor of "stmtCacheSize" property.

src/njsConnection.h

@@ -124,6 +124,10 @@ class njsConnection: public njsCommon {
     static NAN_METHOD(ChangePassword);
     static void Async_ChangePassword(njsBaton *baton);
 
+    // Ping Method on Connection class
+    static NAN_METHOD(Ping);
+    static void Async_Ping(njsBaton *baton);
+
     // Define Getter Accessors to properties
     static NAN_GETTER(GetStmtCacheSize);
     static NAN_GETTER(GetClientId);