Browsing Guaranteed Messages

PubSub+ messaging APIs can use queue browser instances or browser flows to look at guaranteed messages spooled on a queue in the order of oldest to newest.

The PubSub+ C and Java RTO APIs can browse guaranteed messages with a browser flow.
The PubSub+ JCSMP, JavaScript, Node.js, and .NET APIs can browse guaranteed messages with a browser object.

Browser flows and 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.

For an example of how to browse messages on a queue, see:

the QueueProvisionAndBrowse.java JCSMP sample on the Solace Developer Hub
the simpleBrowserFlow.c sample in the C API Reference Documentation

Creating Browsers

To browse Guaranteed messages spooled for a queue when using the JCSMP, JavaScript, Node.js or .NET API, a client must create a browser in a session.

To create a browser, call one of the methods listed below and pass in a set of browser properties.

To create browsers
PubSub+ Messaging API	Call
JCSMP	`JCSMPSession.createBrowser(BrowserProperties properties)`
.NET	`ISession.CreateBrowser(Endpoint endpointToBrowse, BrowserProperties browserProperties)`
JavaScript, Node.js	`session.createQueueBrowser(solace.QueueBrowserProperties \| Object browserProperties)`

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. For JCSMP, the queue is set through the flow properties. For .NET, the IEndpoint is passed in separately.
(Optional) For JCSMP and .NET, specify a selector string for the Selector property to only browse messages that match that selector. When a selector is used, the wait time-out can be significantly increased because it takes longer for the message bus to evaluate spooled messages against a selector. The complexity of the selector can also increase the evaluation time. (For more information about selectors and selector syntax, see Using Selectors.)
(Optional) To increase browsing performance, specify the maximum number of messages that the browser can pre-fetch from the queue and buffer locally through the transport window size (JCSMP) or window size (.NET API) properties.
(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:
- JavaScript/Node.js—the API will throw an error.
- JCSMP—the API auto-connects the session and creates the browser instance.
- C, C#, Java RTO—the operation depends on the property FLOW_BIND_BLOCKING. If this property is enabled, the default setting, the API blocks until the session is connected, otherwise the function call returns immediately and waits for the session connect operation to complete.
The life span of the browser or browser flow is tied to the session that it is created in. Therefore, closing a session closes all browsers created in that session.

Creating Browser Flows

To browse Guaranteed messages spooled for a queue when using the C or Java RTO APIs, a client must create a browser flow in a session.

To create a browser flow, use one of the methods listed below, and pass in the appropriate flow properties:

To create browser flows
PubSub+ Messaging API	Call
Java RTO	`CreateFlowForHandle(...)`
C	`solClient_session_createFlow(...)`

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

Specify the queue that you want to browse. Only queues can be browsed—topic endpoints cannot be browsed. For the Java RTO API, the queue is specified when creating the flow. For the C API, the queue is set through the flow properties.
Enable the property FlowHandle.PROPERTIES.BROWSER (for the Java RTO API) or SOLCLIENT_FLOW_PROP_BROWSER (for the C API) to configure the flow as a browser flow rather than a standard Guaranteed message flow. For more information about creating standard flows, see Creating Flows.
Pass in a pointer to a structure that provides information on callback functions for messages and events that are received on this browser flow.
(Optional) Specify a selector string for the Selector property to only browse messages that match that selector. When a selector is used, the wait time-out can be significantly increased because it takes longer for the message bus to evaluate spooled messages against a selector. The complexity of the selector can also increase the evaluation time. For more information on selectors and selector syntax, see Using Selectors.
(Optional) To increase browsing performance, specify the maximum number of messages that the browser can pre-fetch from the queue and buffer locally through the window size property.

The life span of a flow is tied to the session that it is created in. Therefore, closing a session closes all browser flows created in that session. When a session is reconnected, a browser flow will rebind to its session.

Closing Browsers or Browser flows

To free allocated memory, it is important to close the browser instance when the application is done with it.

To close browsers or browser flows
PubSub+ Messaging API	Call
JCSMP	`Browser.close()`
Java RTO	`FlowHandle.destroy()`
C	`solClient_flow_destroy(...)`
.NET	`IBrowser.Dispose()`
JavaScript, Node.js	`browser.disconnect()`

Browsing Messages with the JCSMP or .NET APIs

To browse Guaranteed messages on a queue when using the JCSMP or .NET API, do the following:

Acquire a browser instance.
For more information, see Creating Browsers.
(Optional)To check if there is a message immediately available in the local message buffer, call a HasMore method.
If at least one message is available in the local buffer, this method returns true. If it returns false, it does not necessarily mean that the queue is empty, rather the local buffer does not currently contain any messages. Subsequent calls to HasMore or GetNext methods might return true, or return a message, respectively.
These methods are provided to support the enumeration pattern for javax.jms.QueueBrowser used by JMS implementations.
To look at a message in a queue, call a GetNext method.
- GetNext is a synchronous operation that returns the full contents of a message (that is, complete with all message headers and payloads). Each call to GetNext returns the next message in the queue (in order of oldest to newest).
- GetNext methods check the local buffer for messages. If a message is available, it returns immediately; if no message is available, the call returns null (when using the GetNextNoWait() method), or it waits for a message for up to a set amount of time (when using the GetNext() method).
Client applications should not make any assumptions about the polling strategy used by the API when browsing spooled messages. For example, when browsing messages, the API could be requesting more messages from the event broker or returning already buffered messages.

Browsing Messages with the Java RTO or C APIs

To browse Guaranteed messages on a queue when using the Java RTO or C APIs, do the following:

Create a browser flow. For more information, see Creating Browser Flows.
Messages are handled according to the referenced callback.
When the maximum number of messages set by the window size is reached, call FlowHandle.start() (for the Java RTO API) or solClient_flow_start() (for the C API) to reset the window so that more Guaranteed messages can be browsed.

Browsing Messages with the JavaScript or Node.js APIs

To browse Guaranteed messages on a queue when using the JavaScript or Node.js APIs, 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 broker. The default is 3.
- connectTimeoutInMsecs—The bind timeout in milliseconds when creating a connection to the Solace 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 PubSub+ 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 PubSub+ 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 do the following:

When using the JCSMP, JavaScript, Node.js or .NET APIs, call one of the methods listed below for that message.
When using the Java RTO or C APIs, send an acknowledgment for the message that is received on the browser flow.

To remove browsed messages
PubSub+ Messaging API	Call
JCSMP	`Browser.remove(BytesXMLMessage message)`
Java RTO	`FlowHandle.ack(long adMsgId)` `FlowHandle.ack(MessageHandle rxMsg)`
C	`solClient_flow_sendAck(solClient_opaqueFlow_pt opaqueFlow_p, solClient_msgId_t msgId)`
.NET	`IBrowser.Remove(IMessage)` `IBrowser.Remove(Int64)`
JavaScript, Node.js	`solace.QueueBrowser.removeMessageFromQueue(message)`

Provide feedback