1. Added jetbrains-annoations dependency to clearly define interface methods

2. Added internet connectivity check to test setup

Author: sacOO7

android/build.gradle.kts

@@ -51,6 +51,7 @@ android {
 dependencies {
     api(libs.gson)
     implementation(libs.bundles.common)
+    compileOnly(libs.jetbrains)
     testImplementation(libs.bundles.tests)
     implementation(project(":network-client-core"))
     runtimeOnly(project(":network-client-default"))

gradle/libs.versions.toml

@@ -22,6 +22,7 @@ test-retry = "1.6.0"
 kotlin = "2.1.10"
 coroutine = "1.9.0"
 turbine = "1.2.0"
+jetbrains-annoations = "26.0.2"
 
 [libraries]
 gson = { group = "com.google.code.gson", name = "gson", version.ref = "gson" }
@@ -47,6 +48,7 @@ okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhtt
 coroutine-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "coroutine" }
 coroutine-test = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-test", version.ref = "coroutine" }
 turbine = { group = "app.cash.turbine", name = "turbine", version.ref = "turbine" }
+jetbrains = { group = "org.jetbrains", name = "annotations", version.ref = "jetbrains-annoations" }
 
 [bundles]
 common = ["msgpack", "vcdiff-core"]

java/build.gradle.kts

@@ -20,6 +20,7 @@ tasks.withType<Jar> {
 dependencies {
     api(libs.gson)
     implementation(libs.bundles.common)
+    compileOnly(libs.jetbrains)
     implementation(project(":network-client-core"))
     if (findProperty("okhttp") == null) {
         runtimeOnly(project(":network-client-default"))

lib/src/main/java/io/ably/lib/objects/LiveCounter.java

@@ -1,6 +1,8 @@
 package io.ably.lib.objects;
 
 import io.ably.lib.types.Callback;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Contract;
 
 /**
  * The LiveCounter interface provides methods to interact with a live counter.
@@ -19,7 +21,7 @@ public interface LiveCounter {
      *
      * @param callback the callback to be invoked upon completion of the operation.
      */
-    void incrementAsync(Callback<Void> callback);
+    void incrementAsync(@NotNull Callback<Void> callback);
 
     /**
      * Decrements the value of the counter by 1.
@@ -31,12 +33,14 @@ public interface LiveCounter {
      *
      * @param callback the callback to be invoked upon completion of the operation.
      */
-    void decrementAsync(Callback<Void> callback);
+    void decrementAsync(@NotNull Callback<Void> callback);
 
     /**
      * Retrieves the current value of the counter.
      *
      * @return the current value of the counter as a Long.
      */
+    @NotNull
+    @Contract(pure = true) // Indicates this method does not modify the state of the object.
     Long value();
 }

lib/src/main/java/io/ably/lib/objects/LiveMap.java

@@ -1,6 +1,10 @@
 package io.ably.lib.objects;
 
 import io.ably.lib.types.Callback;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.Map;
 
@@ -16,27 +20,34 @@ public interface LiveMap {
      * @param keyName the key whose associated value is to be returned.
      * @return the value associated with the specified key, or null if the key does not exist.
      */
-    Object get(String keyName);
+    @Nullable
+    Object get(@NotNull String keyName);
 
     /**
      * Retrieves all entries (key-value pairs) in the map.
      *
      * @return an iterable collection of all entries in the map.
      */
+    @NotNull
+    @Unmodifiable
     Iterable<Map.Entry<String, Object>> entries();
 
     /**
      * Retrieves all keys in the map.
      *
      * @return an iterable collection of all keys in the map.
      */
+    @NotNull
+    @Unmodifiable
     Iterable<String> keys();
 
     /**
      * Retrieves all values in the map.
      *
      * @return an iterable collection of all values in the map.
      */
+    @NotNull
+    @Unmodifiable
     Iterable<Object> values();
 
     /**
@@ -45,21 +56,22 @@ public interface LiveMap {
      * @param keyName the key to be set.
      * @param value the value to be associated with the key.
      */
-    void set(String keyName, Object value);
+    void set(@NotNull String keyName, @NotNull Object value);
 
     /**
      * Removes the specified key and its associated value from the map.
      *
      * @param keyName the key to be removed.
-     * @param value the value associated with the key to be removed.
      */
-    void remove(String keyName, Object value);
+    void remove(@NotNull String keyName);
 
     /**
      * Retrieves the number of entries in the map.
      *
      * @return the size of the map.
      */
+    @Contract(pure = true) // Indicates this method does not modify the state of the object.
+    @NotNull
     Long size();
 
     /**
@@ -69,14 +81,13 @@ public interface LiveMap {
      * @param value the value to be associated with the key.
      * @param callback the callback to handle the result or any errors.
      */
-    void setAsync(String keyName, Object value, Callback<Void> callback);
+    void setAsync(@NotNull String keyName, @NotNull Object value, @NotNull Callback<Void> callback);
 
     /**
      * Asynchronously removes the specified key and its associated value from the map.
      *
-     * @param keyName the key to be removed.
-     * @param value the value associated with the key to be removed.
+     * @param keyName  the key to be removed.
      * @param callback the callback to handle the result or any errors.
      */
-    void removeAsync(String keyName, Object value, Callback<Void> callback);
+    void removeAsync(@NotNull String keyName, @NotNull Callback<Void> callback);
 }

lib/src/main/java/io/ably/lib/objects/LiveObjects.java

@@ -2,13 +2,18 @@
 
 import io.ably.lib.objects.batch.BatchContextBuilder;
 import io.ably.lib.types.Callback;
+import org.jetbrains.annotations.NotNull;
+
 
 import java.util.Map;
 
 /**
  * The LiveObjects interface provides methods to interact with live data objects,
  * such as maps and counters, in a real-time environment. It supports both synchronous
  * and asynchronous operations for retrieving and creating live objects.
+ *
+ * <p>Implementations of this interface must be thread-safe as they may be accessed
+ * from multiple threads concurrently.
  */
 public interface LiveObjects {
 
@@ -17,91 +22,96 @@ public interface LiveObjects {
      *
      * @return the root LiveMap instance.
      */
+    @NotNull
     LiveMap getRoot();
 
     /**
      * Initiates a batch operation and provides a BatchContext through a callback.
      *
-     * @param batchContextCallback the callback to handle the BatchContext or error.
+     * @param batchContextCallback the builder to configure the batch operation.
      */
-    void batch(BatchContextBuilder batchContextCallback);
+    void batch(@NotNull BatchContextBuilder batchContextCallback);
 
     /**
      * Creates a new LiveMap based on an existing LiveMap.
      *
      * @param liveMap the existing LiveMap to base the new LiveMap on.
      * @return the newly created LiveMap instance.
      */
-    LiveMap createMap(LiveMap liveMap);
+    @NotNull
+    LiveMap createMap(@NotNull LiveMap liveMap);
 
     /**
      * Creates a new LiveMap based on a LiveCounter.
      *
      * @param liveCounter the LiveCounter to base the new LiveMap on.
      * @return the newly created LiveMap instance.
      */
-    LiveMap createMap(LiveCounter liveCounter);
+    @NotNull
+    LiveMap createMap(@NotNull LiveCounter liveCounter);
 
     /**
      * Creates a new LiveMap based on a standard Java Map.
      *
      * @param map the Java Map to base the new LiveMap on.
      * @return the newly created LiveMap instance.
      */
-    LiveMap createMap(Map<String, Object> map);
+    @NotNull
+    LiveMap createMap(@NotNull Map<String, Object> map);
 
     /**
      * Creates a new LiveCounter with an initial value.
      *
      * @param initialValue the initial value of the LiveCounter.
      * @return the newly created LiveCounter instance.
      */
-    LiveCounter createCounter(Long initialValue);
+    @NotNull
+    LiveCounter createCounter(@NotNull Long initialValue);
 
     /**
      * Asynchronously retrieves the root LiveMap object.
      *
      * @param callback the callback to handle the result or error.
      */
-    void getRootAsync(Callback<LiveMap> callback);
+    void getRootAsync(@NotNull Callback<@NotNull LiveMap> callback);
 
     /**
      * Initiates a batch operation asynchronously.
      *
-     * @param batchContextCallback the BatchContextBuilder to build the BatchContext.
+     * @param batchContextCallback the builder to configure the batch operation.
      * @param callback the Callback to handle the completion or error of the batch operation.
      */
-    void batchAsync(BatchContextBuilder batchContextCallback, Callback<Void> callback);
+    void batchAsync(@NotNull BatchContextBuilder batchContextCallback, @NotNull Callback<Void> callback);
 
     /**
      * Asynchronously creates a new LiveMap based on an existing LiveMap.
      *
      * @param liveMap the existing LiveMap to base the new LiveMap on.
      * @param callback the callback to handle the result or error.
      */
-    void createMapAsync(LiveMap liveMap, Callback<LiveMap> callback);
+    void createMapAsync(@NotNull LiveMap liveMap, @NotNull Callback<@NotNull LiveMap> callback);
 
     /**
      * Asynchronously creates a new LiveMap based on a LiveCounter.
      *
      * @param liveCounter the LiveCounter to base the new LiveMap on.
      * @param callback the callback to handle the result or error.
      */
-    void createMapAsync(LiveCounter liveCounter, Callback<LiveMap> callback);
+    void createMapAsync(@NotNull LiveCounter liveCounter, @NotNull Callback<@NotNull LiveMap> callback);
 
     /**
      * Asynchronously creates a new LiveMap based on a standard Java Map.
      *
      * @param map the Java Map to base the new LiveMap on.
      * @param callback the callback to handle the result or error.
      */
-    void createMapAsync(Map<String, Object> map, Callback<LiveMap> callback);
+    void createMapAsync(@NotNull Map<String, Object> map, @NotNull Callback<@NotNull LiveMap> callback);
 
     /**
      * Asynchronously creates a new LiveCounter with an initial value.
      *
      * @param initialValue the initial value of the LiveCounter.
      * @param callback the callback to handle the result or error.
      */
-    void createCounterAsync(Long initialValue, Callback<LiveCounter> callback);
+    void createCounterAsync(@NotNull Long initialValue, @NotNull Callback<@NotNull LiveCounter> callback);
 }

lib/src/main/java/io/ably/lib/objects/LiveObjectsPlugin.java

@@ -1,5 +1,7 @@
 package io.ably.lib.objects;
 
+import org.jetbrains.annotations.NotNull;
+
 /**
  * The LiveObjectsPlugin interface provides a mechanism to retrieve instances of LiveObjects
  * associated with specific channel names. This allows for interaction with live data objects
@@ -13,13 +15,12 @@ public interface LiveObjectsPlugin {
      * @param channelName the name of the channel for which the LiveObjects instance is to be retrieved.
      * @return the LiveObjects instance associated with the specified channel name.
      */
-    LiveObjects getInstance(String channelName);
-
+    LiveObjects getInstance(@NotNull String channelName);
 
     /**
      * Disposes of the LiveObjects instance associated with the specified channel name.
      *
      * @param channelName the name of the channel whose LiveObjects instance is to be removed.
      */
-    void dispose(String channelName);
+    void dispose(@NotNull String channelName);
 }

lib/src/main/java/io/ably/lib/objects/batch/BatchContext.java

@@ -1,5 +1,6 @@
 package io.ably.lib.objects.batch;
 
+import org.jetbrains.annotations.NotNull;
 
 /**
  * The BatchContext interface represents the context for batch operations
@@ -13,5 +14,6 @@ public interface BatchContext {
      *
      * @return the root LiveMap instance.
      */
+    @NotNull
     BatchContextLiveMap getRoot();
 }

lib/src/main/java/io/ably/lib/objects/batch/BatchContextBuilder.java

@@ -1,7 +1,9 @@
 package io.ably.lib.objects.batch;
 
+import org.jetbrains.annotations.NotNull;
+
 /**
- * A functional interface for building and handling a BatchContext.*
+ * A functional interface for building and handling a BatchContext.
  */
 @FunctionalInterface
 public interface BatchContextBuilder {
@@ -10,5 +12,5 @@ public interface BatchContextBuilder {
      *
      * @param batchContext the BatchContext to handle.
      */
-    void build(BatchContext batchContext);
+    void build(@NotNull BatchContext batchContext);
 }