Refactored/Updated public API types as per spec

Author: sacOO7

lib/src/main/java/io/ably/lib/object/Subscription.java

@@ -0,0 +1,30 @@
+package io.ably.lib.object;
+
+/**
+ * Represents a registration for receiving events from a subscribe operation.
+ * Provides a way to clean up and remove a subscription when it is no longer
+ * needed.
+ *
+ * <p>Example usage:
+ * <pre>
+ * {@code
+ * Subscription s = pathObject.subscribe(event -> { ... });
+ * // Later, when done with the subscription
+ * s.unsubscribe();
+ * }
+ * </pre>
+ *
+ * <p>Spec: SUB1
+ */
+public interface Subscription {
+
+    /**
+     * Deregisters the listener that was registered by the corresponding
+     * {@code subscribe} call. Once called, the listener will not be invoked for
+     * any subsequent events and references to it are cleaned up. Calling this
+     * method more than once is a no-op.
+     *
+     * <p>Spec: SUB2a, SUB2b
+     */
+    void unsubscribe();
+}

lib/src/main/java/io/ably/lib/object/ValueType.java

@@ -1,13 +1,28 @@
 package io.ably.lib.object;
 
+/**
+ * The type of a value resolved by a {@code PathObject} or wrapped by an
+ * {@code Instance} in the LiveObjects graph.
+ *
+ * <p>Spec: RTTS2
+ */
 public enum ValueType {
+    /** Corresponds to the {@code String} primitive. Spec: RTTS2a1 */
     STRING,
+    /** Corresponds to the {@code Number} primitive. Spec: RTTS2a2 */
     NUMBER,
+    /** Corresponds to the {@code Boolean} primitive. Spec: RTTS2a3 */
     BOOLEAN,
+    /** Corresponds to the {@code Binary} primitive. Spec: RTTS2a4 */
     BINARY,
+    /** Corresponds to the {@code JsonObject} primitive. Spec: RTTS2a5 */
     JSON_OBJECT,
+    /** Corresponds to the {@code JsonArray} primitive. Spec: RTTS2a6 */
     JSON_ARRAY,
+    /** Corresponds to a {@code LiveMap} object. Spec: RTTS2a7 */
     LIVE_MAP,
+    /** Corresponds to a {@code LiveCounter} object. Spec: RTTS2a8 */
     LIVE_COUNTER,
+    /** Returned when path resolution fails or the resolved value has none of the known types; never produced by an {@code Instance} in normal operation. Spec: RTTS2a9 */
     UNKNOWN,
 }

lib/src/main/java/io/ably/lib/object/instance/Instance.java

@@ -10,30 +10,40 @@
 import io.ably.lib.object.instance.types.LiveMapInstance;
 import io.ably.lib.object.instance.types.NumberInstance;
 import io.ably.lib.object.instance.types.StringInstance;
-import io.ably.lib.objects.ObjectsSubscription;
-import org.jetbrains.annotations.NonBlocking;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * A direct-reference view of a single LiveObject (a {@code LiveMap} or {@code LiveCounter})
- * or a primitive value. Unlike {@code PathObject}, which resolves a path lazily against
- * the LiveObjects graph at every call, an {@code Instance} is bound to a specific
- * underlying value and dereferenced in O(1).
+ * A direct-reference view of a single resolved LiveObject ({@code LiveMap} or
+ * {@code LiveCounter}) or primitive value.
  *
- * <p>Java exposes type-specific sub-types ({@link LiveMapInstance},
- * {@link LiveCounterInstance}, and the primitive {@code *Instance} types). Use the
- * {@code as*} helpers to obtain a sub-type wrapper without performing type validation.
- * Only {@link LiveMapInstance} and {@link LiveCounterInstance} expose an object id
- * (via their own {@code getId()} methods); primitive instances are anonymous.
+ * <p>Unlike {@code PathObject}, which re-resolves its path on every call, an
+ * {@code Instance} is identity-addressed: it is bound to a specific underlying value
+ * and dereferenced in O(1), regardless of where that value sits in the graph. Read
+ * operations validate the access API preconditions and fail with an
+ * {@code AblyException} if they are not satisfied.
  *
