API Change C++/Java: BTGattChar::addCharListener(..): Use naive BTGattChar::Listener and have implementation handle the BTGattChar association match for notificationsv2.2.13

Turns out previous API and code moved the burden to user to only have the calling BTGattChar object to be matched,
which is not only not intuitive, but also a potential source of issues.

Now we provide a naive interface BTGattChar::Listener to be passed
and BTGattChar::addCharListener(..) wraps its instance in a BTGattCharListener to be delegated.

BTGattChar::removeCharListener(..) has been removed due to high implementation
burden on the Java side. This shall not cause harm to the user, as it isn't useful in a user application.

BTGattChar::removeAllAssociatedCharListener(..) is available on the C++ and Java side,
i.e. fixed API in C++ where we had BTGattChar::removeAllCharListener(..).

Tested and demonstrated in dbt_scanner10.cpp and DBTScanner10.java, as usual.
Both examples also print the service, characteristic and declaration in a more readable fashion.

2 files changed, 72 insertions, 41 deletions

diff --git a/java/org/direct_bt/BTGattChar.java b/java/org/direct_bt/BTGattChar.java
index 5dfb2373..078fbd0f 100644
--- a/java/org/direct_bt/BTGattChar.java
+++ b/java/org/direct_bt/BTGattChar.java
@@ -38,6 +38,45 @@ import java.util.List;
   */
 public interface BTGattChar extends BTObject
 {
+    /**
+     * {@link BTGattChar} event listener for notification and indication events.
+     * <p>
+     * This listener instance is attached to a {@link BTGattChar} via
+     * {@link BTGattChar#addCharListener(Listener)} or {@link BTGattChar#addCharListener(Listener, boolean[])}
+     * to listen to events associated with the {@link BTGattChar} instance.
+     * </p>
+     * <p>
+     * The listener manager maintains a unique set of listener instances without duplicates.
+     * </p>
+     * <p>
+     * Implementation will utilize a {@link BTGattCharListener) for the listener manager,
+     * delegating matching {@link BTGattChar} events to this instance.
+     * </p>
+     */
+    static public interface Listener {
+        /**
+         * Called from native BLE stack, initiated by a received notification associated
+         * with the given {@link BTGattChar}.
+         * @param charDecl {@link BTGattChar} related to this notification
+         * @param value the notification value
+         * @param timestamp the indication monotonic timestamp, see {@link BTUtils#currentTimeMillis()}
+         */
+        public void notificationReceived(final BTGattChar charDecl,
+                                         final byte[] value, final long timestamp);
+
+        /**
+         * Called from native BLE stack, initiated by a received indication associated
+         * with the given {@link BTGattChar}.
+         * @param charDecl {@link BTGattChar} related to this indication
+         * @param value the indication value
+         * @param timestamp the indication monotonic timestamp, see {@link BTUtils#currentTimeMillis()}
+         * @param confirmationSent if true, the native stack has sent the confirmation, otherwise user is required to do so.
+         */
+        public void indicationReceived(final BTGattChar charDecl,
+                                       final byte[] value, final long timestamp,
+                                       final boolean confirmationSent);
+    };
+
     @Override
     public BTGattChar clone();
 
@@ -130,80 +169,69 @@ public interface BTGattChar extends BTObject
             throws IllegalStateException;
 
     /**
-     * Add the given {@link BTGattCharListener} to the listener list if not already present.
+     * Add the given {@link BTGattChar.Listener} to the listener list if not already present.
      * <p>
-     * Occurring notifications and indications, if enabled via {@link #configNotificationIndication(boolean, boolean, boolean[])}
+     * Occurring notifications and indications for this characteristic,
+     * if enabled via {@link #configNotificationIndication(boolean, boolean, boolean[])}
      * or {@link #enableNotificationOrIndication(boolean[])},
-     * will call the respective BTGattCharListener callback method.
+     * will call the respective {@link BTGattChar.Listener} callback method.
      * </p>
-     * @param listener A {@link BTGattCharListener} instance, listening to this {@link BTGattChar}'s events
+     * <p>
+     * Implementation wraps given {@link BTGattChar.Listener} into a {@link BTGattCharListener}
+     * to restrict the listener to listen only to this BTGattChar instance.
+     * </p>
+     * @param listener A {@link BTGattChar.Listener} instance, listening to this {@link BTGattChar}'s events
      * @return true if the given listener is not element of the list and has been newly added, otherwise false.
      * @throws IllegalStateException if the DBTDevice's GATTHandler is null, i.e. not connected
-     * @throws IllegalStateException if the given {@link BTGattCharListener} is already in use, i.e. added.
+     * @throws IllegalStateException if the given {@link BTGattChar.Listener} is already in use, i.e. added.
      * @see #enableNotificationOrIndication(boolean[])
      * @see #configNotificationIndication(boolean, boolean, boolean[])
+     * @see #addCharListener(Listener, boolean[])
+     * @see #removeCharListener(Listener, boolean)
+     * @see #removeAllAssociatedCharListener(boolean)
      * @since 2.0.0
      * @implNote not implemented in tinyb.dbus
      */
-    public boolean addCharListener(final BTGattCharListener listener)
+    public boolean addCharListener(final Listener listener)
             throws IllegalStateException;
 
     /**
-     * Add the given {@link BTGattCharListener} to the listener list if not already present
+     * Add the given {@link BTGattChar.Listener} to the listener list if not already present
      * and if enabling the notification <i>or</i> indication for this characteristic at BLE level was successful.<br>
      * Notification and/or indication configuration is only performed per characteristic if changed.
      * <p>
-     * Implementation will attempt to enable notification only, if available,
-     * otherwise indication if available. <br>
-     * Implementation uses {@link #enableNotificationOrIndication(boolean[])} to enable one.
+     * Implementation will enable notification if available,
+     * otherwise indication will be enabled if available. <br>
+     * Implementation uses {@link #enableNotificationOrIndication(boolean[])} to enable either.
      * </p>
      * <p>
-     * Occurring notifications and indications will call the respective {@link BTGattCharListener}
-     * callback method.
+     * Occurring notifications and indications for this characteristic
+     * will call the respective {@link BTGattChar.Listener} callback method.
      * </p>
-     * @param listener A {@link BTGattCharListener} instance, listening to this {@link BTGattChar}'s events
+     * @param listener A {@link BTGattChar.Listener} instance, listening to this {@link BTGattChar}'s events
      * @param enabledState array of size 2, holding the resulting enabled state for notification and indication
      * using {@link #enableNotificationOrIndication(boolean[])}
      * @return true if enabling the notification and/or indication was successful
      * and if the given listener is not element of the list and has been newly added, otherwise false.
      * @throws IllegalStateException if the {@link BTDevice}'s GATTHandler is null, i.e. not connected
-     * @throws IllegalStateException if the given {@link BTGattCharListener} is already in use, i.e. added.
+     * @throws IllegalStateException if the given {@link BTGattChar.Listener} is already in use, i.e. added.
      * @see #enableNotificationOrIndication(boolean[])
      * @see #configNotificationIndication(boolean, boolean, boolean[])
+     * @see #addCharListener(Listener)
+     * @see #removeCharListener(Listener, boolean)
+     * @see #removeAllAssociatedCharListener(boolean)
      * @since 2.0.0
      * @implNote not implemented in tinyb.dbus
      */
-    public boolean addCharListener(final BTGattCharListener listener, final boolean enabledState[/*2*/])
+    public boolean addCharListener(final Listener listener, final boolean enabledState[/*2*/])
             throws IllegalStateException;
 
     /**
-     * Disables the notification and/or indication for this characteristic at BLE level
-     * if {@code disableIndicationNotification == true}
-     * and removes the given {@link BTGattCharListener} from the listener list.
-     * <p>
-     * If the DBTDevice's GATTHandler is null, i.e. not connected, {@code false} is being returned.
-     * </p>
-     *
-     * @param listener A {@link BTGattCharListener} instance
-     * @param disableIndicationNotification if true, disables the notification and/or indication for this characteristic
-     * using {@link #configNotificationIndication(boolean, boolean, boolean[])}
-     * @return true if the given listener is an element of the list and has been removed, otherwise false.
-     * @see #configNotificationIndication(boolean, boolean, boolean[])
-     * @since 2.0.0
-     * @implNote not implemented in tinyb.dbus
-     */
-    public boolean removeCharListener(final BTGattCharListener l, final boolean disableIndicationNotification);
-
-    /**
      * Disables the notification and/or indication for this characteristic BLE level
      * if {@code disableIndicationNotification == true}
-     * and removes all {@link BTGattCharListener} from the listener list,
+     * and removes all associated {@link BTGattChar.Listener} or {@link BTGattCharListener} from the listener list,
      * which are associated with this characteristic instance.
      * <p>
-     * Implementation tests all listener's {@link BTGattCharListener#getAssociatedChar()}
-     * to match with this characteristic instance.
-     * </p>
-     * <p>
      * If the DBTDevice's GATTHandler is null, i.e. not connected, {@code false} is being returned.
      * </p>
      *
@@ -212,6 +240,9 @@ public interface BTGattChar extends BTObject
      * @return number of removed listener.
      * @see #configNotificationIndication(boolean, boolean, boolean[])
      * @see BTDevice#removeAllAssociatedCharListener(BTGattChar)
+     * @see #addCharListener(Listener)
+     * @see #addCharListener(Listener, boolean[])
+     * @see #removeCharListener(Listener, boolean)
      * @since 2.0.0
      * @implNote not implemented in tinyb.dbus
      */
diff --git a/java/org/direct_bt/BTGattCharListener.java b/java/org/direct_bt/BTGattCharListener.java
index d24a3d49..862ef4b0 100644
--- a/java/org/direct_bt/BTGattCharListener.java
+++ b/java/org/direct_bt/BTGattCharListener.java
@@ -31,7 +31,7 @@ import java.lang.ref.WeakReference;
  * {@link BTGattChar} event listener for notification and indication events.
  * <p>
  * A listener instance may be attached to a {@link BTGattChar} via
- * {@link BTGattChar#addCharListener(BTGattCharListener)} to listen to its events.
+ * {@link BTGattChar#addCharListener(org.direct_bt.BTGattChar.Listener)} to listen to its events.
  * </p>
  * <p>
  * A listener instance may be attached to a {@link BTDevice} via
@@ -39,7 +39,7 @@ import java.lang.ref.WeakReference;
  * to listen to all events of the device or the matching filtered events.
  * </p>
  * <p>
- * One {@link BTGattCharListener} instance can only be attached to a listener receiver once at a time,
+ * One {@link BTGattCharListener} instance can only be attached to a listener manager once at a time,
  * i.e. you cannot attach the same instance more than once to a {@link BTDevice}
  * or {@link BTGattChar}.
  * <br>
@@ -50,7 +50,7 @@ import java.lang.ref.WeakReference;
  * The latter will be added to the native list of listeners.
  * This class's {@code nativeInstance} field links the Java instance to mentioned C++ listener.
  * <br>
- * Since the listener receiver maintains a unique set of listener instances without duplicates,
+ * Since the listener manager maintains a unique set of listener instances without duplicates,
  * this restriction is more esoteric.
  * </p>
  */