Package io.ably.lib.objects

Interface LiveObjects

public interface LiveObjects
The LiveObjects 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 live 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(@NotNull @NotNull LiveMap liveMap)
      Creates a new LiveMap based on an existing LiveMap. 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:
      liveMap - the existing LiveMap to base the new LiveMap on.
      Returns:
      the newly created LiveMap instance.

    • createMap

      @Blocking @NotNull @NotNull LiveMap createMap(@NotNull @NotNull LiveCounter liveCounter)
      Creates a new LiveMap based on a LiveCounter. 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:
      liveCounter - the LiveCounter to base the new LiveMap on.
      Returns:
      the newly created LiveMap instance.

    • createMap

      @Blocking @NotNull @NotNull LiveMap createMap(@NotNull @NotNull Map<String,Object> map)
      Creates a new LiveMap based on a standard Java Map. 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:
      map - the Java Map to base the new LiveMap on.
      Returns:
      the newly created LiveMap instance.

    • createCounter

      @Blocking @NotNull @NotNull LiveCounter createCounter(@NotNull @NotNull Long 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 Callback<@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 LiveMap liveMap, @NotNull @NotNull Callback<@NotNull LiveMap> callback)
      Asynchronously creates a new LiveMap based on an existing LiveMap. 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:
      liveMap - the existing LiveMap to base the new LiveMap on.
      callback - the callback to handle the result or error.

    • createMapAsync

      @NonBlocking void createMapAsync(@NotNull @NotNull LiveCounter liveCounter, @NotNull @NotNull Callback<@NotNull LiveMap> callback)
      Asynchronously creates a new LiveMap based on a LiveCounter. 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:
      liveCounter - the LiveCounter to base the new LiveMap on.
      callback - the callback to handle the result or error.

    • createMapAsync

      @NonBlocking void createMapAsync(@NotNull @NotNull Map<String,Object> map, @NotNull @NotNull Callback<@NotNull LiveMap> callback)
      Asynchronously creates a new LiveMap based on a standard Java Map. 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:
      map - the Java Map to base the new LiveMap on.
      callback - the callback to handle the result or error.

    • createCounterAsync

      @NonBlocking void createCounterAsync(@NotNull @NotNull Long initialValue, @NotNull @NotNull Callback<@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.