Package io.ably.lib.liveobjects

Class RealtimeObject.Unavailable

java.lang.Object
io.ably.lib.liveobjects.RealtimeObject.Unavailable
All Implemented Interfaces:
RealtimeObject, ObjectStateChange
Enclosing interface:
RealtimeObject
public static final class RealtimeObject.Unavailable extends Object implements RealtimeObject
Null-Object guard for RealtimeObject, used as the value of channel.object when the LiveObjects plugin is not installed.

Because channel.object is a field, dereferencing it can never throw; instead every method here fails fast with the plugin-missing error, so get(), on(), off() and offAll() surface a clear, consistent error rather than a NullPointerException.

A stateless singleton (INSTANCE) shared across all channels that lack the plugin. Adding a method to RealtimeObject will fail compilation here until it is guarded, which is the intended safety net.

  • Field Details

  • Method Details

    • get

      @NotNull public @NotNull CompletableFuture<LiveMapPathObject> get()
      Description copied from interface: RealtimeObject
      Retrieves a LiveMapPathObject rooted at the channel's root LiveMap. The returned object has an empty path and resolves to the root LiveMap; use its navigation methods to address nested values within the objects graph.

      When called without a type variable, we return a default root type which is based on the globally defined interface for the Objects feature. A user can provide an explicit type to set the type structure on this particular channel. This is useful when working with multiple channels with different underlying data structures.

      This operation requires the OBJECT_SUBSCRIBE channel mode. It implicitly attaches the channel if it is not already attached; the returned future completes once the objects synchronization state has transitioned to SYNCED, and completes exceptionally with an AblyException if synchronization fails.

      Spec: RTO23, RTO23f (typed SDKs return a LiveMapPathObject)

      Specified by:
      get in interface RealtimeObject
      Returns:
      a future that completes with the root LiveMapPathObject for this channel's objects graph.

    • on

      public Subscription on(@NotNull @NotNull ObjectStateEvent event, @NotNull ObjectStateChange.Listener listener)
      Description copied from interface: ObjectStateChange
      Subscribes to a specific Objects synchronization state event.

      This method registers the provided listener to be notified when the specified synchronization state event occurs. The returned subscription can be used to unsubscribe later when the notifications are no longer needed.

      Specified by:
      on in interface ObjectStateChange
      Parameters:
      event - the synchronization state event to subscribe to (SYNCING or SYNCED)
      listener - the listener that will be called when the event occurs
      Returns:
      a subscription object that can be used to unsubscribe from the event

    • off

      public void off(@NotNull ObjectStateChange.Listener listener)
      Description copied from interface: ObjectStateChange
      Unsubscribes the specified listener from all synchronization state events.

      After calling this method, the provided listener will no longer receive any synchronization state event notifications.

      Specified by:
      off in interface ObjectStateChange
      Parameters:
      listener - the listener to unregister from all events

    • offAll

      public void offAll()
      Description copied from interface: ObjectStateChange
      Unsubscribes all listeners from all synchronization state events.

      After calling this method, no listeners will receive any synchronization state event notifications until new listeners are registered.

      Specified by:
      offAll in interface ObjectStateChange