Browsing Guaranteed Messages

The Solace Java RTO API can use browser flows to look at guaranteed messages spooled on a queue in the order of oldest to newest.

Browser flows 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 Browser Flows

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

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

To create browser flows, use CreateFlowForHandle(...)

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 Solace Java RTO API, the queue is specified when creating the flow.
  • Enable the property FlowHandle.PROPERTIES.BROWSER 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 Browser Flows

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

To close browser flow, use FlowHandle.destroy()

Browsing Messages with the Solace Java RTO API

To browse Guaranteed messages on a queue when using the Solace Java RTO API, do the following:

  1. Create a browser flow. For more information, see Creating Browser Flows.

    Messages are handled according to the referenced callback.

  2. When the maximum number of messages set by the window size is reached, call FlowHandle.start() to reset the window so that more Guaranteed messages can be browsed.

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 when using the Solace Java RTO API, send an acknowledgment for the message that is received on the browser flow.

To remove browsed messages, use:

  • FlowHandle.ack(long adMsgId)
  • FlowHandle.ack(MessageHandle rxMsg)