Browsing Guaranteed Messages

The Solace C 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.

For an example of how to browse messages on a queue, see the simpleBrowserFlow.c sample in the Solace C API Reference Documentation.

Creating Browser Flows

To browse Guaranteed messages spooled for a queue, a client must create a browser flow in a session.

To create a browser flow, use solClient_session_createFlow(...), and pass in the appropriate flow properties.

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. The queue is set through the flow properties.
  • Enable the property SOLCLIENT_FLOW_PROP_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.

If the session is not already connected, 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 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 flow when the application is done with it. To close a browser flow, call solClient_flow_destroy(...).

Browsing Messages

To browse Guaranteed messages on a queue, 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 solClient_flow_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, send an acknowledgment for the message that is received on the browser flow by calling solClient_flow_sendAck(solClient_opaqueFlow_pt opaqueFlow_p, solClient_msgId_t msgId).