Package com.hivemq.extension.sdk.api.client.parameter

Interface ConnectionAttributeStore

@ThreadSafe
@DoNotImplement
public interface ConnectionAttributeStore
Through this service an extension can manage client connection attributes with the same lifetime as the connection.

The ConnectionAttributeStore is a key-value store for storing arbitrary data as additional information within the MQTT client connection. All data is stored in-memory and the maximum amount of a single key-value pair is 10 kilobytes.

A Connection Attribute is arbitrary binary data. For convenience purposes methods like putAsString(String, String) are available in case String representations should be stored. If complex objects are desired to be stored in the ConnectionAttributeStore, manual serialization and deserialization must be implemented by the extension developer.

The ConnectionAttributeStore is useful for storing temporary data or data that needs to be cleaned up automatically after the MQTT client disconnected. This store is also useful for storing temporary information that needs to be shared across callbacks.

The ConnectionAttributeStore is thread safe.

Since:
4.0.0, CE 2019.1

  • Method Details

    • put

      void put​(@NotNull String key, @NotNull ByteBuffer value)
      Sets the given connection attribute for the connected client.
      Parameters:
      key - The key of the connection attribute.
      value - The value of the connection attribute.
      Throws:
      LimitExceededException - A LimitExceededException is thrown when the size of the passed value exceeds the maximum allowed size of 10 kilobytes for the value.
      Since:
      4.0.0, CE 2019.1

    • putAsString

      void putAsString​(@NotNull String key, @NotNull String value)
      Sets the given connection attribute as UTF-8 String representation for the connected client.
      Parameters:
      key - The key of the connection attribute.
      value - The value of the connection attribute as a string.
      Throws:
      LimitExceededException - A LimitExceededException is thrown when the size of the passed value exceeds the maximum allowed size of 10 kilobytes for the value.
      Since:
      4.0.0, CE 2019.1

    • putAsString

      void putAsString​(@NotNull String key, @NotNull String value, @NotNull Charset charset)
      Sets the given connection attribute as String representation for the connected client with a given charset.
      Parameters:
      key - The key of the connection attribute.
      value - The value of the connection attribute as a string with the given charset.
      charset - The Charset of the given value.
      Throws:
      LimitExceededException - A LimitExceededException is thrown when the size of the passed value exceeds the maximum allowed size of 10 kilobytes for the value.
      Since:
      4.0.0, CE 2019.1

    • get

      @NotNull @NotNull Optional<@Immutable ByteBuffer> get​(@NotNull String key)
      Retrieves the value of the connection attribute with the given key for the connected client.

      The ByteBuffer returned by this method is read only and will throw a ReadOnlyBufferException if handled incorrectly.

      Parameters:
      key - The key of the connection attribute.
      Returns:
      An Optional containing the value of the connection attribute if present.
      Since:
      4.0.0, CE 2019.1

    • getAsString

      @NotNull @NotNull Optional<String> getAsString​(@NotNull String key)
      Retrieves the value of the connection attribute with the given key for the connected client as UTF-8 string.
      Parameters:
      key - The key of the connection attribute.
      Returns:
      An Optional containing the value of the connection attribute as a string if present.
      Since:
      4.0.0, CE 2019.1

    • getAsString

      @NotNull @NotNull Optional<String> getAsString​(@NotNull String key, @NotNull Charset charset)
      Retrieves the value of the connection attribute with the given key for the connected client as string with the given charset.
      Parameters:
      key - The key of the connection attribute.
      charset - The Charset of the value of the connection attribute.
      Returns:
      An Optional containing the value of the connection attribute as a string with the given charset if present.
      Since:
      4.0.0, CE 2019.1

    • getAll

      @NotNull @NotNull Optional<Map<String,​@Immutable ByteBuffer>> getAll()
      Retrieves all connection attributes for the connected client.

      The ByteBuffers returned by this method are read only and will throw a ReadOnlyBufferException if handled incorrectly.

      Returns:
      An Optional containing all connection attributes as a map of key and value pairs if present.
      Since:
      4.0.0, CE 2019.1

    • remove

      @NotNull @NotNull Optional<@Immutable ByteBuffer> remove​(@NotNull String key)
      Removes the connection attribute with the given key for the connected client.

      The ByteBuffer returned by this method is read only and will throw a ReadOnlyBufferException if handled incorrectly.

      Parameters:
      key - The key of the connection attribute.
      Returns:
      An Optional containing the value of the removed connection attribute if it was present.
      Since:
      4.0.0, CE 2019.1

    • clear

      void clear()
      Clears all connection attributes for the connected client.
      Since:
      4.0.0, CE 2019.1