Chapter 25. Configuring Duplicate Message Detection

When a sender sends a message to another server, there can be a situation where the target server or the connection fails after sending the message, but before sending a response to the sender indicating that the process was successful. In these situations, it is very difficult for the sender to determine whether the message was sent successfully to the intended receiver. If the sender decides to resend the last message, it can result in a duplicate message being sent to the address.

You can configure duplicate message detection in JBoss EAP messaging so that your application does not need to provide the logic to filter duplicate messages.

25.1. Using Duplicate Message Detection for Sending Messages

To enable duplicate message detection for sent messages, you need to set the value of the org.apache.activemq.artemis.api.core.Message.HDR_DUPLICATE_DETECTION_ID property, which resolves to _AMQ_DUPL_ID, to a unique value. When the target server receives the messages, if the _AMQ_DUPL_ID property is set, it will check its memory cache to see if it has already received a message with the value of that header. If it has, then this message will be ignored. See Configuring the Duplicate ID Cache for more information.

The value of the _AMQ_DUPL_ID property can be of type byte[] or SimpleString if you are using the core API. If you are using JMS, it must be a String.

The following example shows how to set the property for core API.

SimpleString myUniqueID = "This is my unique id";   // Can use a UUID for this

ClientMessage message = session.createMessage(true);
message.setStringProperty(HDR_DUPLICATE_DETECTION_ID, myUniqueID);

The following example shows how to set the property for JMS clients.

String myUniqueID = "This is my unique id";   // Can use a UUID for this

Message jmsMessage = session.createMessage();
message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID);

Duplicate messages are not detected when they are sent within the same transaction using the HDR_DUPLICATE_DETECTION_ID property.

25.2. Configuring the Duplicate ID Cache

The server maintains caches of received values of the _AMQ_DUPL_ID property that is sent to each address. Each address maintains its own address cache.

The cache is fixed in terms of size. The maximum size of cache is configured using the id-cache-size attribute. The default value of this parameter is 20000 elements. If the cache has a maximum size of n elements, then the (n + 1)th ID stored will overwrite the element 0 in the cache. The value is set using the following management CLI command:


The caches can also be configured to persist to disk. This can be configured by setting the persist-id-cache attribute using the following management CLI command.


If this value is set to true, then each ID will be persisted to permanent storage as they are received. The default value for this parameter is true.


Set the size of the duplicate ID cache to a large size in order to ensure that resending of messages does not overwrite the previously sent messages stored in the cache.