Package com.hivemq.extension.sdk.api.services.publish

Interface RetainedMessageStore

@DoNotImplement
public interface RetainedMessageStore

The retained message store allows the management of retained messages from within extensions.

Since:

4.0.0, CE 2019.1

Method Summary

Modifier and Type	Method	Description
@NotNull CompletableFuture<Void>	addOrReplace(@NotNull RetainedPublish retainedPublish)	This method adds or replaces a retained message.
@NotNull CompletableFuture<Void>	clear()	Removes all retained messages from the message store.
@NotNull CompletableFuture<Optional<RetainedPublish>>	getRetainedMessage(@NotNull String topic)	Get the retained message for a topic, if it exist.
@NotNull CompletableFuture<Void>	iterateAllRetainedMessages(@NotNull IterationCallback<RetainedPublish> callback)	Iterate over all retained messages in the HiveMQ cluster.
@NotNull CompletableFuture<Void>	iterateAllRetainedMessages(@NotNull IterationCallback<RetainedPublish> callback, @NotNull Executor callbackExecutor)	Iterate over all retained messages in the HiveMQ cluster.
@NotNull CompletableFuture<Void>	remove(@NotNull String topic)	Removes the retained message for the given topic.

Method Detail

getRetainedMessage

@NotNull CompletableFuture<Optional<RetainedPublish>> getRetainedMessage(@NotNull String topic)

Get the retained message for a topic, if it exist.

CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

Parameters:

topic - The topic.

Returns:

A CompletableFuture which contains the retained message for the specific topic or null.

Since:

4.0.0, CE 2019.1

remove

@NotNull CompletableFuture<Void> remove(@NotNull String topic)

Removes the retained message for the given topic. If there isn't any retained message on the topic yet, nothing will happen.

CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

Parameters:

topic - The topic from which the retained message should be removed.

Returns:

A CompletableFuture which returns after removal.

Since:

4.0.0, CE 2019.1

clear

@NotNull CompletableFuture<Void> clear()

Removes all retained messages from the message store.

CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

Returns:

A CompletableFuture which returns after removal.

Since:

4.0.0, CE 2019.1

addOrReplace

@NotNull CompletableFuture<Void> addOrReplace(@NotNull RetainedPublish retainedPublish)

This method adds or replaces a retained message.

CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

CompletableFuture fails with a DoNotImplementException if the retained publish is implemented by the extension.

Parameters:

retainedPublish - Retained publish which should be added or replaced.

Returns:

A CompletableFuture which returns after adding or replacing the retained publish.

Since:

4.0.0, CE 2019.1

iterateAllRetainedMessages

@NotNull CompletableFuture<Void> iterateAllRetainedMessages(@NotNull IterationCallback<RetainedPublish> callback)

Iterate over all retained messages in the HiveMQ cluster.

The callback is called once for each retained message. Passed to each execution of the callback is all information about the retained message, such as its payload and its metadata. Retained messages that have exceeded their message expiry interval are not included.

The callback is executed in the ManagedExtensionExecutorService per default. Use the overloaded methods to pass a custom executor for the callback. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection (thread-safe), as the callback might be executed in another thread as the calling thread of this method.

The results are not sorted in any way, no ordering of any kind is guaranteed.

CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.4.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded. CompletableFuture fails with a IterationFailedException if the cluster topology changed during the iteration (e.g. a network-split, node leave or node join)

Parameters:

callback - An IterationCallback that is called for every returned result.

Returns:

A CompletableFuture that is completed after all iterations are executed, no match is found or the iteration is aborted manually with the IterationContext.

Throws:

NullPointerException - if the passed callback is null.

Since:

4.4.0, CE 2020.4

iterateAllRetainedMessages

@NotNull CompletableFuture<Void> iterateAllRetainedMessages(@NotNull IterationCallback<RetainedPublish> callback,
                                                            @NotNull Executor callbackExecutor)

Iterate over all retained messages in the HiveMQ cluster.

The callback is called once for each retained message. Passed to each execution of the callback is all information about the retained message, such as its payload and its metadata. Retained messages that have exceeded their message expiry interval are not included.

The callback is executed in the passed Executor. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection (thread-safe), as the callback might be executed in another thread as the calling thread of this method.

The results are not sorted in any way, no ordering of any kind is guaranteed.

CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.4.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded. CompletableFuture fails with a IterationFailedException if the cluster topology changed during the iteration (e.g. a network-split, node leave or node join)

Parameters:

callback - An IterationCallback that is called for every returned result.

callbackExecutor - An Executor that the IterationCallback is executed in.

Returns:

A CompletableFuture that is completed after all iterations are executed, no match is found or the iteration is aborted manually with the IterationContext.

Throws:

NullPointerException - if the passed callback or callbackExecutor are null.

Since:

4.4.0, CE 2020.4