Package io.ably.lib.liveobjects.path

Interface PathObject

All Known Subinterfaces:
BinaryPathObject, BooleanPathObject, JsonArrayPathObject, JsonObjectPathObject, LiveCounterPathObject, LiveMapPathObject, NumberPathObject, StringPathObject
public interface PathObject
A lazy, path-based reference into the LiveObjects graph rooted at the channel's root LiveMap.

A PathObject stores a path as an ordered list of string segments and resolves it against the local object graph each time a terminal method is called; the freshly resolved value is the sole basis for that call's result. Resolution is best-effort: the value at a path may change between two calls (e.g. between exists() and a subsequent write) as updates from other clients are applied.

When the path does not resolve, or resolves to a type the called method does not apply to, read operations degrade gracefully - returning null or an empty result - whereas write operations fail with an AblyException (code 92005 if the path does not resolve, 92007 on a type mismatch). All terminal operations additionally validate the access/write API preconditions and fail with an AblyException if those are not satisfied.

This base type exposes only the methods whose behaviour is independent of the resolved type; map and counter reads/writes are partitioned onto the sub-types (RTTS3e). Use the as* helpers to obtain a sub-type view without type validation, e.g. pathObject.asLiveMap().at("a.b.c") (RTTS3g). The spec's compact is not exposed; compactJson() is the supported equivalent (RTTS3f).

Spec: RTPO1, RTPO2, RTTS3

See Also:

  • Method Details

    • getType

      @Nullable @Nullable ValueType getType()
      Returns the ValueType of the value currently resolved at this path, or null when the path does not resolve to any value. Use this instead of dedicated isLiveMap/isLiveCounter/etc. checks.

      A null result means there is no value at this path - nothing is stored there (e.g. an absent or removed map entry). This is deliberately distinct from ValueType.UNKNOWN, which is returned only when a value is present but its type matches none of the known categories. In other words: null means "no value", UNKNOWN means "a value of an unrecognized type".

      Spec: RTTS4b

      Returns:
      the resolved value type at this path, or null if the path does not resolve to a value

    • path

      @NotNull @NotNull String path()
      Returns a dot-delimited string representation of the stored path segments. Dot characters inside individual segments are escaped with a backslash, so a path with segments ["a", "b.c", "d"] is represented as "a.b\.c.d". An empty path (i.e. the root PathObject) returns the empty string.

      Spec: RTPO4 / RTTS3a

      Returns:
      the dot-delimited path from the root to this position

    • instance

      @Nullable @Nullable Instance instance()
      Resolves this path and returns a Instance wrapping the resolved value, whether it is a LiveMap, LiveCounter or a primitive (RTPO8c/RTPO8f).

      Returns null when the path does not resolve (RTPO8e).

      Spec: RTPO8 / RTTS3b

      Returns:
      a Instance wrapping the resolved value, or null

    • compactJson

      @Nullable @Nullable com.google.gson.JsonElement compactJson()
      Returns a JSON-serializable, recursively compacted snapshot of the value at this path. Behaves like the spec's compact except that Binary values are base64-encoded and cyclic references are represented as { "objectId": ... } markers, so the result is safe to serialise as JSON.

      Returns null when the path does not resolve.

      Spec: RTPO14 / RTTS3c

      Returns:
      the compacted JSON snapshot, or null if the path does not resolve

    • exists

      boolean exists()
      Returns true if a value currently resolves at this path in the local object graph. This is a best-effort check evaluated at call time; the answer may change immediately afterwards as remote operations are applied. Useful as a guard before performing operations whose semantics depend on existence.

      Complexity is O(n) in the path length because the path must be resolved.

      Spec: RTTS4a

      Returns:
      true if the path resolves to a value, false otherwise

    • asLiveMap

      @NotNull @NotNull LiveMapPathObject asLiveMap()
      Returns this PathObject wrapped as a LiveMapPathObject.

      This is a best-effort cast - it does not validate that the underlying value at this path is a LiveMap. Read operations are always permitted on the returned wrapper; write or terminal operations that require resolution will fail at call time if the resolved value is not a LiveMap.

      Spec: RTTS5a

      Returns:
      a LiveMapPathObject view of this path

    • asLiveCounter

      @NotNull @NotNull LiveCounterPathObject asLiveCounter()
      Returns this PathObject wrapped as a LiveCounterPathObject. Best-effort cast; does not validate the underlying type at this path.

      Spec: RTTS5b

      Returns:
      a LiveCounterPathObject view of this path

    • asNumber

      @NotNull @NotNull NumberPathObject asNumber()
      Returns this PathObject wrapped as a NumberPathObject. Best-effort cast; does not validate the underlying type at this path.

      Spec: RTTS5c

      Returns:
      a NumberPathObject view of this path

    • asString

      @NotNull @NotNull StringPathObject asString()
      Returns this PathObject wrapped as a StringPathObject. Best-effort cast; does not validate the underlying type at this path.

      Spec: RTTS5c

      Returns:
      a StringPathObject view of this path

    • asBoolean

      @NotNull @NotNull BooleanPathObject asBoolean()
      Returns this PathObject wrapped as a BooleanPathObject. Best-effort cast; does not validate the underlying type at this path.

      Spec: RTTS5c

      Returns:
      a BooleanPathObject view of this path

    • asBinary

      @NotNull @NotNull BinaryPathObject asBinary()
      Returns this PathObject wrapped as a BinaryPathObject. Best-effort cast; does not validate the underlying type at this path.

      Spec: RTTS5c

      Returns:
      a BinaryPathObject view of this path

    • asJsonObject

      @NotNull @NotNull JsonObjectPathObject asJsonObject()
      Returns this PathObject wrapped as a JsonObjectPathObject. Best-effort cast; does not validate the underlying type at this path.

      Spec: RTTS5c

      Returns:
      a JsonObjectPathObject view of this path

    • asJsonArray

      @NotNull @NotNull JsonArrayPathObject asJsonArray()
      Returns this PathObject wrapped as a JsonArrayPathObject. Best-effort cast; does not validate the underlying type at this path.

      Spec: RTTS5c

      Returns:
      a JsonArrayPathObject view of this path

    • subscribe

      @NonBlocking @NotNull @NotNull Subscription subscribe(@NotNull @NotNull PathObjectListener listener)
      Subscribes a listener for path-based update events. The listener is invoked when an operation modifies the value at this path. The same path may be subscribed by multiple listeners independently. Call Subscription.unsubscribe() on the returned handle to stop receiving events for this listener.

      Spec: RTPO19 / RTTS3d

      Parameters:
      listener - the listener to invoke on updates
      Returns:
      a subscription handle that can be used to unsubscribe this listener

    • subscribe

      @NonBlocking @NotNull @NotNull Subscription subscribe(@NotNull @NotNull PathObjectListener listener, @Nullable @Nullable PathObjectSubscriptionOptions options)
      Subscribes a listener for path-based update events using the provided PathObjectSubscriptionOptions. Options control coverage rules such as the depth of nested updates that trigger the listener. Call Subscription.unsubscribe() on the returned handle to stop receiving events for this listener.

      Spec: RTPO19 / RTTS3d

      Parameters:
      listener - the listener to invoke on updates
      options - optional subscription options, may be null
      Returns:
      a subscription handle that can be used to unsubscribe this listener