Core Concepts

In this section we'll discuss several concepts at the core of messaging technology and Solace message routers:

Also, you can find discussions about the operational advantages of using the Solace message router's multi-protocol and cloud native capabilities here:


In application development terms, messaging, which is also commonly known as message-oriented middleware or just middleware, refers to technology that lets computer systems share information without requiring direct connections or awareness of one another's location.

Messaging is analogous to postal and shipping services. Just as you would hand your letters or packages to a carrier and trust that they will get to where you want them to go; and so it is with messaging, applications hand off information to a messaging system that routes it to whatever applications, analytics engines or user interfaces you’ve said you want it to get to. The analogy holds up fairly well when you consider different kinds of shipping and qualities of service (first class vs. bulk mail, ground vs. overnight, local vs. overseas, and so on) as different kinds of messaging are used for different kinds of interactions, such as publish/subscribe, request/reply and others that we'll take a look at in the sections that follow.

What does a Message look like? Fundamentally, a Message has three parts: Header, Properties and Body.


The Header is the part of the message used by the Solace Message Router for routing messages through the system. Some header fields, such as Destination and Delivery Mode, are required, while others are optional. For example, the reply-to topic is optional and is only needed for Request-Reply messaging where the Replier needs to know where to send its responses.


In addition to the header fields, application-specific properties can also be included as part of the message. These application-specified properties are unmodified by the broker and can be used to facilitate communication between applications. Some APIs define their own standard properties. For instance, JMS has defined properties such as JMSXUserID and JMSXAppID which can be used to identify the user or application sending the message. Besides API-defined standard properties, applications can also specify properties. An example of an application-specified property might be an Order ID an Order Management System uses as a unique identifier to track all messages related to a given purchase.


The body of a message is often called the payload or the attachment. It contains data in an application specified format and is transported unmodified by the Solace message router. The body is made up of raw binary data or structured data such as text, streams, maps, or otherwise. Regardless, Producers and Consumer must agree upon the payload format so that the data can be properly interpreted.

Message Delivery Modes

Solace message routers support the following different message delivery modes:

  • At most once delivery—Solace message routers provide two options: Direct and Non-Persistent message delivery. See details below for the differences.
  • At least once delivery—Solace message routers provide this through Persistent messaging. At Solace this is often called Guaranteed delivery.
  • Transacted delivery—Solace message routers support session based and XA transactions.


Direct messaging is meant for high-speed applications that can tolerate occasional message loss. Producers can publish messages to a topic, and when these messages are received by the Solace Message Router, they are delivered to Consumers with matching topic subscriptions. Direct messages are neither spooled on the Solace Message Router (that is, they are not persisted) for consuming clients nor acknowledged when received.

Learn More:


The Non-Persistent messaging delivery mode in Solace is used mostly to fulfill the requirements of the JMS specification. It is also used in message promotion and demotion, which is explained below. In general, it is not used directly by client applications when publishing.

Persistent (Guaranteed)

Persistent or Guaranteed messaging is combination of sending persistent messages with proper publish confirmation handling and means at least once delivery. Guaranteed messages are never lost. Guaranteed messaging can be looked at from two angles: the publish side and the receive side.

Guaranteed Message Publishing

When Persistent Messaging is used to send messages to a Solace message router, clients can publish to either a Solace queue or topic.

When these messages are received by the Solace message router, they are saved in the Solace message router message spool (that is, they are persisted) before they are acknowledged back to the producers. The acknowledgment is the confirmation to the publisher that the Solace message router accepts the message and it will not be lost.

Guaranteed Message Receiving

The messages are delivered to consuming clients that bind to the Solace endpoints containing the received messages. Messages are persisted on the Solace message router until they expire or the consuming client acknowledges the message indicating it has been consumed.

Learn More:

Message Promotion / Demotion and Message Delivery Modes

In the previous explanations of Direct and Persistent messages, both the producer and consumer in the examples wanted the same message delivery mode. This is the simplest scenario, but it is not a requirement. The Solace message router matches messages based on topics or queue names and routes these messages to interested consumers. So it is possible to use different message delivery modes for the producer and consumer and end up with a hybrid of Direct messaging and Persistent messaging.

Message promotion is the scenario where the producer sends Direct messages and the consumer receives these message from a Guaranteed Messaging endpoint. In this case the consumer will receive Non-Persistent Solace messages. This is a typical scenario in applications where there is a real-time publisher sending in events, and it is critical that this publisher never be back pressured. However, there are some consumers that would like to receive the data in the most fault-tolerant Persistent way. In this scenario they can receive the events using a queue endpoint with mapped topics. If the consumer application is ever offline, then messages will accumulate in the Queue Endpoint. The consumer application will not miss messages if it's offline or slow.