- * <p>Spec: RTINS1
+ * <p>This base type exposes only the methods whose behaviour is independent of the
+ * wrapped type; everything else - including {@code subscribe} (RTTS7b) - is
+ * partitioned onto the sub-types. Use the {@code as*} helpers to obtain a sub-type
+ * view without type validation, or discriminate via {@link #getType()}.
+ *
+ * <p>Spec: RTINS1, RTTS7
+ *
+ * @see LiveMapInstance
+ * @see LiveCounterInstance
+ * @see InstanceListener
  */
 public interface Instance {
 
     /**
      * Returns the {@link ValueType} of the value wrapped by this instance. Use this
      * instead of dedicated {@code isLiveMap}/{@code isLiveCounter}/etc. checks.
      *
+     * <p>An {@code Instance} is always constructed from a resolved value, so this never
+     * returns {@link ValueType#UNKNOWN} in normal operation.
+     *
+     * <p>Spec: RTTS8a
+     *
      * @return the wrapped value type
      */
     @NotNull ValueType getType();
@@ -45,38 +55,24 @@ public interface Instance {
      * always bound to a resolved value, so this always returns a non-null result;
      * failures of the access API preconditions are signalled via {@code AblyException}.
      *
-     * <p>Spec: RTINS11
+     * <p>Spec: RTINS11 / RTINS11c (universal non-null invariant - Instance is bound
+     * to an already-resolved value, so the path-resolution failure mode of
+     * PathObject#compactJson does not apply) / RTTS7a (typed-SDK signature reflects
+     * the universal invariant)
      *
      * @return the compacted JSON snapshot
      */
     @NotNull JsonElement compactJson();
 
-    /**
-     * Subscribes a listener for updates on the underlying LiveObject. The listener is
-     * invoked whenever the wrapped object is changed by a local or remote operation.
-     * Call {@link ObjectsSubscription#unsubscribe()} on the returned handle to stop
-     * receiving events for this listener.
-     *
-     * <p>Subscribe is not supported on primitive instances; implementations may throw
-     * when called on {@link NumberInstance}, {@link StringInstance},
-     * {@link BooleanInstance}, {@link BinaryInstance}, {@link JsonObjectInstance} or
-     * {@link JsonArrayInstance}.
-     *
-     * <p>Spec: RTINS16
-     *
-     * @param listener the listener to invoke on updates
-     * @return a subscription handle that can be used to unsubscribe this listener
-     */
-    @NonBlocking
-    @NotNull ObjectsSubscription subscribe(@NotNull Listener listener);
-
     /**
      * Returns this instance wrapped as a {@link LiveMapInstance}.
      *
      * <p>Best-effort cast; does not validate the underlying type. Read operations on
      * the returned wrapper are always permitted; write/terminal operations will fail
      * at call time if the wrapped value is not a {@code LiveMap}.
      *
+     * <p>Spec: RTTS9a
+     *
      * @return a {@link LiveMapInstance} view of this instance
      */
     @NotNull LiveMapInstance asLiveMap();
@@ -85,6 +81,8 @@ public interface Instance {
      * Returns this instance wrapped as a {@link LiveCounterInstance}.
      * Best-effort cast; does not validate the underlying type.
      *
+     * <p>Spec: RTTS9b
+     *
      * @return a {@link LiveCounterInstance} view of this instance
      */
     @NotNull LiveCounterInstance asLiveCounter();
@@ -93,6 +91,8 @@ public interface Instance {
      * Returns this instance wrapped as a {@link NumberInstance}.
      * Best-effort cast; does not validate the underlying type.
      *
+     * <p>Spec: RTTS9c
+     *
      * @return a {@link NumberInstance} view of this instance
      */
     @NotNull NumberInstance asNumber();
@@ -101,6 +101,8 @@ public interface Instance {
      * Returns this instance wrapped as a {@link StringInstance}.
      * Best-effort cast; does not validate the underlying type.
      *
+     * <p>Spec: RTTS9c
+     *
      * @return a {@link StringInstance} view of this instance
      */
     @NotNull StringInstance asString();
@@ -109,6 +111,8 @@ public interface Instance {
      * Returns this instance wrapped as a {@link BooleanInstance}.
      * Best-effort cast; does not validate the underlying type.
      *
+     * <p>Spec: RTTS9c
+     *
      * @return a {@link BooleanInstance} view of this instance
      */
     @NotNull BooleanInstance asBoolean();
@@ -117,6 +121,8 @@ public interface Instance {
      * Returns this instance wrapped as a {@link BinaryInstance}.
      * Best-effort cast; does not validate the underlying type.
      *
+     * <p>Spec: RTTS9c
+     *
      * @return a {@link BinaryInstance} view of this instance
      */
     @NotNull BinaryInstance asBinary();
@@ -125,6 +131,8 @@ public interface Instance {
      * Returns this instance wrapped as a {@link JsonObjectInstance}.
      * Best-effort cast; does not validate the underlying type.
      *
+     * <p>Spec: RTTS9c
+     *
      * @return a {@link JsonObjectInstance} view of this instance
      */
     @NotNull JsonObjectInstance asJsonObject();
@@ -133,37 +141,9 @@ public interface Instance {
      * Returns this instance wrapped as a {@link JsonArrayInstance}.
      * Best-effort cast; does not validate the underlying type.
      *
+     * <p>Spec: RTTS9c
+     *
      * @return a {@link JsonArrayInstance} view of this instance
      */
     @NotNull JsonArrayInstance asJsonArray();
-
-    /**
-     * Listener interface for {@link Instance#subscribe(Listener) instance
-     * subscriptions}.
-     *
-     * <p>Spec: RTINS16a1
-     */
-    interface Listener {
-        /**
-         * Invoked when the wrapped LiveObject is modified.
-         *
-         * @param event the event describing the change
-         */
-        void onUpdated(@NotNull SubscriptionEvent event);
-    }
-
-    /**
-     * Event delivered to {@link Listener#onUpdated(SubscriptionEvent)} when the wrapped
-     * LiveObject is updated.
-     *
-     * <p>Spec: RTINS16e
-     */
-    interface SubscriptionEvent {
-        /**
-         * Returns the {@link Instance} that was updated.
-         *
-         * @return the updated instance
-         */
-        @NotNull Instance getInstance();
-    }
 }

lib/src/main/java/io/ably/lib/object/instance/InstanceListener.java

@@ -0,0 +1,22 @@
+package io.ably.lib.object.instance;
+
+import io.ably.lib.object.instance.types.LiveCounterInstance;
+import io.ably.lib.object.instance.types.LiveMapInstance;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Listener interface for instance subscriptions created via
+ * {@link LiveMapInstance#subscribe(InstanceListener)} or
+ * {@link LiveCounterInstance#subscribe(InstanceListener)}.
+ *
+ * <p>Spec: RTINS16a1
+ */
+public interface InstanceListener {
+
+    /**
+     * Invoked when the wrapped LiveObject is modified.
+     *
+     * @param event the event describing the change
+     */
+    void onUpdated(@NotNull InstanceSubscriptionEvent event);
+}

lib/src/main/java/io/ably/lib/object/instance/InstanceSubscriptionEvent.java

@@ -0,0 +1,37 @@
+package io.ably.lib.object.instance;
+
+import io.ably.lib.object.instance.types.LiveCounterInstance;
+import io.ably.lib.object.instance.types.LiveMapInstance;
+import io.ably.lib.object.message.ObjectMessage;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Event delivered to {@link InstanceListener#onUpdated(InstanceSubscriptionEvent)} when
+ * the LiveObject wrapped by a subscribed {@link LiveMapInstance} or
+ * {@link LiveCounterInstance} is updated.
+ *
+ * <p>Spec: RTINS16e
+ */
+public interface InstanceSubscriptionEvent {
+
+    /**
+     * Returns an {@link Instance} wrapping the LiveObject that was updated.
+     *
+     * <p>Spec: RTINS16e1
+     *
+     * @return the updated instance
+     */
+    @NotNull Instance getObject();
+
+    /**
+     * Returns the {@link ObjectMessage} describing the operation that caused this
+     * event, if any. The value is present whenever the underlying update carried an
+     * object message with an operation; otherwise it is {@code null}.
+     *
+     * <p>Spec: RTINS16e2 / PAOM1
+     *
+     * @return the source {@code ObjectMessage}, or {@code null} if unavailable
+     */
+    @Nullable ObjectMessage getMessage();
+}

lib/src/main/java/io/ably/lib/object/instance/package-info.java

@@ -0,0 +1,12 @@
+/**
+ * The identity-addressed view of the LiveObjects graph.
+ * {@link io.ably.lib.object.instance.Instance} wraps a specific resolved
+ * LiveObject or primitive value and dereferences it in O(1), following the
+ * object wherever it sits in the graph. Type-specific operations live on the
+ * sub-types in {@link io.ably.lib.object.instance.types}; instance
+ * subscriptions use {@link io.ably.lib.object.instance.InstanceListener} and
+ * {@link io.ably.lib.object.instance.InstanceSubscriptionEvent}.
+ *
+ * <p>Spec: RTINS1-RTINS16, RTTS7-RTTS9
+ */
+package io.ably.lib.object.instance;

lib/src/main/java/io/ably/lib/object/instance/types/BinaryInstance.java

@@ -5,15 +5,19 @@
 
 /**
  * A read-only {@link Instance} bound to a binary primitive value
- * (a {@code byte[]}). Primitive instances are anonymous (no object id) and do not
- * support subscribe.
+ * (a {@code byte[]}).
+ * Primitive instances are anonymous (no object id) and deliberately do not expose
+ * {@code subscribe}, {@code set}, {@code remove} or any other id/iteration/write
+ * methods - only {@code value()} - per RTTS10c.
+ *
+ * <p>Spec: RTTS10c
  */
 public interface BinaryInstance extends Instance {
 
     /**
      * Returns the wrapped binary value.
      *
-     * <p>Spec: RTINS4
+     * <p>Spec: RTINS4 / RTTS10c
      *
      * @return the wrapped bytes
      */

lib/src/main/java/io/ably/lib/object/instance/types/BooleanInstance.java

@@ -5,14 +5,18 @@
 
 /**
  * A read-only {@link Instance} bound to a {@code Boolean} primitive value.
- * Primitive instances are anonymous (no object id) and do not support subscribe.
+ * Primitive instances are anonymous (no object id) and deliberately do not expose
+ * {@code subscribe}, {@code set}, {@code remove} or any other id/iteration/write
+ * methods - only {@code value()} - per RTTS10c.
+ *
+ * <p>Spec: RTTS10c
  */
 public interface BooleanInstance extends Instance {
 
     /**
      * Returns the wrapped boolean.
      *
-     * <p>Spec: RTINS4
+     * <p>Spec: RTINS4 / RTTS10c
      *
      * @return the wrapped boolean value
      */

lib/src/main/java/io/ably/lib/object/instance/types/JsonArrayInstance.java

@@ -6,14 +6,18 @@
 
 /**
  * A read-only {@link Instance} bound to a {@link JsonArray} primitive value.
- * Primitive instances are anonymous (no object id) and do not support subscribe.
+ * Primitive instances are anonymous (no object id) and deliberately do not expose
+ * {@code subscribe}, {@code set}, {@code remove} or any other id/iteration/write
+ * methods - only {@code value()} - per RTTS10c.
+ *
+ * <p>Spec: RTTS10c
  */
 public interface JsonArrayInstance extends Instance {
 
     /**
      * Returns the wrapped JSON array.
      *
-     * <p>Spec: RTINS4
+     * <p>Spec: RTINS4 / RTTS10c
      *
      * @return the wrapped JsonArray value
      */