Merge pull request #1217 from ably/chore/liveobjects-add-basic-implementation

[AIT-928] Added basic impl. for PathObject and Instance interfaces

Author: sacOO7

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

@@ -23,6 +23,6 @@ public enum ValueType {
     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 */
+    /** Returned by {@code PathObject#getType()} only when a value is present but matches 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/adapter/AblyClientAdapter.java

@@ -0,0 +1,53 @@
+package io.ably.lib.object.adapter;
+
+import io.ably.lib.realtime.ChannelBase;
+import io.ably.lib.realtime.Connection;
+import io.ably.lib.types.AblyException;
+import io.ably.lib.types.ClientOptions;
+import org.jetbrains.annotations.Blocking;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Bridges the path-based LiveObjects implementation to the core Ably client, exposing the
+ * client configuration, connection and channel state it needs without coupling it to the
+ * concrete {@link io.ably.lib.realtime.AblyRealtime} type.
+ *
+ * <p>This is the adapter for the path-based {@code io.ably.lib.object} API and is intentionally
+ * kept independent of the legacy {@code io.ably.lib.objects} package.
+ */
+public interface AblyClientAdapter {
+    /**
+     * Retrieves the client options configured for the Ably client.
+     * Used to access client configuration parameters such as echoMessages setting
+     * that affect the behavior of Objects operations.
+     *
+     * @return the client options containing configuration parameters
+     */
+    @NotNull ClientOptions getClientOptions();
+
+    /**
+     * Retrieves the connection instance for handling connection state and operations.
+     * Used to check connection status, obtain error information, and manage
+     * message transmission across the Ably connection.
+     *
+     * @return the connection instance
+     */
+    @NotNull Connection getConnection();
+
+    /**
+     * Retrieves the current time in milliseconds from the Ably server.
+     * Spec: RTO16
+     */
+    @Blocking
+    long getTime() throws AblyException;
+
+    /**
+     * Retrieves the channel instance for the specified channel name.
+     * If the channel does not exist, an AblyException is thrown.
+     *
+     * @param channelName the name of the channel to retrieve
+     * @return the ChannelBase instance for the specified channel
+     * @throws AblyException if the channel is not found or cannot be retrieved
+     */
+    @NotNull ChannelBase getChannel(@NotNull String channelName) throws AblyException;
+}

lib/src/main/java/io/ably/lib/object/adapter/Adapter.java

@@ -0,0 +1,56 @@
+package io.ably.lib.object.adapter;
+
+import io.ably.lib.realtime.AblyRealtime;
+import io.ably.lib.realtime.Channel;
+import io.ably.lib.realtime.ChannelBase;
+import io.ably.lib.realtime.Connection;
+import io.ably.lib.types.AblyException;
+import io.ably.lib.types.ClientOptions;
+import io.ably.lib.types.ErrorInfo;
+import io.ably.lib.types.ReadOnlyMap;
+import io.ably.lib.util.Log;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Default {@link AblyClientAdapter} implementation backed by an {@link AblyRealtime} client.
+ * Holding the {@code AblyRealtime} reference gives the path-based LiveObjects implementation
+ * access to the full client configuration and runtime state it may need.
+ */
+public class Adapter implements AblyClientAdapter {
+    private final AblyRealtime ably;
+    private static final String TAG = AblyClientAdapter.class.getName();
+
+    public Adapter(@NotNull AblyRealtime ably) {
+        this.ably = ably;
+    }
+
+    @Override
+    public @NotNull ClientOptions getClientOptions() {
+        return ably.options;
+    }
+
+    @Override
+    public @NotNull Connection getConnection() {
+        return ably.connection;
+    }
+
+    @Override
+    public long getTime() throws AblyException {
+        return ably.time();
+    }
+
+    @Override
+    public @NotNull ChannelBase getChannel(@NotNull String channelName) throws AblyException {
+        // Look up via the read-only map view. Channels#get(String) would create the channel if
+        // absent; ReadOnlyMap only exposes get(Object), which returns null atomically for an
+        // unknown channel instead of silently recreating it.
+        final ReadOnlyMap<String, Channel> channels = ably.channels;
+        final ChannelBase channel = channels.get(channelName);
+        if (channel == null) {
+            Log.e(TAG, "getChannel(): channel not found: " + channelName);
+            ErrorInfo errorInfo = new ErrorInfo("Channel not found: " + channelName, 404);
+            throw AblyException.fromErrorInfo(errorInfo);
+        }
+        return channel;
+    }
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Adapter layer bridging the path-based LiveObjects implementation to the core Ably client.
+ * {@link io.ably.lib.object.adapter.AblyClientAdapter} is the abstraction the implementation
+ * depends on; {@link io.ably.lib.object.adapter.Adapter} is the default implementation backed
+ * by an {@link io.ably.lib.realtime.AblyRealtime} client.
+ *
+ * <p>This package is intentionally independent of the legacy {@code io.ably.lib.objects}
+ * package so the path-based API can evolve on its own.
+ */
+package io.ably.lib.object.adapter;

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

@@ -17,15 +17,19 @@
  * {@code LiveCounter}) or primitive value.
  *
  * <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.
+ * {@code Instance} is identity-addressed: it wraps an already-resolved value (typically
+ * obtained from a {@code PathObject}), so its type is fixed and known for the lifetime
+ * of the instance, and it is 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 those are not satisfied.
  *
  * <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()}.
