Reworking GATTCharacteristicListener (C++ and Java)

- Aligned all related C++ and Java API doc entries and made sure it matches implementation.

- Renaming SpecificGATTCharacteristicListener to AssociatedGATTCharacteristicListener,
  as we refer to the associate GATTCharacteristic of a GATTCharacteristicListener

  AssociatedGATTCharacteristicListener is a specialization knowing its
  associated GATTCharacteristic to be used for match().

- Renamed 'configIndicationNotification(..)' to 'configNotificationIndication(..)',
  matching order of arguments and the returned enabledState array.

- Exposed 'configNotificationIndication(..)' incl enabledState array to Java

- Clarified the 'add listener' and 'configNotificationIndication(..)' semantic in API doc
  and implementation. Added new API entries to distinguish them.

- DBTGattCharacteristic.java skips adding its 'TinyB API compatibility' GATTCharacteristicListener
  in case neither notify nor indicate property exist.
  Also skip the native configNotificationIndication(..) in such case.
  This reduces the overall listener load to GattHandler by factor 5!

- General: Add new method 'removeAllAssociatedCharacteristicListener(GATTCharacteristic)',
  allowing removal of all GATTCharacteristic associated listener.
  This is usefull to complete the GATTCharacteristic C++ dtor or Java close() operation.

- DBTDevice: Add GATTCharacteristicListener methods to align with Java API
  and allow user not to deal with GATTHandler directly.
  Convenience and validates the C++/Java API alignement.

- C++ JNICriticalArray: Added 2nd template typename for the java-array-type,
  enabling it for other than jbyteArray. Here used for a jbooleanArray.

- The GATTCharacteristicListener Java to C++ native holding specialization JNICharacteristicListener
  keeps a new global reference to the Java GATTCharacteristicListener
  and the optional associated GATTCharacteristic.
  This ensures the instances won't get garbage collected and hence ensures proper
  object lifecycle even when passing 'throw away' listener object created just
  for the add*Listener call.

- Removal and hence destruction of the listeners is always guaranteed at:
-- Device / GATTHandler disconnect
-- GattCharacteristic dtor or close

6 files changed, 62 insertions, 75 deletions

