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.
- Delivery Mode
- Destination
- Deliver-To-One Subscriber
- Class of Service
- Message Eliding Eligibility
- Message Priority
For a complete list of message properties that can be set, refer to the PubSub+ Messaging APIs documentation for the appropriate messaging API.
Delivery Mode
Each message to be published has a delivery mode. By default, a Direct delivery mode is used. For more information, see Message Delivery Modes.
PubSub+ Messaging API | Use |
---|---|
JCSMP |
Message.setDeliveryMode(...) |
Java RTO |
MessageHandle.setDeliveryMode(...) |
C |
solClient_msg_setDeliveryMode(...) |
.NET |
IMessage.DeliveryMode |
JavaScript and Node.js |
solace.Message.setDeliveryMode(...) |
Related Samples
For an example of how to set the delivery mode for a message, refer to the DirectPubSub
sample for the Java, Java RTO, C, and .NET APIs, and the TopicPublisher
sample for the JavaScript and Node.js APIs.
Destination
A Topic represents a logical destination. Clients can publish messages to a Topic destination. A client can also subscribe to a Topic, and when the event broker has a Topic subscription for the client that matches the message’s destination, the client can receive the message.
Topics can be grouped in hierarchies. Therefore Topic subscriptions, which support wildcards, can attract parts of the hierarchy for a client without subscribing to each possible combination of the hierarchy levels. For detailed information on the characters and syntax supported by event brokers, refer to Topic Support & Syntax
A published Direct message is routed according to its set Topic destination.
PubSub+ Messaging API | Use |
---|---|
JCSMP |
A destination is set on the send method used to publish the message. Refer to Sending Direct Messages or Sending Multiple Messages at a Time. |
Java RTO |
MessageHandle.setDestination(...) |
C |
solClient_msg_setDestination(...) |
.NET |
IMessage.Destination |
JavaScript and Node.js |
solace.Message.setDestination(...) |
Related Samples
For an example of how to publish a message to a Topic, refer to the DirectPubSub
sample for the Java, Java RTO, C, and .NET APIs, and the TopicPublisher
sample for the JavaScript and Node.js APIs.
Deliver-To-One Subscriber
When a Session connects to an event broker, you can use a Deliver-To-One (DTO) flag to send a Direct message to a single client, even though there could be a number of clients with appropriate subscriptions that are capable of receiving the message. A value of true
sets this on an outgoing message.
PubSub+ Messaging API | Use |
---|---|
JCSMP |
XMLMessage.setDeliverToOne(...) |
Java RTO |
MessageHandle.setDeliverToOne(...) |
C |
solClient_msg_setDeliverToOne(...) |
.NET |
IMessage.DeliverToOne |
JavaScript and Node.js |
solace.Message.setDeliverToOne(...) |
Related Samples
For an example of how to publish a Deliver-To-One message, refer to the DTOPubSub
sample for the appropriate messaging API.
Class of Service
You can apply a Class of Service (COS) level to Direct messages that are published to an event broker. The COS value specifies which of the per‑client priority queues on the event broker the messages are placed on, which can affect the rate at which they are sent out from the event broker to consuming clients. A COS level of 1 is the lowest class of service, and a COS level of 3 is the highest class of service. The default value is level 1.
You must set the COS value using the data structure provided by each API. Do not set the value directly using an integer.
For more information on egress per-client priority queues, refer to Message Delivery Resources.
PubSub+ Messaging API | Use |
---|---|
JCSMP |
Message.setCos(...) |
Java RTO |
MessageHandle.setUserCos(...) |
C |
solClient_msg_setClassOfService(...) |
.NET |
IMessage.UserCos |
JavaScript and Node.js |
solace.Message.setUserCos(...) |
Message Eliding Eligibility
The message eliding capabilities of Solace PubSub+ enable 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 there are slow consumers or where a slower message rate is required.
To use message eliding, the following steps are required:
- Published messages must be flagged as eligible for message eliding.
- A receiving 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. For information on how to configure client profiles and assign them to clients, refer to Configuring Client Authentication.
PubSub+ Messaging API | Use |
---|---|
JCSMP |
Message.setElidingEligible(...) |
Java RTO |
MessageHandle.setElidingEligible(...) |
C |
solClient_msg_setElidingEligible(...) |
.NET |
IMessage.ElidingEligible(...) |
JavaScript and Node.js |
solace.Message.setElidingEligible(...) |
Message Priority
You can apply a message priority value to Direct messages that are published to an event broker; however, the priority value is respected only if the message is promoted to guaranteed during delivery (see Message Promotion and Demotion) and a corresponding Queue or Topic Endpoint is configured to respect message priority. The event broker uses this value to deliver the message in the appropriate order, meaning messages with a higher priority are sent before messages with a lower priority. A value of 0 is the lowest priority, and a value of 255 is the highest priority (though the event broker treats all values higher than 9 as priority 9). The default value is 4.
When an endpoint is configured to enforce message priority, it increases the chance that duplicate messages will be delivered to a consuming client after it recovers from a connection failure.
PubSub+ Messaging API | Use |
---|---|
JCSMP |
Message.setPriority(...) |
Java RTO |
MessageHandle.setPriority(...) |
C |
solClient_msg_setPriority(...) |
.NET |
IMessage.Priority(...) |
JavaScript and Node.js |
solace.Message.setPriority(...) |