Persistence with Queues
9 Minute Read
This tutorial builds on the basic concepts introduced in the publish/subscribe tutorial, and will show you how to send and receive Persistent (Guaranteed) Messages from a Solace message router queue in a point to point fashion.
Assumptions
This tutorial assumes the following:
-
You are familiar with Solace core concepts.
-
You have access to Solace messaging with the following configuration details:
- Connectivity information for a Solace message-VPN
- Enabled client username and password
One simple way to get access to Solace messaging quickly is to create a messaging service in Solace Cloud as outlined here. You can find other ways to get access to Solace messaging below.
Goals
The goal of this tutorial is to understand the following:
- How to send a guaranteed message to a Solace queue
- How to bind to this queue and receive a guaranteed message
Get Solace Messaging
This tutorial requires access Solace PubSub+ messaging and requires that you know several connectivity properties about your Solace messaging. Specifically you need to know the following:
Resources | Value | Description |
---|---|---|
Host | String | This is the address clients use when connecting to the PubSub+ messaging to send and receive messages. (Format: DNS_NAME:Port or IP:Port ) |
Message VPN | String | The PubSub+ message router Message VPN that this client should connect to. |
Client Username | String | The client username. (See Notes below) |
Client Password | String | The client password. (See Notes below) |
There are several ways you can get access to PubSub+ Messaging and find these required properties.
Option 1: Use PubSub+ Cloud
-
Follow these instructions to quickly spin up a cloud-based PubSub+ messaging service for your applications.
-
The messaging connectivity information is found in the service details in the connectivity tab (shown below). You will need:
- Host:Port (use the SMF URI)
- Message VPN
- Client Username
- Client Password
Option 2: Start a PubSub+ Software
-
Follow these instructions to start the PubSub+ Software in leading Clouds, Container Platforms or Hypervisors. The tutorials outline where to download and how to install the PubSub+ Software.
-
The messaging connectivity information are the following:
-
Host: <public_ip> (IP address assigned to the VMR in tutorial instructions)
-
Message VPN: default
-
Client Username: sampleUser (can be any value)
-
Client Password: samplePassword (can be any value)
Note: By default, the PubSub+ Software "default" message VPN has authentication disabled.
-
Option 3: Get access to a PubSub+ Appliance
-
Contact your PubSub+ appliance administrators and obtain the following:
- A PubSub+ Message-VPN where you can produce and consume direct and persistent messages
- The host name or IP address of the Solace appliance hosting your Message-VPN
- A username and password to access the Solace appliance
Obtaining the Solace PubSub+ API
The repository where this tutorial reside already comes with C API library version 7.7.1.4. However, you should always check for any newer version for download here. The C API is distributed as a gzipped tar file for all supported platform. To update to a newer version of the API, please ensure that the existing core library components are appropriately replaced by the newer components.
Prerequisite Creating a Durable Queue on the Solace message router
A difference with the publish/subscribe tutorial is that for guaranteed messaging a physical endpoint resource – a durable queue, associated with the queue destination – needs to be created on the Solace message router, which will persist the messages until consumed.
You can use Solace PubSub+ Manager, SEMP or CLI to create a durable queue. This tutorial assumes that the queue named tutorial/queue
has been created. Ensure the queue is enabled for both Incoming and Outgoing messages and set the Permission to at least "Consume".
Loading and Initializing the Solace JavaScript API
To load the Solace Web Messaging API for JavaScript on your HTML page simply include the solclient.js
file from the distribution.
<head>
<script src="../../../lib/solclient.js"></script>
</head>
Use the debug version of the API in lib/solclient-debug.js
file instead, if you’re planning to see console log messages and/or debug it.
<head>
<script src="../../../lib/solclient-debug.js"></script>
</head>
Then initialize the SolclientFactory
, which is the first entry point to the API. Add the following to initialize with the latest version10
behavior profile to run with the default property values that Solace recommends at the time of the version 10 release.
var factoryProps = new solace.SolclientFactoryProperties();
factoryProps.profile = solace.SolclientFactoryProfiles.version10;
solace.SolclientFactory.init(factoryProps);
If the debug version of the API has been loaded the required level of logging can be set like so:
solace.SolclientFactory.setLogLevel(solace.LogLevel.DEBUG);
Implementing Guaranteed Messaging
For guaranteed messaging, we will use a "producer" to send messages to and a "consumer" to receive messages from a durable queue configured on the Solace message router. The producer will use a MessagePublisher
embedded into the Session
object to send, and the consumer will bind to a queue destination and use a MessageConsumer
object to receive guaranteed messages.
Connecting to the Solace message router
Similar to the publish/subscribe tutorial, an application must connect a Solace session. The Solace session is the basis for all client communication with the Solace message router.
The solace.SolclientFactory
is used to create a Solace Session
from SessionProperties
.
The following is an example of a session creating and connecting to the Solace message router for the producer.
Compared to the publish/subscribe tutorial, here it is not required to specify a message event listener for the Session
object. Guaranteed messages are delivered to event listeners defined for the MessageConsumer
object instead.
// create session
producer.session = solace.SolclientFactory.createSession({
// solace.SessionProperties
url: hosturl,
vpnName: vpn,
userName: username,
password: pass,
});
// define session event listeners
/*...see section Session Events...*/
// connect the session
try {
producer.session.connect();
} catch (error) {
producer.log(error.toString());
}
At this point your Node.js application is connected as a client to the Solace message router. You can use PubSub+ Manager to view this client connection and related details.
Session Events
The Solace Node.js API communicates changes in status and results of connect calls through emitting session events with certain event names.
It is necessary to wire your application logic to session events through listeners to take appropriate action. The most important session events are:
SessionEventCode.UP_NOTICE
: session has been successfully connected to the Solace message routerSessionEventCode.CONNECT_FAILED_ERROR
: unable to connect to the Solace message routerSessionEventCode.DISCONNECTED
: session has been disconnected from the Solace message router
This is how event listeners can be defined in the sample producer, and the sample consumer is very similar:
// define session event listeners
producer.session.on(solace.SessionEventCode.UP_NOTICE, function (sessionEvent) {
producer.log('=== Successfully connected and ready to send messages. ===');
producer.sendMessage();
producer.exit();
});
producer.session.on(solace.SessionEventCode.CONNECT_FAILED_ERROR, function (sessionEvent) {
producer.log('Connection failed to the message router: ' + sessionEvent.infoStr +
' - check correct parameter values and connectivity!');
});
producer.session.on(solace.SessionEventCode.DISCONNECTED, function (sessionEvent) {
producer.log('Disconnected.');
if (producer.session !== null) {
producer.session.dispose();
producer.session = null;
}
});
Note that the application logic can be triggered only after receiving the solace.SessionEventCode.UP_NOTICE
event.
Sending a message to a queue
Now it is time to send a message to the queue. Remember that the queue must be pre-configured on the message router as described in the "Creating a Durable Queue" section.
In the simplest case, the actual method calls to create and send guaranteed messages to a queue are similar to those used for direct messages in the publish/subscribe tutorial. The differences are:
- a durable queue type destination is created and used,
- the delivery mode is set to PERSISTENT, and
- delivery to the Solace message router is confirmed (shown in the Confirmed Delivery tutorial).
var messageText = 'Sample Message';
var message = solace.SolclientFactory.createMessage();
producer.log('Sending message "' + messageText + '" to queue "' + producer.queueName + '"...');
message.setDestination(solace.SolclientFactory.createDurableQueueDestination(producer.queueName));
message.setBinaryAttachment(messageText);
message.setDeliveryMode(solace.MessageDeliveryModeType.PERSISTENT);
try {
// Delivery not yet confirmed. See ConfirmedPublish.js
producer.session.send(message);
producer.log('Message sent.');
} catch (error) {
producer.log(error.toString());
}
The message is transferred to the Solace message router asynchronously, but if all goes well, it will be waiting for your consumer on the queue. The Confirmed Delivery tutorial shows how to make sure it gets there.
Receiving a message from a queue
Now it is time to receive the messages sent to your queue.
Receiving guaranteed messages is different from the direct messaging case described in the the publish/subscribe tutorial.
To receive guaranteed messages, a connected Session
is used to create a Solace MessageConsumer
object from MessageConsumerProperties
and then connected, meaning that it will bind to the queue on the message router and can start receiving messages.
// Create message consumer
consumer.messageConsumer = consumer.session.createMessageConsumer({
// solace.MessageConsumerProperties
queueDescriptor: { name: consumer.queueName, type: solace.QueueType.QUEUE },
acknowledgeMode: solace.MessageConsumerAcknowledgeMode.CLIENT, // Enabling Client ack
});
// define message consumer event listeners
/*...see section Message Consumer Events...*/
// define message received event listener
/*...see section Message Consumer Message Received Event...*/
// connect the message consumer
try {
consumer.messageConsumer.connect();
} catch (error) {
consumer.log(error.toString());
}
Notice that here we use the Solace "Client acknowledgement mode", which allows the consumers to acknowledge each message individually. You can learn more about acknowledgement modes in the Solace Documentation – Acknowledging Messages Received by Clients.
acknowledgeMode: solace.MessageConsumerAcknowledgeMode.CLIENT, // Enabling Client ack
Message Consumer Events
Message consumer related events will be sent to the event listeners defined for the MessageConsumer
. The most important events are:
MessageConsumerEventName.UP
: the message consumer has successfully bound to the destination and ready to receive messagesMessageConsumerEventName.CONNECT_FAILED_ERROR
: the message consumer has not been able to bind to the destinationMessageConsumerEventName.DOWN
: the message consumer has been disconnected.
// Define message consumer event listeners
consumer.messageConsumer.on(solace.MessageConsumerEventName.UP, function () {
consumer.consuming = true;
consumer.log('=== Ready to receive messages. ===');
});
consumer.messageConsumer.on(solace.MessageConsumerEventName.CONNECT_FAILED_ERROR, function () {
consumer.consuming = false;
consumer.log('=== Error: the message consumer could not bind to queue "' + consumer.queueName +
'" ===\n Ensure this queue exists on the message router vpn');
});
consumer.messageConsumer.on(solace.MessageConsumerEventName.DOWN, function () {
consumer.consuming = false;
consumer.log('=== An error happened, the message consumer is down ===');
});
Message Consumer Message Received Event
Message received events will be sent to the message received event listener defined for the message consumer. Successful processing of a message must be explicitly acknowledged because "client acknowledgement mode" is used:
// Define message received event listener
consumer.messageConsumer.on(solace.MessageConsumerEventName.MESSAGE, function (message) {
consumer.log('Received message: "' + message.getBinaryAttachment() + '",' +
' details:\n' + message.dump());
// Need to explicitly ack otherwise it will not be deleted from the message router
message.acknowledge();
});
Summarizing
Combining the example source code shown above results in the following source code files:
Learn how to verify all messages arrive to the Solace message router in our next tutorial, Confirmed Delivery.
Getting the Source
Clone the GitHub repository containing the Solace samples.
git clone https://github.com/SolaceSamples/solace-samples-nodejs
cd solace-samples-nodejs
Note: the code in the master
branch of this repository depends on Solace Node.js API version 10 or later. If you want to work with an older version clone the branch that corresponds your version.
Installing the Node.js API
For a local installation of the API package, run from the current solace-samples-nodejs
directory:
npm install
Running the Samples
The samples consist of two separate producer and consumer Node.js applications in the /src/basic-samples
directory: QueueProducer.js
and QueueConsumer.js
.
The producer application sends one message and exits, the consumer application is running until Ctrl-C is pressed on the console.
Sample Output
First run QueueConsumer.js
in Node.js, giving it following arguments:
node QueueConsumer.js <protocol://host:port> <client-username>@<message-vpn> <client-password>
The following is the output of the tutorial’s QueueConsumer.js
application after it successfully connected to the Solace message router and bound to the queue.
$ node QueueConsumer.js ws://192.168.133.64 testuser@default passw
[11:35:05]
*** Consumer to queue "tutorial/queue" is ready to connect ***
[11:35:05] Connecting to Solace message router using url: ws://192.168.133.64
[11:35:05] Client username: testuser
[11:35:05] Solace message router VPN name: default
[11:35:05] Press Ctrl-C to exit
[11:35:05] === Successfully connected and ready to start the message consumer. ===
[11:35:05] Starting consumer for queue: tutorial/queue
[11:35:05] === Ready to receive messages. ===
Now, run QueueProducer.js
in Node.js, also specifying the same arguments.
node QueueProducer.js <protocol://host:port> <client-username>@<message-vpn> <client-password>
It will connect to the router, send a message and exit.
The following is the output of the tutorial’s QueueProducer.js
application after it successfully connected to the Solace message router, published a message and exited.
$ node QueueProducer.js ws://192.168.133.64 testuser@default passw
[11:35:37]
*** Producer to queue "tutorial/queue" is ready to connect ***
[11:35:37] Connecting to Solace message router using url: ws://192.168.133.64
[11:35:37] Client username: testuser
[11:35:37] Solace message router VPN name: default
[11:35:37] === Successfully connected and ready to send messages. ===
[11:35:37] Sending message "Sample Message" to queue "tutorial/queue"...
[11:35:37] Message sent.
[11:35:37] Disconnecting from Solace message router...
[11:35:37] Disconnected.
This is the subscriber receiving a message (QueueConsumer.js
):
[11:35:37] Received message: "Sample Message", details:
Destination: [Queue tutorial/queue]
Class Of Service: COS1
DeliveryMode: PERSISTENT
Message Id: 8106
Expiration: 0 (Wed Dec 31 1969 19:00:00 GMT-0500 (Eastern Standard Time))
Binary Attachment: len=14
53 61 6d 70 6c 65 20 4d 65 73 73 61 67 65 Sample.Message
You have now successfully connected a client, sent guaranteed messages to a queue and received them from a message consumer.