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.

For a complete list of message properties that can be set, see the PubSub+ Messaging APIs documentation for the appropriate PubSub+ 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.

To Set a Delivery Mode

PubSub+ Messaging API Use

PubSub+ Java RTO API

MessageHandle.setDeliveryMode(...)

PubSub+ C API

solClient_msg_setDeliveryMode(...)

PubSub+ .NET API

IMessage.DeliveryMode

PubSub+ JavaScript API and PubSub+ Node.js API

solace.Message.setDeliveryMode(...)

Related Samples

For an example of how to set the delivery mode for a message, see the DirectPubSub sample for the PubSub+ Java RTO API, PubSub+ C API, and PubSub+ .NET API, and the TopicPublisher sample for the PubSub+ JavaScript API and PubSub+ Node.js API.

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, see Topic Support & Syntax

A published Direct message is routed according to its set topic destination.

To Set a Message Destination

PubSub+ Messaging API Use

PubSub+ Java RTO API

MessageHandle.setDestination(...)

PubSub+ C API

solClient_msg_setDestination(...)

PubSub+ .NET API

IMessage.Destination

PubSub+ JavaScript API and PubSub+ Node.js API

solace.Message.setDestination(...)

Related Samples

For an example of how to publish a message to a topic, see the DirectPubSub sample for the PubSub+ Java RTO API, PubSub+ C API, and PubSub+ .NET API, and the TopicPublisher sample for the PubSub+ JavaScript API and PubSub+ Node.js API.

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.

To Set a Deliver-to-One Message Flag

PubSub+ Messaging API Use

PubSub+ Java RTO API

MessageHandle.setDeliverToOne(...)

PubSub+ C API

solClient_msg_setDeliverToOne(...)

PubSub+ .NET API

IMessage.DeliverToOne

PubSub+ JavaScript API and PubSub+ Node.js API

solace.Message.setDeliverToOne(...)

Related Samples

For an example of how to publish a deliver-to-one message, see the DTOPubSub sample for the appropriate PubSub+ 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, see Message Delivery Resources.

To set a COS Flag

PubSub+ Messaging API Use

PubSub+ Java RTO API

MessageHandle.setUserCos(...)

PubSub+ C API

solClient_msg_setClassOfService(...)

PubSub+ .NET API

IMessage.UserCos

PubSub+ JavaScript API and PubSub+ Node.js API

solace.Message.setUserCos(...)

Message Eliding Eligibility

The message eliding capabilities of 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, see Configuring Client Authentication.

To Enable Message Eligibility for Eliding

PubSub+ Messaging API Use

PubSub+ Java RTO API

MessageHandle.setElidingEligible(...)

PubSub+ C API

solClient_msg_setElidingEligible(...)

PubSub+ .NET API

IMessage.ElidingEligible(...)

PubSub+ JavaScript API and PubSub+ Node.js API

solace.Message.setElidingEligible(...)

Message Priority

Message priority is a guaranteed messaging feature. The event broker uses the message priority value to deliver messages in the appropriate order, meaning messages with a higher priority are sent before messages with a lower priority. The valid priority value range is 0-255, with 0 as the lowest priority and 255 as the highest priority, however the event broker treats all values above 9 as 9. The default message priority value is 4.

You can also apply a message priority value to direct messages that you publish to an event broker. The priority value of a direct message is respected only when both these conditions are met:

  • During delivery, the event broker promotes the message to guaranteed delivery.
  • You configure a corresponding queue or topic endpoint to respect message priority.

For more information, see Message Promotion and Demotion.

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.

To Enable Message Priority

PubSub+ Messaging API Use

PubSub+ Java RTO API

MessageHandle.setPriority(...)

PubSub+ C API

solClient_msg_setPriority(...)

PubSub+ .NET API

IMessage.Priority(...)

PubSub+ JavaScript API and PubSub+ Node.js API

solace.Message.setPriority(...)