Setting Message Properties

The following sections discuss some important message properties that can be set for messages to be published. These properties can affect how messages are routed.

Time-to-Live

To ensure that stale messages are not consumed, you can set a Time‑To-Live (TTL) value (in milliseconds) for each Guaranteed message published by a producer. The TTL value is ignored for non‑durable endpoints when using Direct Transport.

Respecting TTL

If destination queues or topic endpoints are configured to respect message TTLs, when received messages’ TTLs have passed, they are either discarded by the endpoint, or, if the messages are eligible for a Dead Message Queue (DMQ), they are moved to a DMQ provisioned on the event broker.

The respect-ttl property value set at the connectionFactory level can be overridden through the InitialContext environment using SupportedProperty.SOLACE_JMS_RESPECT_TIME_TO_LIVE.

Setting TTL

You can set a TTL value for messages in the following ways:

  • Call MessageProducer.setTimeToLive(long timeToLive) to set a default TTL value for all messages to be published by the MessageProducer. (A value of 0 means that the messages never expire.)
  • After acquiring a MessageProducer, a TTL value can be passed in when you call either one of the following methods to publish the message:
    • send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive) or send(Message message, int deliveryMode, int priority, long timeToLive)

    The TTL value set through these methods overrides any set at the MessageProducer level.

Moving messages to a DMQ

If you want to move messages with expired TTL values to a provisioned DMQ, the endpoints must be configured to respect the messages’ TTL values:

  • If you are using SolAdmin to provision endpoints, you must enable the Respect TTL check box and create a new queue or subscription name (that is, endpoint).
  • If you want to dynamically create endpoints, the connectionFactory used should also be configured to respect TTLs. Therefore, when using SolAdmin to create a connectionFactory, enable the Respect TTL check box. When using the CLI to create the connectionFactory, set respect‑ttl to true. For more information, refer to Solace JNDI Objects.

Dead Message Queue Eligibility

Guaranteed messages that have exceeded their TTL, or maximum number of redelivery attempts, can be moved from a durable Queue or a Topic Endpoint to a DMQ, instead of being discarded if those messages are flagged as being DMQ-eligible. A DMQ is just a durable queue that has been assigned to serve as the DMQ for another durable endpoint. For more information, refer to Configuring Dead Message Queues.

You can dynamically create a queue with the name #DEAD_MSG_QUEUE through the JMS API (refer to Creating Queues), or provision one through CLI or SolAdmin.

You can flag published messages as DMQ eligible on a per-message basis, or you can enable message eligibility for DMQs on a Connection Factory basis so that all messages published by Producers using that Connection Factory are DMQ-eligible.

  • To flag individual messages

    • Set the SOLACE_JMS_PROP_DEAD_MSG_QUEUE_ELIGIBLE property to true for each message.

  • To flag messages at the Connection Factory level

    • Use SolAdmin or the CLI to enable the default-dmq-eligible property.

For more information on this message property, refer to Dead Message Queue Eligible.

Eliding Eligibility

The message eliding capabilities of Solace PubSub+ enables client applications to only receive the most current messages published to topics that they subscribe to, at a rate that they can manage. Using message eliding can be useful in situations where a slower message rate is required or where there are slow consumers.

To use message eliding, the following steps are required:

  • A consuming client application must be assigned a client profile through its client username that permits it to use message eliding. The client profile also sets a rate to control the delay interval at which a new eliding-eligible message elides a previous version that is queued for delivery to the client.
  • Published messages must be flagged as eligible for message eliding.
  • You can flag published messages as eligible for message eliding on a per‑message basis, or you can enable message eliding eligibility on a Connection Factory basis so that all messages published by Producers using that Connection Factory are eliding-eligible.
    • To flag individual messages, set the SOLACE_JMS_PROP_ELIDING_ELIGIBLE property to true for each message.
    • To flag messages at the Connection Factory level, use SolAdmin or the CLI to enable the default-eliding-eligible property.

For more information on this message property, refer to Eliding Eligible.

Partition Key

You can set a partition key in your message to take advantage of partitioned queues. Partitioned queues allow you to easily scale the number of consumer applications in your event mesh, while maintaining the message sequence for all published messages with the same partition key. PubSub+ event brokers ensure that all related events are delivered to the same consumer in the correct sequence and also re-balance the event stream when you add or remove consumers. For more information see Partitioned Queues.

