1. Updated public doc for LiveObjects, LiveMap and LiveCounter

2. Added live objects specific channel modes and flags to protocol message

Author: sacOO7

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

@@ -13,23 +13,33 @@ public interface LiveCounter {
 
     /**
      * Increments the value of the counter by 1.
+     * Send a COUNTER_INC operation to the realtime system to increment a value on this LiveCounter object.
+     * This does not modify the underlying data of this LiveCounter object. Instead, the change will be applied when
+     * the published COUNTER_INC operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
      */
     void increment();
 
     /**
      * Increments the value of the counter by 1 asynchronously.
+     * Send a COUNTER_INC operation to the realtime system to increment a value on this LiveCounter object.
+     * This does not modify the underlying data of this LiveCounter object. Instead, the change will be applied when
+     * the published COUNTER_INC operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
      *
      * @param callback the callback to be invoked upon completion of the operation.
      */
     void incrementAsync(@NotNull Callback<Void> callback);
 
     /**
      * Decrements the value of the counter by 1.
+     * An alias for calling {@link LiveCounter#increment()} with a negative amount.
      */
     void decrement();
 
     /**
      * Decrements the value of the counter by 1 asynchronously.
+     * An alias for calling {@link LiveCounter#increment()} with a negative amount.
      *
      * @param callback the callback to be invoked upon completion of the operation.
      */

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

@@ -16,6 +16,12 @@ public interface LiveMap {
 
     /**
      * Retrieves the value associated with the specified key.
+     * If this map object is tombstoned (deleted), `undefined` is returned.
+     * If no entry is associated with the specified key, `undefined` is returned.
+     * If map entry is tombstoned (deleted), `undefined` is returned.
+     * If the value associated with the provided key is an objectId string of another LiveObject, a reference to that LiveObject
+     * is returned, provided it exists in the local pool and is not tombstoned. Otherwise, `undefined` is returned.
+     * If the value is not an objectId, then that value is returned.
      *
      * @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.
@@ -52,6 +58,10 @@ public interface LiveMap {
 
     /**
      * Sets the specified key to the given value in the map.
+     * Send a MAP_SET operation to the realtime system to set a key on this LiveMap object to a specified value.
+     * This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when
+     * the published MAP_SET operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
      *
      * @param keyName the key to be set.
      * @param value the value to be associated with the key.
@@ -60,6 +70,10 @@ public interface LiveMap {
 
     /**
      * Removes the specified key and its associated value from the map.
+     * Send a MAP_REMOVE operation to the realtime system to tombstone a key on this LiveMap object.
+     * This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when
+     * the published MAP_REMOVE operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
      *
      * @param keyName the key to be removed.
      */
@@ -76,6 +90,10 @@ public interface LiveMap {
 
     /**
      * Asynchronously sets the specified key to the given value in the map.
+     * Send a MAP_SET operation to the realtime system to set a key on this LiveMap object to a specified value.
+     * This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when
+     * the published MAP_SET operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
      *
      * @param keyName the key to be set.
      * @param value the value to be associated with the key.
@@ -85,6 +103,10 @@ public interface LiveMap {
 
     /**
      * Asynchronously removes the specified key and its associated value from the map.
+     * Send a MAP_REMOVE operation to the realtime system to tombstone a key on this LiveMap object.
+     * This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when
+     * the published MAP_REMOVE operation is echoed back to the client and applied to the object following the regular
+     * operation application procedure.
      *
      * @param keyName  the key to be removed.
      * @param callback the callback to handle the result or any errors.

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

@@ -19,6 +19,9 @@ public interface LiveObjects {
 
     /**
      * Retrieves the root LiveMap object.
+     * When called without a type variable, we return a default root type which is based on globally defined interface for Objects feature.
+     * A user can provide an explicit type for the getRoot method to explicitly set the type structure on this particular channel.
+     * This is useful when working with multiple channels with different underlying data structure.
      *
      * @return the root LiveMap instance.
      */
@@ -27,13 +30,19 @@ public interface LiveObjects {
 
     /**
      * Initiates a batch operation and provides a BatchContext through a callback.
+     * Provides access to the synchronous write API for Objects that can be used to batch multiple operations
+     * together in a single channel message.
      *
      * @param batchContextCallback the builder to configure the batch operation.
      */
     void batch(@NotNull BatchContextBuilder batchContextCallback);
 
     /**
      * Creates a new LiveMap based on an existing LiveMap.
+     * Send a MAP_CREATE operation to the realtime system to create a new map object in the pool.
+     * Once the ACK message is received, the method returns the object from the local pool if it got created due to
+     * the echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locally
+     * using the provided data and returns it.
      *
      * @param liveMap the existing LiveMap to base the new LiveMap on.
      * @return the newly created LiveMap instance.
@@ -43,6 +52,10 @@ public interface LiveObjects {
 
     /**
      * Creates a new LiveMap based on a LiveCounter.
+     * Send a MAP_CREATE operation to the realtime system to create a new map object in the pool.
+     * Once the ACK message is received, the method returns the object from the local pool if it got created due to
+     * the echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locally
+     * using the provided data and returns it.
      *
      * @param liveCounter the LiveCounter to base the new LiveMap on.
      * @return the newly created LiveMap instance.
@@ -52,6 +65,10 @@ public interface LiveObjects {
 
     /**
      * Creates a new LiveMap based on a standard Java Map.
+     * Send a MAP_CREATE operation to the realtime system to create a new map object in the pool.
+     * Once the ACK message is received, the method returns the object from the local pool if it got created due to
+     * the echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locally
+     * using the provided data and returns it.
      *
      * @param map the Java Map to base the new LiveMap on.
      * @return the newly created LiveMap instance.
@@ -61,6 +78,10 @@ public interface LiveObjects {
 
     /**
      * Creates a new LiveCounter with an initial value.
+     * Send a COUNTER_CREATE operation to the realtime system to create a new counter object in the pool.
+     * Once the ACK message is received, the method returns the object from the local pool if it got created due to
+     * the echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locally
+     * using the provided data and returns it.
      *
      * @param initialValue the initial value of the LiveCounter.
      * @return the newly created LiveCounter instance.
@@ -70,13 +91,18 @@ public interface LiveObjects {
 
     /**
      * Asynchronously retrieves the root LiveMap object.
+     * When called without a type variable, we return a default root type which is based on globally defined interface for Objects feature.
+     * A user can provide an explicit type for the getRoot method to explicitly set the type structure on this particular channel.
+     * This is useful when working with multiple channels with different underlying data structure.
      *
      * @param callback the callback to handle the result or error.
      */
     void getRootAsync(@NotNull Callback<@NotNull LiveMap> callback);
 
     /**
      * Initiates a batch operation asynchronously.
+     * Provides access to the synchronous write API for Objects that can be used to batch multiple operations
+     * together in a single channel message.
      *
      * @param batchContextCallback the builder to configure the batch operation.
      * @param callback the Callback to handle the completion or error of the batch operation.
@@ -85,6 +111,10 @@ public interface LiveObjects {
 
     /**
      * Asynchronously creates a new LiveMap based on an existing LiveMap.
+     * Send a MAP_CREATE operation to the realtime system to create a new map object in the pool.
+     * Once the ACK message is received, the method returns the object from the local pool if it got created due to
+     * the echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locally
+     * using the provided data and returns it.
      *
      * @param liveMap the existing LiveMap to base the new LiveMap on.
      * @param callback the callback to handle the result or error.
@@ -93,6 +123,10 @@ public interface LiveObjects {
 
     /**
      * Asynchronously creates a new LiveMap based on a LiveCounter.
+     * Send a MAP_CREATE operation to the realtime system to create a new map object in the pool.
+     * Once the ACK message is received, the method returns the object from the local pool if it got created due to
+     * the echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locally
+     * using the provided data and returns it.
      *
      * @param liveCounter the LiveCounter to base the new LiveMap on.
      * @param callback the callback to handle the result or error.
@@ -101,6 +135,10 @@ public interface LiveObjects {
 
     /**
      * Asynchronously creates a new LiveMap based on a standard Java Map.
+     * Send a MAP_CREATE operation to the realtime system to create a new map object in the pool.
+     * Once the ACK message is received, the method returns the object from the local pool if it got created due to
+     * the echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locally
+     * using the provided data and returns it.
      *
      * @param map the Java Map to base the new LiveMap on.
      * @param callback the callback to handle the result or error.
@@ -109,6 +147,10 @@ public interface LiveObjects {
 
     /**
      * Asynchronously creates a new LiveCounter with an initial value.
+     * Send a COUNTER_CREATE operation to the realtime system to create a new counter object in the pool.
+     * Once the ACK message is received, the method returns the object from the local pool if it got created due to
+     * the echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locally
+     * using the provided data and returns it.
      *
      * @param initialValue the initial value of the LiveCounter.
      * @param callback the callback to handle the result or error.

lib/src/main/java/io/ably/lib/types/ChannelMode.java

@@ -24,7 +24,27 @@ public enum ChannelMode {
     /**
      * The client can receive presence messages.
      */
-    presence_subscribe(Flag.presence_subscribe);
+    presence_subscribe(Flag.presence_subscribe),
+
+    /**
+     * The client can publish object messages.
+     */
+    object_publish(Flag.object_publish),
+
+    /**
+     * The client can subscribe to object messages.
+     */
+    object_subscribe(Flag.object_subscribe),
+
+    /**
+     * The client can publish annotation messages.
+     */
+    annotation_publish(Flag.annotation_publish),
+
+    /**
+     * The client can subscribe to annotation messages.
+     */
+    annotation_subscribe(Flag.annotation_subscribe);
 
     private final int mask;
 

lib/src/main/java/io/ably/lib/types/ProtocolMessage.java

@@ -45,7 +45,11 @@ public enum Action {
         presence,
         message,
         sync,
-        auth;
+        auth,
+        activate,
+        object,
+        object_sync,
+        annotation;
 
         public int getValue() { return ordinal(); }
         public static Action findByValue(int value) { return values()[value]; }
@@ -57,12 +61,19 @@ public enum Flag {
         has_backlog(1),
         resumed(2),
         attach_resume(5),
-
+        /* Has object flag */
+        has_objects(7),
         /* Channel mode flags */
         presence(16),
         publish(17),
         subscribe(18),
-        presence_subscribe(19);
+        presence_subscribe(19),
+        /* Annotation flags */
+        annotation_publish(21),
+        annotation_subscribe(22),
+        /* Object flags */
+        object_subscribe(24),
+        object_publish(25);
 
         private final int mask;