diff --git a/examples/direct_bt_scanner00/dbt_scanner00.cpp b/examples/direct_bt_scanner00/dbt_scanner00.cpp
index 617b52b8..e08998c9 100644
--- a/examples/direct_bt_scanner00/dbt_scanner00.cpp
+++ b/examples/direct_bt_scanner00/dbt_scanner00.cpp
@@ -95,11 +95,11 @@ class MyAdapterStatusListener : public AdapterStatusListener {
 
 static const uuid16_t _TEMPERATURE_MEASUREMENT(GattCharacteristicType::TEMPERATURE_MEASUREMENT);
 
-class MyGATTEventListener : public SpecificGATTCharacteristicListener {
+class MyGATTEventListener : public AssociatedGATTCharacteristicListener {
   public:
 
     MyGATTEventListener(const GATTCharacteristic * characteristicMatch)
-    : SpecificGATTCharacteristicListener(characteristicMatch) {}
+    : AssociatedGATTCharacteristicListener(characteristicMatch) {}
 
     void notificationReceived(GATTCharacteristicRef charDecl, std::shared_ptr<TROOctets> charValue, const uint64_t timestamp) override {
         const std::shared_ptr<DBTDevice> dev = charDecl->getDevice();
@@ -278,7 +278,7 @@ int main(int argc, char *argv[])
                             }
                         }
                         bool cccdEnableResult[2];
-                        bool cccdRet = serviceChar.configIndicationNotification(true /* enableNotification */, true /* enableIndication */, cccdEnableResult);
+                        bool cccdRet = serviceChar.configNotificationIndication(true /* enableNotification */, true /* enableIndication */, cccdEnableResult);
                         fprintf(stderr, "  [%2.2d.%2.2d] Config Notification(%d), Indication(%d): Result %d\n",
                                 (int)i, (int)j, cccdEnableResult[0], cccdEnableResult[1], cccdRet);
                         if( cccdRet ) {
diff --git a/examples/direct_bt_scanner01/dbt_scanner01.cpp b/examples/direct_bt_scanner01/dbt_scanner01.cpp
index 10eca512..2fead468 100644
--- a/examples/direct_bt_scanner01/dbt_scanner01.cpp
+++ b/examples/direct_bt_scanner01/dbt_scanner01.cpp
@@ -290,7 +290,7 @@ int main(int argc, char *argv[])
                             const bool enableNotification = serviceChar.hasProperties(GATTCharacteristic::PropertyBitVal::Notify);
                             const bool enableIndication = serviceChar.hasProperties(GATTCharacteristic::PropertyBitVal::Indicate);
                             if( enableNotification || enableIndication ) {
-                                bool res = gatt->configIndicationNotification(*cccd, enableNotification, enableIndication);
+                                bool res = gatt->configNotificationIndication(*cccd, enableNotification, enableIndication);
                                 fprintf(stderr, "  [%2.2d.%2.2d] Config Notification(%d), Indication(%d): Result %d\n",
                                         (int)i, (int)j, enableNotification, enableIndication, res);
                             }
diff --git a/examples/direct_bt_scanner10/dbt_scanner10.cpp b/examples/direct_bt_scanner10/dbt_scanner10.cpp
index bde839d8..4a4e7bd8 100644
--- a/examples/direct_bt_scanner10/dbt_scanner10.cpp
+++ b/examples/direct_bt_scanner10/dbt_scanner10.cpp
@@ -193,11 +193,11 @@ class MyAdapterStatusListener : public AdapterStatusListener {
 
 static const uuid16_t _TEMPERATURE_MEASUREMENT(GattCharacteristicType::TEMPERATURE_MEASUREMENT);
 
-class MyGATTEventListener : public SpecificGATTCharacteristicListener {
+class MyGATTEventListener : public AssociatedGATTCharacteristicListener {
   public:
 
     MyGATTEventListener(const GATTCharacteristic * characteristicMatch)
-    : SpecificGATTCharacteristicListener(characteristicMatch) {}
+    : AssociatedGATTCharacteristicListener(characteristicMatch) {}
 
     void notificationReceived(GATTCharacteristicRef charDecl, std::shared_ptr<TROOctets> charValue, const uint64_t timestamp) override {
         const std::shared_ptr<DBTDevice> dev = charDecl->getDevice();
@@ -306,12 +306,10 @@ static void processConnectedDevice(std::shared_ptr<DBTDevice> device) {
                     }
                 }
                 bool cccdEnableResult[2];
-                bool cccdRet = serviceChar.configIndicationNotification(true /* enableNotification */, true /* enableIndication */, cccdEnableResult);
-                fprintf(stderr, "  [%2.2d.%2.2d] Config Notification(%d), Indication(%d): Result %d\n",
+                bool cccdRet = serviceChar.addCharacteristicListener( std::shared_ptr<GATTCharacteristicListener>( new MyGATTEventListener(&serviceChar) ),
+                                                                      cccdEnableResult );
+                fprintf(stderr, "  [%2.2d.%2.2d] addCharacteristicListener Notification(%d), Indication(%d): Result %d\n",
                         (int)i, (int)j, cccdEnableResult[0], cccdEnableResult[1], cccdRet);
-                if( cccdRet ) {
-                    serviceChar.addCharacteristicListener( std::shared_ptr<GATTCharacteristicListener>( new MyGATTEventListener(&serviceChar) ) );
-                }
             }
         }
         // FIXME sleep 1s for potential callbacks ..
diff --git a/examples/java/ScannerTinyB01.java b/examples/java/ScannerTinyB01.java
index c2f7a739..d6385167 100644
--- a/examples/java/ScannerTinyB01.java
+++ b/examples/java/ScannerTinyB01.java
@@ -203,22 +203,6 @@ public class ScannerTinyB01 {
 
         adapter.enablePoweredNotifications(new BooleanNotification("Powered", timestamp_t0));
 
-        final GATTCharacteristicListener myCharacteristicListener = new GATTCharacteristicListener() {
-            @Override
-            public void notificationReceived(final BluetoothGattCharacteristic charDecl,
-                                             final byte[] value, final long timestamp) {
-                System.err.println("****** GATT notificationReceived: "+charDecl+
-                                   ", value "+BluetoothUtils.bytesHexString(value, true, true));
-            }
-
-            @Override
-            public void indicationReceived(final BluetoothGattCharacteristic charDecl,
-                                           final byte[] value, final long timestamp, final boolean confirmationSent) {
-                System.err.println("****** GATT indicationReceived: "+charDecl+
-                                   ", value "+BluetoothUtils.bytesHexString(value, true, true));
-            }
-        };
-
         int loop = 0;
         try {
             while( forever || loop < max_loops ) {
@@ -339,13 +323,23 @@ public class ScannerTinyB01 {
                         }
                     }
 
-                    final boolean addedCharacteristicListenerRes;
-                    if( isDirectBT ) {
-                        addedCharacteristicListenerRes =
-                                BluetoothGattService.addCharacteristicListenerToAll(sensor, primServices, myCharacteristicListener);
-                    } else {
-                        addedCharacteristicListenerRes = false;
-                    }
+                    final GATTCharacteristicListener myCharacteristicListener = new GATTCharacteristicListener(null) {
+                        @Override
+                        public void notificationReceived(final BluetoothGattCharacteristic charDecl,
+                                final byte[] value, final long timestamp) {
+                            System.err.println("****** GATT notificationReceived: "+charDecl+
+                                    ", value "+BluetoothUtils.bytesHexString(value, true, true));
+                        }
+
+                        @Override
+                        public void indicationReceived(final BluetoothGattCharacteristic charDecl,
+                                final byte[] value, final long timestamp, final boolean confirmationSent) {
+                            System.err.println("****** GATT indicationReceived: "+charDecl+
+                                    ", value "+BluetoothUtils.bytesHexString(value, true, true));
+                        }
+                    };
+                    final boolean addedCharacteristicListenerRes =
+                            BluetoothGattService.addCharacteristicListenerToAll(sensor, primServices, myCharacteristicListener);
                     System.err.println("Added GATTCharacteristicListener: "+addedCharacteristicListenerRes);
 
                     int i=0, j=0;
@@ -373,12 +367,7 @@ public class ScannerTinyB01 {
                     }
                     Thread.sleep(1000); // FIXME: Wait for notifications
 
-                    final boolean remRes;
-                    if( isDirectBT ) {
-                        remRes = BluetoothGattService.removeCharacteristicListenerFromAll(sensor, primServices, myCharacteristicListener);
-                    } else {
-                        remRes = false;
-                    }
+                    final boolean remRes = BluetoothGattService.removeCharacteristicListenerFromAll(sensor, primServices, myCharacteristicListener);
                     System.err.println("Removed GATTCharacteristicListener: "+remRes);
                 }
                 sensor.disconnect();
diff --git a/examples/java/ScannerTinyB02.java b/examples/java/ScannerTinyB02.java
index 678e88a0..d02ba9e7 100644
--- a/examples/java/ScannerTinyB02.java
+++ b/examples/java/ScannerTinyB02.java
@@ -193,22 +193,6 @@ public class ScannerTinyB02 {
 
         adapter.enablePoweredNotifications(new BooleanNotification("Powered", timestamp_t0));
 
-        final GATTCharacteristicListener myCharacteristicListener = new GATTCharacteristicListener() {
-            @Override
-            public void notificationReceived(final BluetoothGattCharacteristic charDecl,
-                                             final byte[] value, final long timestamp) {
-                System.err.println("****** GATT notificationReceived: "+charDecl+
-                                   ", value "+BluetoothUtils.bytesHexString(value, true, true));
-            }
-
-            @Override
-            public void indicationReceived(final BluetoothGattCharacteristic charDecl,
-                                           final byte[] value, final long timestamp, final boolean confirmationSent) {
-                System.err.println("****** GATT indicationReceived: "+charDecl+
-                                   ", value "+BluetoothUtils.bytesHexString(value, true, true));
-            }
-        };
-
         int loop = 0;
         try {
             while( forever || loop < max_loops ) {
@@ -346,6 +330,21 @@ public class ScannerTinyB02 {
                 if ( null == primServices || primServices.isEmpty() ) {
                     System.err.println("No BluetoothGattService found!");
                 } else {
+                    final GATTCharacteristicListener myCharacteristicListener = new GATTCharacteristicListener(null) {
+                        @Override
+                        public void notificationReceived(final BluetoothGattCharacteristic charDecl,
+                                                         final byte[] value, final long timestamp) {
+                            System.err.println("****** GATT notificationReceived: "+charDecl+
+                                               ", value "+BluetoothUtils.bytesHexString(value, true, true));
+                        }
+
+                        @Override
+                        public void indicationReceived(final BluetoothGattCharacteristic charDecl,
+                                                       final byte[] value, final long timestamp, final boolean confirmationSent) {
+                            System.err.println("****** GATT indicationReceived: "+charDecl+
+                                               ", value "+BluetoothUtils.bytesHexString(value, true, true));
+                        }
+                    };
                     final boolean addedCharacteristicListenerRes =
                       BluetoothGattService.addCharacteristicListenerToAll(sensor, primServices, myCharacteristicListener);
                     System.err.println("Added GATTCharacteristicListener: "+addedCharacteristicListenerRes);
diff --git a/examples/java/ScannerTinyB10.java b/examples/java/ScannerTinyB10.java
index 959bba5b..78235138 100644
--- a/examples/java/ScannerTinyB10.java
+++ b/examples/java/ScannerTinyB10.java
@@ -164,22 +164,6 @@ public class ScannerTinyB10 {
         }
     };
 
-    final GATTCharacteristicListener myCharacteristicListener = new GATTCharacteristicListener() {
-        @Override
-        public void notificationReceived(final BluetoothGattCharacteristic charDecl,
-                                         final byte[] value, final long timestamp) {
-            System.err.println("****** GATT notificationReceived: "+charDecl+
-                               ", value "+BluetoothUtils.bytesHexString(value, true, true));
-        }
-
-        @Override
-        public void indicationReceived(final BluetoothGattCharacteristic charDecl,
-                                       final byte[] value, final long timestamp, final boolean confirmationSent) {
-            System.err.println("****** GATT indicationReceived: "+charDecl+
-                               ", value "+BluetoothUtils.bytesHexString(value, true, true));
-        }
-    };
-
     private void connectDiscoveredDevice(final BluetoothDevice device) {
         System.err.println("****** Connecting Device: Start " + device.toString());
         device.getAdapter().stopDiscovery();
@@ -237,9 +221,26 @@ public class ScannerTinyB10 {
                     System.err.println("  over device : "+char2);
                 }
             }
-            final boolean addedCharacteristicListenerRes =
-              BluetoothGattService.addCharacteristicListenerToAll(device, primServices, myCharacteristicListener);
-            System.err.println("Added GATTCharacteristicListener: "+addedCharacteristicListenerRes);
+            {
+                final GATTCharacteristicListener myCharacteristicListener = new GATTCharacteristicListener(null) {
+                    @Override
+                    public void notificationReceived(final BluetoothGattCharacteristic charDecl,
+                                                     final byte[] value, final long timestamp) {
+                        System.err.println("****** GATT notificationReceived: "+charDecl+
+                                           ", value "+BluetoothUtils.bytesHexString(value, true, true));
+                    }
+
+                    @Override
+                    public void indicationReceived(final BluetoothGattCharacteristic charDecl,
+                                                   final byte[] value, final long timestamp, final boolean confirmationSent) {
+                        System.err.println("****** GATT indicationReceived: "+charDecl+
+                                           ", value "+BluetoothUtils.bytesHexString(value, true, true));
+                    }
+                };
+                final boolean addedCharacteristicListenerRes =
+                  BluetoothGattService.addCharacteristicListenerToAll(device, primServices, myCharacteristicListener);
+                System.err.println("Added GATTCharacteristicListener: "+addedCharacteristicListenerRes);
+            }
 
             int i=0, j=0;
             for(final Iterator<BluetoothGattService> srvIter = primServices.iterator(); srvIter.hasNext(); i++) {