To set the partition key, use the setStringProperty(name,value) method to set a name-value pair on a JMS API message.

  • name—The constant SupportedProperty.JMSX_GROUP_ID or the string value JMSXGroupID.

  • value—A string representing the value of your partition key. Client applications set the value at publish time.

The following example sets the partition key value to Group-0:

Message message = message.setStringProperty("JMSXGroupID", "Group-0");
// Or:
Message message.setStringProperty(SupportedProperty.JMSX_GROUP_ID, "Group-0");

End-to-End Payload Compression

The PubSub+ JMS API can perform message payload compression to allow for:

  • faster message throughput

  • reduced bandwidth usage

  • improved performance in your applications

While message payload compression creates more work for individual PubSub+ APIs, it enables faster aggregate rates of message publishing and message receiving. The PubSub+ event broker offers transport message compression that compresses the entire message, see Streaming Compressed Connections. However, when you send and receive large messages, compressing the entire message creates a lot of work for the event broker, which can result in slower throughput. If your application needs to send and receive large messages, we recommend you use message payload compression to improve performance.

  1. Considerations When Compressing Message Payloads

  2. Compressing Message Payloads in the PubSub+ JMS API

Considerations When Compressing Message Payloads

The following sections explain what you should be aware of when you compress message payloads with the PubSub+ Messaging APIs.

Use only one form of message compression

We recommend you only use one form of compression, either Streaming Compressed Connections through the event broker or end-to-end payload compression through the APIs. Compressing the same message multiple times can waste resources and usually does not result in smaller message sizes.

Do not use end-to-end payload compression to bypass the maximum message size supported on a PubSub+ event broker

Do not pass a payload with a size that exceeds the maximum message size supported on the event brokers. We recommend that you reduce the size of your payload to ensure it's smaller than the maximum message size prior to using payload compression. For more information about the maximum message sizes, see Sending Messages Larger Than the Event Broker's Maximum Message Size.

Do not use end-to-end payload compression with small messages

End-to-end payload compression works best with messages that are a few megabytes in size. Solace does not recommend using message payload compression with small messages, because end-to-end payload compression can actually increase the size of small messages.

Upgrade your publisher and receiver applications

Receiver applications automatically decompress any compressed message payloads only if the API supports message payload compression and is updated to the minimum supported version. If your receiver application does not support message payload compression, this can cause potential errors or exceptions. Make sure you update your publisher and receiver applications to the minimum supported versions for payload compression. For version support information, see Feature Support in PubSub+ Messaging APIs.

End-to-end payload compression limitations

End-to-end payload compression does not currently support PubSub+ Cache.

End-to-end payload compression is not compatible with:

  • SolCache

  • Non-SMF protocols, such as AMQP, HTTP, Kafka, and MQTT

If your applications use any of the above, we recommend that you do not use end-to-end payload compression.

Compressing Message Payloads in the PubSub+ JMS API

Your publisher application can compress the binary payload of a message before you publish it. To compress a message payload, you must set the JMS payload compression level, which tells the API you want message compression enabled. The payload compression level property can be set to an integer from 0-9:

  • 0—Payload compression is disabled. This is the default setting.

  • 1 - 9—Payload compression is enabled. 1 is the lowest level of compression with the fastest data throughput, and 9 is the highest level of compression with the slowest data throughput.

Your payload compression level should be adjusted according to your network and performance requirements. The following code snippets show the two ways you can enable message payload compression:

  1. Set SOLACE_JMS_PAYLOAD_COMPRESSION_LEVEL in the initial context:
    Hashtable env = new Hashtable();
//...
env.put(SupportedProperty.SOLACE_JMS_PAYLOAD_COMPRESSION_LEVEL, 9);
InitialContext initialContext = new InitialContext(env);

  2. Set SOLACE_JMS_PayloadCompressionLevel in a JNDI property file:

    Solace_JMS_PayloadCompressionLevel=9

Message payload compression only applies to binary message attachments. If you want to compress the payload of a TextMessage, you need to set SOLACE_JMS_PROP_ISXML to false, which tells the API to put the text in the binary attachment of the message:

TextMessage msg = session.createTextMessage("My text message"));
msg.setBooleanProperty(SupportedProperty.SOLACE_JMS_PROP_ISXML, false);

Because the connection factory has priority, the value set via JNDI property file or initial context is only used when the event broker does not send a value to JMS. For example, if you are using an event broker version that does not support the message compression JNDI property, then the value for message compression will default to what is specified in the initial context or property file, as the broker itself won't provide a value for it.