Package io.ably.lib.objects

Interface LiveMap

public interface LiveMap
The LiveMap interface provides methods to interact with a live, real-time map structure. It supports both synchronous and asynchronous operations for managing key-value pairs.

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull @Unmodifiable Iterable<Map.Entry<String,Object>>
    entries()
    Retrieves all entries (key-value pairs) in the map.
    @Nullable Object
    get(@NotNull String keyName)
    Retrieves the value associated with the specified key.
    @NotNull @Unmodifiable Iterable<String>
    keys()
    Retrieves all keys in the map.
    void
    remove(@NotNull String keyName)
    Removes the specified key and its associated value from the map.
    void
    removeAsync(@NotNull String keyName, @NotNull Callback<Void> callback)
    Asynchronously removes the specified key and its associated value from the map.
    void
    set(@NotNull String keyName, @NotNull Object value)
    Sets the specified key to the given value in the map.
    void
    setAsync(@NotNull String keyName, @NotNull Object value, @NotNull Callback<Void> callback)
    Asynchronously sets the specified key to the given value in the map.
    @NotNull Long
    size()
    Retrieves the number of entries in the map.
    @NotNull @Unmodifiable Iterable<Object>
    values()
    Retrieves all values in the map.

  • Method Details

    • get

      @Nullable @Nullable Object get(@NotNull @NotNull String keyName)
      Retrieves the value associated with the specified key. If this map object is tombstoned (deleted), `undefined` is returned. If no entry is associated with the specified key, `undefined` is returned. If map entry is tombstoned (deleted), `undefined` is returned. If the value associated with the provided key is an objectId string of another LiveObject, a reference to that LiveObject is returned, provided it exists in the local pool and is not tombstoned. Otherwise, `undefined` is returned. If the value is not an objectId, then that value is returned.
      Parameters:
      keyName - the key whose associated value is to be returned.
      Returns:
      the value associated with the specified key, or null if the key does not exist.

    • entries

      @NotNull @NotNull @Unmodifiable Iterable<Map.Entry<String,Object>> entries()
      Retrieves all entries (key-value pairs) in the map.
      Returns:
      an iterable collection of all entries in the map.

    • keys

      @NotNull @NotNull @Unmodifiable Iterable<String> keys()
      Retrieves all keys in the map.
      Returns:
      an iterable collection of all keys in the map.

    • values

      @NotNull @NotNull @Unmodifiable Iterable<Object> values()
      Retrieves all values in the map.
      Returns:
      an iterable collection of all values in the map.

    • set

      @Blocking void set(@NotNull @NotNull String keyName, @NotNull @NotNull Object value)
      Sets the specified key to the given value in the map. Send a MAP_SET operation to the realtime system to set a key on this LiveMap object to a specified value. This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when the published MAP_SET operation is echoed back to the client and applied to the object following the regular operation application procedure.
      Parameters:
      keyName - the key to be set.
      value - the value to be associated with the key.

    • remove

      @Blocking void remove(@NotNull @NotNull String keyName)
      Removes the specified key and its associated value from the map. Send a MAP_REMOVE operation to the realtime system to tombstone a key on this LiveMap object. This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when the published MAP_REMOVE operation is echoed back to the client and applied to the object following the regular operation application procedure.
      Parameters:
      keyName - the key to be removed.

    • size

      @Contract(pure=true) @NotNull @NotNull Long size()
      Retrieves the number of entries in the map.
      Returns:
      the size of the map.

    • setAsync

      @NonBlocking void setAsync(@NotNull @NotNull String keyName, @NotNull @NotNull Object value, @NotNull @NotNull Callback<Void> callback)
      Asynchronously sets the specified key to the given value in the map. Send a MAP_SET operation to the realtime system to set a key on this LiveMap object to a specified value. This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when the published MAP_SET operation is echoed back to the client and applied to the object following the regular operation application procedure.
      Parameters:
      keyName - the key to be set.
      value - the value to be associated with the key.
      callback - the callback to handle the result or any errors.

    • removeAsync

      @NonBlocking void removeAsync(@NotNull @NotNull String keyName, @NotNull @NotNull Callback<Void> callback)
      Asynchronously removes the specified key and its associated value from the map. Send a MAP_REMOVE operation to the realtime system to tombstone a key on this LiveMap object. This does not modify the underlying data of this LiveMap object. Instead, the change will be applied when the published MAP_REMOVE operation is echoed back to the client and applied to the object following the regular operation application procedure.
      Parameters:
      keyName - the key to be removed.
      callback - the callback to handle the result or any errors.