Message demotion is the scenario where the producer sends Persistent messages and there are consumers that want to receive these messages but can tolerate lost messages. These consumers can add a Topic Subscription matching these messages and receive them in real time as Direct messages. These consumers will never back pressure the publisher application, and if they go offline those consumers will simply miss messages. In summary, the producer application is sending mission critical data but some consumers of this data are not mission critical and should never be allowed to affect the publishers. Message demotion achieves this requirement.

From a consumer’s point of view, the only way to ensure fully guaranteed messaging is if the message is received from an Endpoint with a delivery mode of Persistent. That means it was sent persistently and received on a Guaranteed Messaging Endpoint. All other combinations are examples of at-most-once messaging and the Consumer will receive them as either Solace Direct or Non-Persistent messages.

The following is a summary table outlining message promotion and demotion in Solace message routers.

Delivery Mode of Published Message Received by Endpoint as… Received by a Client with a Matching Topic Subscription as…
Direct Non-Persistent Direct
Non-Persistent Non-Persistent Direct
Persistent Persistent Direct

Learn More:

Message Delivery Modes Terminology

Different protocols and APIs use different terminology to describe delivery modes. The following tables provides a summary across the various protocols supported by the Solace message router.

Message QoS Solace APIs JMS MQTT AMQP Solace REST
At most once delivery Direct (default) Non-Persistent QoS 0 (default)

Direct for publishers only

(Direct subscribers not supported)

At least once delivery Persistent Persistent QoS 1 Persisted Persistent (default)
Transacted Session Based Session + XA N/A N/A N/A

Message Models

Most messaging applications can be reduced to a series of interactions that adhere to one of the following core messaging models. The Point-to-Point, Publish-Subscribe, and Request-Reply Message Exchange Patterns are the building blocks for describing the manner in which applications interact.


With Point-to-Point messaging, messages sent by the Producer are to be processed by a single Consumer.

Non-Exclusive Consumption

An extension of the traditional Point-to-Point messaging is the addition of multiple consumers consuming from a shared channel or queue. The scale of the overall receiving application is increased by having multiple consumers, but each message is still only delivered to a single consumer.


With request-reply messaging, applications achieve two-way communication using separate point-to-point channels: one for the requests and another for the replies.

Request Reply Pattern

Publish – Subscribe

With publish-subscribe messaging, messages sent by the Producer are processed multiple times by different consumers. Each consumer receives its own copy of the message for processing.

Publish Subscribe Pattern

Solace Message Router Concepts

Solace message routers unify many kinds of data movement so companies can efficiently and cost-effectively move all of the information associated with better serving customers and making smarter decisions. Basically, they are multi-protocol message brokers and come in several form factors.

Message Router Appliances

Solace message router appliances offer greater capacity and performance with lower TCO and complexity than any other messaging middleware technology. Learn more here.

Solace Virtual Message Router

The Solace Virtual Message Router (VMR) is SolOS messaging technology that runs on general purpose processors instead of Solace purpose-built hardware. Learn more here or download the Solace VMR here.

Message VPNs

The Message VPN is a core feature of the Solace message router. It allows for many separate applications to share a single message router while still remaining independent and separated. In essence it enables virtualization of the Solace message router into many individual virtual message brokers.

Message VPNs allow for the segregation of topic space and messaging space by creating fully separate messaging domains. Message VPNs also group clients connecting to a network of Solace message routers, such that messages published within a particular group are only visible to clients that belong to that group. Each client connection is associated with a single Message VPN.

Message VPNs also allow scoping of resources such as message spool, queues, topics, connections.

Message VPNs

Learn More:


Applications or devices that connect to Solace message routers are represented as clients. A client on the router represents a single logical connection to the router that is capable of sending and/or receiving messages. To establish a client connection to a Solace message router, client applications or devices connect using a specific Client Username account.

As part of the connection process, a unique Client Name is required to identify the Client’s session. That is, the Client Name serves as a session name. If the Client application or device does not provide its own Client Name when creating its session, a unique Client Name is automatically generated by the Solace API. Note that while Client Names are unique within a given Message VPN, the same name may exist in multiple Message VPNs.

Once connected, Clients inherit a number of characteristics, behaviors, and permissions based on a Client Profile and an ACL Profile associated with that Client Username.

