API doc AdapterStatusListener, GATTCharacteristicListener restriction: One instance can only be attached once.

To attach multiple instances, you need to create one instance per attachment.

2 files changed, 27 insertions, 2 deletions

diff --git a/java/org/tinyb/AdapterStatusListener.java b/java/org/tinyb/AdapterStatusListener.java
index 08d3a118..3101d0df 100644
--- a/java/org/tinyb/AdapterStatusListener.java
+++ b/java/org/tinyb/AdapterStatusListener.java
@@ -32,9 +32,21 @@ package org.tinyb;
  * A listener instance may be attached to a {@link BluetoothAdapter} via
  * {@link BluetoothAdapter#addStatusListener(BluetoothDeviceDiscoveryListener, BluetoothDevice)}.
  * </p>
+ * <p>
+ * You can only attach one {@link AdapterStatusListener} instance at a time,
+ * i.e. you cannot attach the same instance more than once to a {@link BluetoothAdapter}.
+ * <br>
+ * To attach multiple instances, you need to create one instance per attachment.
+ * <br>
+ * This restriction is due to implementation semantics of strictly associating
+ * one Java {@link AdapterStatusListener} instance to one C++ {@code AdapterStatusListener} instance.
+ * 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.
+ * </p>
  */
 public abstract class AdapterStatusListener {
-    long nativeInstance;
+    @SuppressWarnings("unused")
+    private long nativeInstance;
 
     /** A {@link BluetoothAdapter} setting has been changed. */
     public void adapterSettingsChanged(final BluetoothAdapter adapter,
diff --git a/java/org/tinyb/GATTCharacteristicListener.java b/java/org/tinyb/GATTCharacteristicListener.java
index 8641ca50..0c2cae1a 100644
--- a/java/org/tinyb/GATTCharacteristicListener.java
+++ b/java/org/tinyb/GATTCharacteristicListener.java
@@ -36,9 +36,22 @@ package org.tinyb;
  * {@link BluetoothDevice#addCharacteristicListener(GATTCharacteristicListener, BluetoothGattCharacteristic)}
  * to listen to all events of the device or the matching filtered events.
  * </p>
+ * <p>
+ * You can only attach one {@link GATTCharacteristicListener} instance at a time,
+ * i.e. you cannot attach the same instance more than once to a {@link BluetoothDevice}
+ * or {@link BluetoothGattCharacteristic}.
+ * <br>
+ * To attach multiple instances, you need to create one instance per attachment.
+ * <br>
+ * This restriction is due to implementation semantics of strictly associating
+ * one Java {@link GATTCharacteristicListener} instance to one C++ {@code GATTCharacteristicListener} instance.
+ * 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.
+ * </p>
  */
 public abstract class GATTCharacteristicListener {
-    long nativeInstance;
+    @SuppressWarnings("unused")
+    private long nativeInstance;
 
     public void notificationReceived(final BluetoothGattCharacteristic charDecl,
                                      final byte[] value, final long timestamp) {