Browsing Guaranteed Messages

The Solace .NET API can use queue browser instances 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, a client must create a browser in a session.

To create a browser, call the ISession.CreateBrowser(Endpoint endpointToBrowse, BrowserProperties browserProperties) method.

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. The IEndpoint is passed in separately.
  • (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 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 window size property.
  • (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 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 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 IBrowser.Dispose().

Browsing Messages

To browse Guaranteed messages on a queue, do the following:

  1. Acquire a browser instance.

    For more information, see 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 one of the following methods:

  • IBrowser.Remove(IMessage)
  • IBrowser.Remove(Int64)