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
All Methods Instance Methods Abstract Methods 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 aRateLimitExceededException
if the extension service rate limit was exceeded.- Parameters:
topic
- The topic.- Returns:
- A
CompletableFuture
which contains the retained message for the specific topic ornull
. - 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 aRateLimitExceededException
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 aRateLimitExceededException
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 aRateLimitExceededException
if the extension service rate limit was exceeded.CompletableFuture
fails with aDoNotImplementException
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 anIncompatibleHiveMQVersionException
if not all HiveMQ nodes in the cluster have at least version 4.4.0.CompletableFuture
fails with aRateLimitExceededException
if the extension service rate limit was exceeded.CompletableFuture
fails with aIterationFailedException
if the cluster topology changed during the iteration (e.g. a network-split, node leave or node join)- Parameters:
callback
- AnIterationCallback
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 theIterationContext
. - 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 anIncompatibleHiveMQVersionException
if not all HiveMQ nodes in the cluster have at least version 4.4.0.CompletableFuture
fails with aRateLimitExceededException
if the extension service rate limit was exceeded.CompletableFuture
fails with aIterationFailedException
if the cluster topology changed during the iteration (e.g. a network-split, node leave or node join)- Parameters:
callback
- AnIterationCallback
that is called for every returned result.callbackExecutor
- AnExecutor
that theIterationCallback
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 theIterationContext
. - Throws:
NullPointerException
- if the passed callback or callbackExecutor are null.- Since:
- 4.4.0, CE 2020.4
-
-