RabbitMQ AMQP.BasicProperties.Builder values

Question

In the RabbitMQ/AMQP Java client, you can create an AMQP.BasicProperties.Builder, and use it to build() an instance of AMQP.BasicProperties. This built properties instance can then be used for all sorts of important things. There are lots of "builder"-style methods available on this builder class:

BasicProperties.Builder propsBuilder = new BasicProperties.Builder();
propsBuilder
    .appId(???)
    .clusterId(???)
    .contentEncoding(???)
    .contentType(???)
    .correlationId(???)
    .deliveryMode(2)
    .expiration(???)
    .headers(???)
    .messageId(???)
    .priority(???)
    .replyTo(???)
    .timestamp(???)
    .type(???)
    .userId(???);

I'm looking for what fields these builer methods help "build-up", and most importantly, what valid values exist for each field. For instance, what is a clusterId, and what are its valid values? What is type, and what are its valid values? Etc.

I have spent all morning scouring:

• The Java client documentation; and
• The Javadocs; and
• The RabbitMQ full reference guide; and
• The AMQP specification

In all these docs, I cannot find clear definitions (besides some vague explanation of what priority, contentEncoding and deliveryMode are) of what each of these fields are, and what their valid values are. Does anybody know? More importantly, does anybody know where these are even documented? Thanks in advance!

Answer 1

Usually I use very simple approach to memorize something. I will provide all details below, but here is a simple picture of BasicProperties field and values. I've also tried to properly highlight queue/server and application context.

If you want me to enhance it a bit - just drop a small comment. What I really want is to provide some visual key and simplify understanding.

High-level description (source 1, source 2):

Please note Clust ID has been deprecated, so I will exclude it.

• Application ID - Identifier of the application that produced the message.
  • Context: application use
  • Value: Can be any string.
• Content Encoding - Message content encoding
  • Context: application use
  • Value: MIME content encoding (e.g. gzip)
• Content Type - Message content type
  • Context: application use
  • Value: MIME content type (e.g. application/json)
• Correlation ID - Message correlated to this one, e.g. what request this message is a reply to. Applications are encouraged to use this attribute instead of putting this information into the message payload.
  • Context: application use
  • Value: any value
• Delivery mode - Should the message be persisted to disk?
  • Context: queue implementation use
  • Value: non-persistent (1) or persistent (2)
• Expiration - Expiration time after which the message will be deleted. The value of the expiration field describes the TTL period in milliseconds. Please see details below.
  • Context: queue implementation use
• Headers - Arbitrary application-specific message headers.
  • Context: application use
• Message ID - Message identifier as a string. If applications need to identify messages, it is recommended that they use this attribute instead of putting it into the message payload.
  • Context: application use
  • Value: any value
• Priority - Message priority.
  • Context: queue implementation use
  • Values: 0 to 9
• ReplyTo - Queue name other apps should send the response to. Commonly used to name a reply queue (or any other identifier that helps a consumer application to direct its response). Applications are encouraged to use this attribute instead of putting this information into the message payload.
  • Context: application use
  • Value: any value
• Time-stamp - Timestamp of the moment when message was sent.
  • Context: application use
  • Value: Seconds since the Epoch.
• Type - Message type, e.g. what type of event or command this message represents. Recommended to be used by applications instead of including this information into the message payload.
  • Context: application use
  • Value: Can be any string.
• User ID - Optional user ID. Verified by RabbitMQ against the actual connection username.
  • Context: queue implementation use
  • Value: Should be authenticated user.

BTW, I've finally managed to review latest sever code (rabbitmq-server-3.1.5), there is an example in rabbit_stomp_test_util.erl:

                content_type     = <<"text/plain">>,
                content_encoding = <<"UTF-8">>,
                delivery_mode    = 2,
                priority         = 1,
                correlation_id   = <<"123">>,
                reply_to         = <<"something">>,
                expiration       = <<"my-expiration">>,
                message_id       = <<"M123">>,
                timestamp        = 123456,
                type             = <<"freshly-squeezed">>,
                user_id          = <<"joe">>,
                app_id           = <<"joe's app">>,
                headers          = [{<<"str">>, longstr, <<"foo">>},
                                    {<<"int">>, longstr, <<"123">>}]

Good to know somebody wants to know all the details. Because it is much better to use well-known message attributes when possible instead of placing information in the message body. BTW, basic message properties are far from being clear and useful. I would say it is better to use a custom one.

Good example (source)

Update - Expiration field

Important note: expiration belongs to queue context. So message might be dropped by the servers.

README says the following:

expiration is a shortstr; since RabbitMQ will expect this to be an encoded string, we translate a ttl to the string representation of its integer value.

Sources:

• Additional source 1
• Additional source 2