Client Connection

Client Username

Client Usernames are contained within a specific Message VPN. They are used by Client applications to authenticate with the Solace message router and may be used to make multiple Client connections. This lets applications horizontally scale without additional configuration on the Solace message router.

Each Client Username is associated with a Client Profile and an ACL profile. These profiles control properties and permissions of the connected Client and will be discussed later in this lesson.

Learn More:

Client Profile

Client Profiles are contained within a specific Message VPN and can be applied Client Usernames. Being able to share Client Profiles gives administrators the ability to manage large groups of Clients without having to make individual changes to each one.

Client Profiles control a number of behaviors and capabilities. For example, resource allocation such as the maximum number of Client connections per Client Username and the per-client transport queues are both controlled by the Client Profile. Other characteristics controlled by the Client Profile include tuning TCP connection parameters, enabling persistent messaging capabilities, and adjusting the point at which certain events will be triggered.

Learn More:

ACL Profiles

Similar to Client Profiles, ACL Profiles are contained within a specific Message VPN and can be applied to Client Usernames. This gives administrators the ability to control the entitlements for large groups of clients.

ACL Profiles consist of a few Access Control Lists which serve to either allow or restrict Client actions. The ACL configuration defines the Client’s ability to connect based on its IP address. It also defines to which topics the Client is allowed to publish or subscribe.

All of the ACL definitions have the same format in that they have a default behavior of either allow or disallow, and they have an exception list.

Learn More:

Endpoints / Queues

Guaranteed messages in Solace are stored in endpoints on the Solace message router. There are two types of endpoints; queues and topic endpoints. In most scenarios the queue endpoint is a superset of the topic endpoint and is the endpoint most commonly used. Topic endpoints are used by JMS (that is, durable topic subscriptions).


Queues on the Solace message router work very much like queues in all message queuing systems. Producers send guaranteed messages to the Solace message router. These messages are saved in the queue and delivered to consuming clients if they are online and connected. The consumer acknowledges the message once it has completed processing of the message, and it is then removed from the queue on the Solace message router. Queue objects are highly configurable with a variety of options to tailor their behavior to application needs.

Queues' lifecycles are determined by whether they are durable or non-durable. Durable queues remain around permanently until removed through configuration. They accumulate messages when clients are online or offline. When offline clients connect again, they receive all the messages that were accumulated while they were offline. Temporary queues follow the lifecycle of the client connection and are useful for ensuring message persistence while clients are online. If a client disconnects for a long period of time, the Solace message router will automatically remove the temporary queues. So messages will not accumulate while clients are offline.

Learn More:

Topic to Queue Mapping

In addition to spooling published Guaranteed messages that have a matching queue destination, it is possible to add one or more topic subscriptions to a durable queue so that Guaranteed messages published to those topics are also delivered to and spooled by the queue. This feature enables queues to participate equally in point-to-point and publish/subscribe messaging models, opening up a large number of interesting use cases.

As shown in the following figure, this allows a single message published to a topic to be delivered to a combination of topic endpoints, one or more queues, or even clients with matching Direct Messaging topic subscriptions.

Message Promotion/Demotion

Any Guaranteed messages published to topics that match subscriptions associated with queues are delivered to those queues. Error indications are returned to the publisher if the message cannot be delivered to one or more queues for any reason (that is, the feedback to the publisher is identical to that provided when the messages are published directly to the queues).

  • Topic subscription to queue mappings are applicable to both durable and non‑durable queues. Deletion of a queue for any reason results in the deletion of all topic subscription to queue mappings for that queue.

Learn More:

Solace API Concepts

The following section provides an overview of Solace API core concepts.


The messaging APIs use processing Contexts for organizing communication between an application and a Solace appliance. Contexts act as containers in which Sessions are created and Session-related events can be handled.

A Context encapsulates threads that drive network I/O and message delivery notification for the Sessions and Session components associated with that Context. For the Java API, one thread is used for I/O and another for notification. For the Java RTO, C, and .NET APIs, a single thread is used for both I/O and for notification. The life cycle of a Context‑owned thread is bound to the life cycle of the Context.

API Entities

Learn More:



A Session creates a single, client connection to a Solace message router for sending and receiving messages. Sessions also allow applications to add and remove subscriptions.


Learn More:



A Consumer Flow is an API concept that allows applications to receive Guaranteed messages from an endpoint, such as a Queue. It is created by a Solace session.

Learn More:

Guaranteed Message Flows