Package io.ably.lib.objects

Interface RealtimeObjects

All Superinterfaces:
ObjectsStateChange
public interface RealtimeObjects extends ObjectsStateChange
The RealtimeObjects interface provides methods to interact with live data objects, such as maps and counters, in a real-time environment. It supports both synchronous and asynchronous operations for retrieving and creating objects.

Implementations of this interface must be thread-safe as they may be accessed from multiple threads concurrently.

  • Method Details

    • getRoot

      @Blocking @NotNull @NotNull LiveMap getRoot()
      Retrieves the root LiveMap object. When called without a type variable, we return a default root type which is based on globally defined interface for Objects feature. A user can provide an explicit type for the getRoot method to explicitly set the type structure on this particular channel. This is useful when working with multiple channels with different underlying data structure.
      Returns:
      the root LiveMap instance.

    • createMap

      @Blocking @NotNull @NotNull LiveMap createMap()
      Creates a new empty LiveMap with no entries. Send a MAP_CREATE operation to the realtime system to create a new map object in the pool. Once the ACK message is received, the method returns the object from the local pool if it got created due to the echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locally and returns it.
      Returns:
      the newly created empty LiveMap instance.

    • createMap

      @Blocking @NotNull @NotNull LiveMap createMap(@NotNull @NotNull Map<String,LiveMapValue> entries)
      Creates a new LiveMap with type-safe entries that can be Boolean, Binary, Number, String, JsonArray, JsonObject, LiveCounter, or LiveMap. Implements spec RTO11 : createMap(Dict<String, Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounter | LiveMap> entries?) Send a MAP_CREATE operation to the realtime system to create a new map object in the pool. Once the ACK message is received, the method returns the object from the local pool if it got created due to the echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locally using the provided data and returns it.

      Example:

      
 Map<String, LiveMapValue> entries = Map.of(
     "string", LiveMapValue.of("Hello"),
     "number", LiveMapValue.of(42),
     "boolean", LiveMapValue.of(true),
     "binary", LiveMapValue.of(new byte[]{1, 2, 3}),
     "array", LiveMapValue.of(new JsonArray()),
     "object", LiveMapValue.of(new JsonObject()),
     "counter", LiveMapValue.of(realtimeObjects.createCounter()),
     "nested", LiveMapValue.of(realtimeObjects.createMap())
 );
 LiveMap map = realtimeObjects.createMap(entries);
      Parameters:
      entries - the type-safe map entries with values that can be Boolean, Binary, Number, String, JsonArray, JsonObject, LiveCounter, or LiveMap.
      Returns:
      the newly created LiveMap instance.

    • createCounter

      @Blocking @NotNull @NotNull LiveCounter createCounter()
      Creates a new LiveCounter with an initial value of 0. Send a COUNTER_CREATE operation to the realtime system to create a new counter object in the pool. Once the ACK message is received, the method returns the object from the local pool if it got created due to the echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locally using the provided data and returns it.
      Returns:
      the newly created LiveCounter instance with initial value of 0.

    • createCounter

      @Blocking @NotNull @NotNull LiveCounter createCounter(@NotNull @NotNull Number initialValue)
      Creates a new LiveCounter with an initial value. Send a COUNTER_CREATE operation to the realtime system to create a new counter object in the pool. Once the ACK message is received, the method returns the object from the local pool if it got created due to the echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locally using the provided data and returns it.
      Parameters:
      initialValue - the initial value of the LiveCounter.
      Returns:
      the newly created LiveCounter instance.

    • getRootAsync

      @NonBlocking void getRootAsync(@NotNull @NotNull ObjectsCallback<@NotNull LiveMap> callback)
      Asynchronously retrieves the root LiveMap object. When called without a type variable, we return a default root type which is based on globally defined interface for Objects feature. A user can provide an explicit type for the getRoot method to explicitly set the type structure on this particular channel. This is useful when working with multiple channels with different underlying data structure.
      Parameters:
      callback - the callback to handle the result or error.

    • createMapAsync

      @NonBlocking void createMapAsync(@NotNull @NotNull ObjectsCallback<@NotNull LiveMap> callback)
      Asynchronously creates a new empty LiveMap with no entries. Send a MAP_CREATE operation to the realtime system to create a new map object in the pool. Once the ACK message is received, the method returns the object from the local pool if it got created due to the echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locally and returns it.
      Parameters:
      callback - the callback to handle the result or error.

    • createMapAsync

      @NonBlocking void createMapAsync(@NotNull @NotNull Map<String,LiveMapValue> entries, @NotNull @NotNull ObjectsCallback<@NotNull LiveMap> callback)
      Asynchronously creates a new LiveMap with type-safe entries that can be Boolean, Binary, Number, String, JsonArray, JsonObject, LiveCounter, or LiveMap. This method implements the spec RTO11 signature: createMap(Dict<String, Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounter | LiveMap> entries?) Send a MAP_CREATE operation to the realtime system to create a new map object in the pool. Once the ACK message is received, the method returns the object from the local pool if it got created due to the echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locally using the provided data and returns it.
      Parameters:
      entries - the type-safe map entries with values that can be Boolean, Binary, Number, String, JsonArray, JsonObject, LiveCounter, or LiveMap.
      callback - the callback to handle the result or error.

    • createCounterAsync

      @NonBlocking void createCounterAsync(@NotNull @NotNull ObjectsCallback<@NotNull LiveCounter> callback)
      Asynchronously creates a new LiveCounter with an initial value of 0. Send a COUNTER_CREATE operation to the realtime system to create a new counter object in the pool. Once the ACK message is received, the method returns the object from the local pool if it got created due to the echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locally using the provided data and returns it.
      Parameters:
      callback - the callback to handle the result or error.

    • createCounterAsync

      @NonBlocking void createCounterAsync(@NotNull @NotNull Number initialValue, @NotNull @NotNull ObjectsCallback<@NotNull LiveCounter> callback)
      Asynchronously creates a new LiveCounter with an initial value. Send a COUNTER_CREATE operation to the realtime system to create a new counter object in the pool. Once the ACK message is received, the method returns the object from the local pool if it got created due to the echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locally using the provided data and returns it.
      Parameters:
      initialValue - the initial value of the LiveCounter.
      callback - the callback to handle the result or error.