+ * view, or discriminate via {@link #getType()}. Because the wrapped type is fixed and
+ * known, a mismatched {@code as*} cast fails fast with an {@link IllegalStateException}
+ * rather than returning a best-effort view (contrast {@code PathObject}, whose casts
+ * never throw).
  *
  * <p>Spec: RTINS1, RTTS7
  *
@@ -65,85 +69,101 @@ public interface Instance {
     @NotNull JsonElement compactJson();
 
     /**
-     * Returns this instance wrapped as a {@link LiveMapInstance}.
+     * Returns this instance viewed 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>Because an {@code Instance} wraps an already-resolved value of a known, fixed
+     * type, this fails fast: it throws {@link IllegalStateException} if the wrapped value
+     * is not a {@code LiveMap}, rather than returning a best-effort view. Use
+     * {@link #getType()} to discriminate the type before casting.
      *
-     * <p>Spec: RTTS9a
+     * <p>Spec: RTTS9a / RTTS9d
      *
      * @return a {@link LiveMapInstance} view of this instance
+     * @throws IllegalStateException if the wrapped value is not a {@code LiveMap}
      */
     @NotNull LiveMapInstance asLiveMap();
 
     /**
-     * Returns this instance wrapped as a {@link LiveCounterInstance}.
-     * Best-effort cast; does not validate the underlying type.
+     * Returns this instance viewed as a {@link LiveCounterInstance}.
+     * Fails fast: throws {@link IllegalStateException} if the wrapped value is not a
+     * {@code LiveCounter}.
      *
-     * <p>Spec: RTTS9b
+     * <p>Spec: RTTS9b / RTTS9d
      *
      * @return a {@link LiveCounterInstance} view of this instance
+     * @throws IllegalStateException if the wrapped value is not a {@code LiveCounter}
      */
     @NotNull LiveCounterInstance asLiveCounter();
 
     /**
-     * Returns this instance wrapped as a {@link NumberInstance}.
-     * Best-effort cast; does not validate the underlying type.
+     * Returns this instance viewed as a {@link NumberInstance}.
+     * Fails fast: throws {@link IllegalStateException} if the wrapped value is not a
+     * {@code Number}.
      *
-     * <p>Spec: RTTS9c
+     * <p>Spec: RTTS9c / RTTS9d
      *
      * @return a {@link NumberInstance} view of this instance
+     * @throws IllegalStateException if the wrapped value is not a {@code Number}
      */
     @NotNull NumberInstance asNumber();
 
     /**
-     * Returns this instance wrapped as a {@link StringInstance}.
-     * Best-effort cast; does not validate the underlying type.
+     * Returns this instance viewed as a {@link StringInstance}.
+     * Fails fast: throws {@link IllegalStateException} if the wrapped value is not a
+     * {@code String}.
      *
-     * <p>Spec: RTTS9c
+     * <p>Spec: RTTS9c / RTTS9d
      *
      * @return a {@link StringInstance} view of this instance
+     * @throws IllegalStateException if the wrapped value is not a {@code String}
      */
     @NotNull StringInstance asString();
 
     /**
-     * Returns this instance wrapped as a {@link BooleanInstance}.
-     * Best-effort cast; does not validate the underlying type.
+     * Returns this instance viewed as a {@link BooleanInstance}.
+     * Fails fast: throws {@link IllegalStateException} if the wrapped value is not a
+     * {@code Boolean}.
      *
-     * <p>Spec: RTTS9c
+     * <p>Spec: RTTS9c / RTTS9d
      *
      * @return a {@link BooleanInstance} view of this instance
+     * @throws IllegalStateException if the wrapped value is not a {@code Boolean}
      */
     @NotNull BooleanInstance asBoolean();
 
     /**
-     * Returns this instance wrapped as a {@link BinaryInstance}.
-     * Best-effort cast; does not validate the underlying type.
+     * Returns this instance viewed as a {@link BinaryInstance}.
+     * Fails fast: throws {@link IllegalStateException} if the wrapped value is not a
+     * binary value.
      *
-     * <p>Spec: RTTS9c
+     * <p>Spec: RTTS9c / RTTS9d
      *
      * @return a {@link BinaryInstance} view of this instance
+     * @throws IllegalStateException if the wrapped value is not a binary value
      */
     @NotNull BinaryInstance asBinary();
 
     /**
-     * Returns this instance wrapped as a {@link JsonObjectInstance}.
-     * Best-effort cast; does not validate the underlying type.
+     * Returns this instance viewed as a {@link JsonObjectInstance}.
+     * Fails fast: throws {@link IllegalStateException} if the wrapped value is not a
+     * JSON object.
      *
-     * <p>Spec: RTTS9c
+     * <p>Spec: RTTS9c / RTTS9d
      *
      * @return a {@link JsonObjectInstance} view of this instance
+     * @throws IllegalStateException if the wrapped value is not a JSON object
      */
     @NotNull JsonObjectInstance asJsonObject();
 
     /**
-     * Returns this instance wrapped as a {@link JsonArrayInstance}.
-     * Best-effort cast; does not validate the underlying type.
+     * Returns this instance viewed as a {@link JsonArrayInstance}.
+     * Fails fast: throws {@link IllegalStateException} if the wrapped value is not a
+     * JSON array.
      *
-     * <p>Spec: RTTS9c
+     * <p>Spec: RTTS9c / RTTS9d
      *
      * @return a {@link JsonArrayInstance} view of this instance
+     * @throws IllegalStateException if the wrapped value is not a JSON array
      */
     @NotNull JsonArrayInstance asJsonArray();
 }

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

@@ -1,5 +1,6 @@
 package io.ably.lib.object.instance.types;
 
+import com.google.gson.JsonPrimitive;
 import io.ably.lib.object.instance.Instance;
 import org.jetbrains.annotations.NotNull;
 
@@ -22,4 +23,15 @@ public interface BinaryInstance extends Instance {
      * @return the wrapped bytes
      */
     byte @NotNull [] value();
+
+    /**
+     * Returns the compacted JSON snapshot of the wrapped value, narrowed to a
+     * {@link JsonPrimitive}: binary compacts to a base64-encoded JSON string.
+     *
+     * <p>Spec: RTTS7a
+     *
+     * @return the compacted JSON primitive
+     */
+    @Override
+    @NotNull JsonPrimitive compactJson();
 }

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

@@ -1,5 +1,6 @@
 package io.ably.lib.object.instance.types;
 
+import com.google.gson.JsonPrimitive;
 import io.ably.lib.object.instance.Instance;
 import org.jetbrains.annotations.NotNull;
 
@@ -22,4 +23,16 @@ public interface BooleanInstance extends Instance {
      */
     @NotNull
     Boolean value();
+
+    /**
+     * Returns the compacted JSON snapshot of the wrapped value, narrowed to a
+     * {@link JsonPrimitive}: a {@code BooleanInstance} always compacts to a single
+     * JSON primitive.
+     *
+     * <p>Spec: RTTS7a
+     *
+     * @return the compacted JSON primitive
+     */
+    @Override
+    @NotNull JsonPrimitive compactJson();
 }

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

@@ -23,4 +23,15 @@ public interface JsonArrayInstance extends Instance {
      */
     @NotNull
     JsonArray value();
+
+    /**
+     * Returns the compacted JSON snapshot of the wrapped value, narrowed to a
+     * {@link JsonArray}: a {@code JsonArrayInstance} always compacts to a JSON array.
+     *
+     * <p>Spec: RTTS7a
+     *
+     * @return the compacted JSON array
+     */
+    @Override
+    @NotNull JsonArray compactJson();
 }

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

@@ -23,4 +23,15 @@ public interface JsonObjectInstance extends Instance {
      */
     @NotNull
     JsonObject value();
+
+    /**
+     * Returns the compacted JSON snapshot of the wrapped value, narrowed to a
+     * {@link JsonObject}: a {@code JsonObjectInstance} always compacts to a JSON object.
+     *
+     * <p>Spec: RTTS7a
+     *
+     * @return the compacted JSON object
+     */
+    @Override
+    @NotNull JsonObject compactJson();
 }

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

@@ -1,5 +1,6 @@
 package io.ably.lib.object.instance.types;
 
+import com.google.gson.JsonPrimitive;
 import io.ably.lib.object.instance.Instance;
 import io.ably.lib.object.instance.InstanceListener;
 import io.ably.lib.object.Subscription;
@@ -37,6 +38,18 @@ public interface LiveCounterInstance extends Instance {
     @NotNull
     Double value();
 
+    /**
+     * Returns the compacted JSON snapshot of the wrapped value, narrowed to a
+     * {@link JsonPrimitive}: a {@code LiveCounterInstance} always compacts to a numeric
+     * JSON primitive.
+     *
+     * <p>Spec: RTTS7a
+     *
+     * @return the compacted JSON primitive
+     */
+    @Override
+    @NotNull JsonPrimitive compactJson();
+
     /**
      * Increments the wrapped {@code LiveCounter} by {@code 1}. Equivalent to
      * calling {@link #increment(Number)} with {@code 1}.