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

1 files changed, 18 insertions, 29 deletions

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();