Package io.ably.lib.liveobjects.instance

Interface Instance

All Known Subinterfaces:
BinaryInstance, BooleanInstance, JsonArrayInstance, JsonObjectInstance, LiveCounterInstance, LiveMapInstance, NumberInstance, StringInstance
public interface Instance
A direct-reference view of a single resolved LiveObject (LiveMap or LiveCounter) or primitive value.

Unlike PathObject, which re-resolves its path on every call, an Instance is identity-addressed: it wraps an already-resolved value (typically obtained from a 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 AblyException if those are not satisfied.

This base type exposes only the methods whose behaviour is independent of the wrapped type; everything else - including subscribe (RTTS7b) - is partitioned onto the sub-types. Use the as* helpers to obtain a sub-type view, or discriminate via getType(). Because the wrapped type is fixed and known, a mismatched as* cast fails fast with an IllegalStateException rather than returning a best-effort view (contrast PathObject, whose casts never throw).

Spec: RTINS1, RTTS7

See Also:

  • Method Details

    • getType

      @NotNull @NotNull ValueType getType()
      Returns the ValueType of the value wrapped by this instance. Use this instead of dedicated isLiveMap/isLiveCounter/etc. checks.

      An Instance is always constructed from a resolved value, so this never returns ValueType.UNKNOWN in normal operation.

      Spec: RTTS8a

      Returns:
      the wrapped value type

    • compactJson

      @NotNull @NotNull com.google.gson.JsonElement compactJson()
      Returns a JSON-serializable, recursively compacted snapshot of the wrapped value. Behaves identically to PathObject#compactJson except that it operates on the wrapped value directly instead of resolving a path. An Instance is always bound to a resolved value, so this always returns a non-null result; failures of the access API preconditions are signalled via AblyException.

      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)

      Returns:
      the compacted JSON snapshot

    • asLiveMap

      @NotNull @NotNull LiveMapInstance asLiveMap()
      Returns this instance viewed as a LiveMapInstance.

      Because an Instance wraps an already-resolved value of a known, fixed type, this fails fast: it throws IllegalStateException if the wrapped value is not a LiveMap, rather than returning a best-effort view. Use getType() to discriminate the type before casting.

      Spec: RTTS9a / RTTS9d

      Returns:
      a LiveMapInstance view of this instance
      Throws:
      IllegalStateException - if the wrapped value is not a LiveMap

    • asLiveCounter

      @NotNull @NotNull LiveCounterInstance asLiveCounter()
      Returns this instance viewed as a LiveCounterInstance. Fails fast: throws IllegalStateException if the wrapped value is not a LiveCounter.

      Spec: RTTS9b / RTTS9d

      Returns:
      a LiveCounterInstance view of this instance
      Throws:
      IllegalStateException - if the wrapped value is not a LiveCounter

    • asNumber

      @NotNull @NotNull NumberInstance asNumber()
      Returns this instance viewed as a NumberInstance. Fails fast: throws IllegalStateException if the wrapped value is not a Number.

      Spec: RTTS9c / RTTS9d

      Returns:
      a NumberInstance view of this instance
      Throws:
      IllegalStateException - if the wrapped value is not a Number

    • asString

      @NotNull @NotNull StringInstance asString()
      Returns this instance viewed as a StringInstance. Fails fast: throws IllegalStateException if the wrapped value is not a String.

      Spec: RTTS9c / RTTS9d

      Returns:
      a StringInstance view of this instance
      Throws:
      IllegalStateException - if the wrapped value is not a String

    • asBoolean

      @NotNull @NotNull BooleanInstance asBoolean()
      Returns this instance viewed as a BooleanInstance. Fails fast: throws IllegalStateException if the wrapped value is not a Boolean.

      Spec: RTTS9c / RTTS9d

      Returns:
      a BooleanInstance view of this instance
      Throws:
      IllegalStateException - if the wrapped value is not a Boolean

    • asBinary

      @NotNull @NotNull BinaryInstance asBinary()
      Returns this instance viewed as a BinaryInstance. Fails fast: throws IllegalStateException if the wrapped value is not a binary value.

      Spec: RTTS9c / RTTS9d

      Returns:
      a BinaryInstance view of this instance
      Throws:
      IllegalStateException - if the wrapped value is not a binary value

    • asJsonObject

      @NotNull @NotNull JsonObjectInstance asJsonObject()
      Returns this instance viewed as a JsonObjectInstance. Fails fast: throws IllegalStateException if the wrapped value is not a JSON object.

      Spec: RTTS9c / RTTS9d

      Returns:
      a JsonObjectInstance view of this instance
      Throws:
      IllegalStateException - if the wrapped value is not a JSON object

    • asJsonArray

      @NotNull @NotNull JsonArrayInstance asJsonArray()
      Returns this instance viewed as a JsonArrayInstance. Fails fast: throws IllegalStateException if the wrapped value is not a JSON array.

      Spec: RTTS9c / RTTS9d

      Returns:
      a JsonArrayInstance view of this instance
      Throws:
      IllegalStateException - if the wrapped value is not a JSON array