com.hivemq.spi.services

Interface ConnectionAttributeStore

@ThreadSafe
public interface ConnectionAttributeStore

Through this service a plugin 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 plugin 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 infomation that needs to be shared across callbacks.

For data that needs to be stored for the lifetime of a MQTT session (in case of persistent sessions), the AsyncSessionAttributeStore may be used as an alternative.

IMPORTANT: The store is not necessarily available if the instance was not acquired via a Callback parameter. If you e.g. receive a ClientData object from calling AsyncClientService.getClientData(String), it's required to call isAccessible() before using the ConnectionAttributeStore.

The ConnectionAttributeStore is thread safe.

Since:

3.3.0

Author:

Silvio Giebl

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Clears all connection attributes for the connected client.
com.google.common.base.Optional<byte[]>	get(String key) Retrieves the value of the connection attribute with the given key for the connected client.
com.google.common.base.Optional<com.google.common.collect.ImmutableMap<String,byte[]>>	getAll() Retrieves all connection attributes for the connected client.
com.google.common.base.Optional<String>	getAsString(String key) Retrieves the value of the connection attribute with the given key for the connected client as UTF-8 string.
com.google.common.base.Optional<String>	getAsString(String key, Charset charset) Retrieves the value of the connection attribute with the given key for the connected client as string with the given charset.
boolean	isAccessible() Returns whether this connection attribute store is accessible.
void	put(String key, byte[] value) Sets the given connection attribute for the connected client.
void	putAsString(String key, String value) Sets the given connection attribute as UTF-8 String representation for the connected client.
void	putAsString(String key, String value, Charset charset) Sets the given connection attribute as String representation for the connected client with a given charset.
com.google.common.base.Optional<byte[]>	remove(String key) Removes the connection attribute with the given key for the connected client.

Method Detail

put

void put(@NotNull
       String key,
       @NotNull
       byte[] 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

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

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

get

@NotNull
com.google.common.base.Optional<byte[]> get(@NotNull
                                                  String key)

Retrieves the value of the connection attribute with the given key for the connected client.

Parameters:

key - the key of the connection attribute.

Returns:

an Optional containing the value of the connection attribute if present.

getAsString

@NotNull
com.google.common.base.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.

getAsString

@NotNull
com.google.common.base.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.

getAll

@NotNull
com.google.common.base.Optional<com.google.common.collect.ImmutableMap<String,byte[]>> getAll()

Retrieves all connection attributes for the connected client.

Returns:

an Optional containing all connection attributes as a map of key and value pairs if present.

remove

@NotNull
com.google.common.base.Optional<byte[]> remove(@NotNull
                                                     String key)

Removes the connection attribute with the given key for the connected client.

Parameters:

key - the key of the connection attribute.

Returns:

an Optional containing the value of the removed connection attribute if it was present.

clear

void clear()

Clears all connection attributes for the connected client.

isAccessible

boolean isAccessible()

Returns whether this connection attribute store is accessible. The connection attribute store can only be accessed on the HiveMQ node, which the client is connected to. A cluster-wide alternative is the AsyncSessionAttributeStore.

The ConnectionAttributeStore is not necessarily available if the instance was not acquired via a Callback parameter. If you e.g. receive a ClientData object from calling AsyncClientService.getClientData(String), it's required to call isAccessible() before using the ConnectionAttributeStore.

Returns:

true if this connection attribute store is accessible, otherwise false