Package 

Interface RealtimeObjects

  • All Implemented Interfaces:
    io.ably.lib.objects.state.ObjectsStateChange 
    
public interface RealtimeObjects
 implements 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 Summary

      Modifier and Type Method Description
      abstract 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.
      abstract 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 tothe echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locallyand returns it.
      abstract LiveMap createMap(@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.
      abstract 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 tothe echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locallyusing the provided data and returns it.
      abstract LiveCounter createCounter(@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 tothe echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locallyusing the provided data and returns it.
      abstract void getRootAsync(@NotNull() ObjectsCallback<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.
      abstract void createMapAsync(@NotNull() ObjectsCallback<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 tothe echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locallyand returns it.
      abstract void createMapAsync(@NotNull() Map<String, LiveMapValue> entries, @NotNull() ObjectsCallback<LiveMap> callback) Asynchronously creates a new LiveMap with type-safe entries that can be Boolean, Binary, Number, String, JsonArray, JsonObject, LiveCounter, or LiveMap.
      abstract void createCounterAsync(@NotNull() ObjectsCallback<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 tothe echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locallyusing the provided data and returns it.
      abstract void createCounterAsync(@NotNull() Number initialValue, @NotNull() ObjectsCallback<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 tothe echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locallyusing the provided data and returns it.

      • Methods inherited from class io.ably.lib.objects.state.ObjectsStateChange

        off, offAll, on

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • getRoot

        @Blocking()@NotNull() abstract 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.

      • createMap

        @Blocking()@NotNull() abstract 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 tothe echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locallyand returns it.

      • createMap

        @Blocking()@NotNull() abstract LiveMap createMap(@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(Dictentries?)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 tothe echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locallyusing the provided data and returns it.

        Example:
        {@code * Mapentries = 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.

      • createCounter

        @Blocking()@NotNull() abstract 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 tothe echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locallyusing the provided data and returns it.

      • createCounter

        @Blocking()@NotNull() abstract LiveCounter createCounter(@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 tothe echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locallyusing the provided data and returns it.

        Parameters:
        initialValue - the initial value of the LiveCounter.

      • getRootAsync

        @NonBlocking() abstract void getRootAsync(@NotNull() ObjectsCallback<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() abstract void createMapAsync(@NotNull() ObjectsCallback<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 tothe echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locallyand returns it.

        Parameters:
        callback - the callback to handle the result or error.

      • createMapAsync

        @NonBlocking() abstract void createMapAsync(@NotNull() Map<String, LiveMapValue> entries, @NotNull() ObjectsCallback<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(Dictentries?)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 tothe echoed MAP_CREATE operation, or if it wasn't received yet, the method creates a new object locallyusing 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() abstract void createCounterAsync(@NotNull() ObjectsCallback<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 tothe echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locallyusing the provided data and returns it.

        Parameters:
        callback - the callback to handle the result or error.

      • createCounterAsync

        @NonBlocking() abstract void createCounterAsync(@NotNull() Number initialValue, @NotNull() ObjectsCallback<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 tothe echoed COUNTER_CREATE operation, or if it wasn't received yet, the method creates a new object locallyusing the provided data and returns it.

        Parameters:
        initialValue - the initial value of the LiveCounter.
        callback - the callback to handle the result or error.