Browsing Guaranteed Messages in the PubSub+ JCSMP API

The PubSub+ JCSMP API can use queue browser objects 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 on access type, refer to Defining Endpoint Properties in the PubSub+ JCSMP API.

For an example of how to browse messages on a queue, see the QueueProvisionAndBrowse.java sample on the Solace Developer Hub

Creating Browsers

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

To create a browser, call the JCSMPSession.createBrowser(BrowserProperties properties)method 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. For JCSMP, the queue is set through the flow properties.
• (Optional) For JCSMP, 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 information on selectors and selector syntax, refer to Using Selectors in the PubSub+ JCSMP API.)
• (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 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.

Closing Browsers

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, call Browser.close()

Browsing Messages with the JCSMP API

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

1. Acquire a browser instance.

   Refer to Creating Browsers.

2. (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.

3. 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.

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 Browser.remove(BytesXMLMessage message)