Browsing Guaranteed Messages

Client applications using the JCSMP and .NET APIs can use the Browser interface to look at Guaranteed messages spooled for a Queue in the order of oldest to newest without consuming them.

Client applications using the C API can also look at Guaranteed messages without consuming them by using a Browser Flow. A Browser Flow is a non‑consuming Flow that can be bound to a Queue; the message receive callback set for the Browser Flow enables the clients to browse the spooled messages in the order of oldest to newest without consuming them.

Client applications can use a Session.createQueueBrowser() in JavaScript and Node.js APIs to look at Guaranteed messages spooled for a Queue in the order of oldest to newest without consuming them.

A Queue’s access type (that is, 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.)

After messages are browsed, they can still be received by clients over Flows.

Related Samples

For an example of how to browse messages on a Queue, refer to the QueueProvisionAndBrowse sample for the JCSMP and .NET APIs or to the simpleBrowserFlow.c the C API.

Creating Browsers

To browse Guaranteed messages spooled for a Queue when using the Java 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)

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) 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.)
  • (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, these calls first connect the Session and then create the Browser instance.
  • 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 Java RTO or C 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 information on creating standard Flows, refer to 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 information on selectors and selector syntax, refer to 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()

Browsing Messages with the JCSMP and .NET APIs

To browse Guaranteed messages on a Queue when using the Java or .NET 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.

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:

  1. Create a Browser Flow. (Refer to 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() (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.

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 Java 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)