Browsing Guaranteed Messages

The Solace JavaScript API and Solace Node.js API can browse guaranteed messages with a browser object to look at guaranteed messages spooled on a queue in the order of oldest to newest.

Browser objects enable your application to browse messages on a queue and selectively remove messages as needed. This can be done independently of any other flow bound to the queue. Browsers allow you to connect to an exclusive queue even if other applications are connected and active on the queue. When you connect to a non-exclusive queue, you can view all messages on the queue. In this case, your browser is not subject to the round-robin method used to deliver messages to regular consumers. After messages are browsed, clients can still receive them over flows.

A queue's access type, exclusive or non-exclusive, does not affect clients' ability to browse its spooled messages. It only affects clients' ability to consume those messages. For more information about access type, see Defining Endpoint Properties.

Creating Browsers

To browse Guaranteed messages spooled for a queue when using the Solace JavaScript API and Solace Node.js API a client must create a browser in a session.

To create a browser in the Solace JavaScript API and Solace Node.js API, call session.createQueueBrowser(solace.QueueBrowserProperties | Object browserProperties) and pass in a set of browser properties.

When defining a new set of browser properties, be sure to do the following:

Specify the queue endpoint that you want to browse. Only queues can be browsed—topic endpoints cannot be browsed.
(Optional) Specify a maximum wait time-out (in milliseconds) before returning from a GetNext operation if no messages are available in the local message buffer through the WaitTimeout property.

If the session is not already connected, the API will throw an error.
The life span of the browser is tied to the session that it is created in. Therefore, closing a session closes all browsers created in that session.

Closing Browsers

To free allocated memory, it is important to close the browser instance when the application is done with it. To close a browser, call browser.disconnect().

Browsing Messages with the Solace JavaScript API or Solace Node.js API

To browse Guaranteed messages on a queue when using the Solace JavaScript API or Solace Node.js API, do the following:

Create an object literal to set your queue browser properties. The only required property is the queueDescriptor which is the name of the queue to browse, but you can also set:
- connectAttempts—Gets and sets the maximum number of bind attempts when creating a connection to the Solace event broker. The default is 3.
- connectTimeoutInMsecs—The bind timeout in milliseconds when creating a connection to the Solace event broker. The default is 10000.
- transportAcknowledgeThresholdPercentage—The threshold for sending an acknowledgment, as a percentage. The default is 60.
- transportAcknowledgeTimeoutInMsecs—The transport acknowledgment timeout for guaranteed messaging in milliseconds. The default is 1000.
- windowSize—The window size for Guaranteed message delivery. The default is 255.
For more information about queue browser properties, see solace.QueueBrowserProperties in the Solace Messaging API for JavaScript reference documentation.

The example below shows a simple queue browser property object that contains only the queue name:
```
const queueBrowserProps = {
   queueDescriptor: { name: "queueName", type: solace.QueueType.QUEUE },
};
```
Create a browser object with the createQueueBrowser() function, and connect it to the event broker with the connect() function.
```
queuebrowser = session.createQueueBrowser(queueBrowserProps);
queuebrowser.connect();
```

(Optional) If you need to pause your queue browser for any reason, use the stop() function. To start your browser again use the start() function.

queuebrowser.stop();
// Perform any operation here, for example wait for 1 second to allow message processing to catch up: setTimeout(() => {}, 1000);
queuebrowser.start();

The queue browser is an event emitter, and you can chose which events your application subscribes to using event listeners:
- solace.QueueBrowserEventName.UP—The queue browser is connected.
- solace.QueueBrowserEventName.DOWN—The queue browser is disconnected.
- solace.QueueBrowserEventName.DOWN_ERROR—The queue browser was disconnected by the router, likely due to operator intervention.
- solace.QueueBrowserEventName.MESSAGE—A message was received on the queue browser.
- solace.QueueBrowserEventName.DISPOSED—The queue browser is disposed. No further events will be emitted.
- solace.QueueBrowserEventName.GM_DISABLED—The queue browser will not connect because the current session is incompatible with Guaranteed messaging.
- solace.QueueBrowserEventName.CONNECT_FAILED_ERROR—The queue browser attempted to connect but was unsuccessful.
For more information on queue browser events, see solace.QueueBrowserEventName in the Solace Messaging API for JavaScript reference documentation.
To begin receiving browsed messages, create an event listener for MESSAGE. This listener will continue to receive browsed messages until the browser is stopped, disconnected or has received all the messages in a queue. The following example shows an event listener for browsed messages:
```
queuebrowser.on(solace.QueueBrowserEventName.MESSAGE, (message) => {
   // the browsed message:
   receivedMessage = message;
   // If you want to remove the message from the queue:
   queuebrowser.removeMessageFromQueue (receivedMessage);
});
```

When there is no listener for solace.QueueBrowserEventName.MESSAGE on a QueueBrowser, messages are queued internally until a listener is added.

Removing Messages When Browsing

A client can selectively remove spooled Guaranteed messages while browsing a queue. Removing browsed messages deletes them from the queue, so that they can no longer be delivered to consuming clients (or redelivered if they were already delivered to consumers at some point).

Selectively removing messages when browsing can be useful in situations where an administrator wants to remove "stuck" Guaranteed messages from a queue without modifying or disrupting existing consuming clients. A message can get stuck if:

It has been received by a client, but that client has failed to acknowledge it.
All active message selectors have failed to match the message, so the message has not been delivered to any client.

No confirmation is returned when a message is removed. Further, no error is returned if you try to remove a non-existent message or a message that has already been removed from a queue.

To remove a browsed message, call solace.QueueBrowser.removeMessageFromQueue(message).

Provide feedback