Version: 10.17.1
Class

solace.QueueBrowser

Contents

class solace.QueueBrowser

This class is not exposed for construction by API users. A Queue Browser is created by calling solace.Session#createQueueBrowser.

A Queue Browser allows client applications to look at messages spooled on Endpoints without removing them. Messages are browsed from oldest to newest. After being browsed, messages are still available for consumption over normal flows. However, it is possible to selectively remove messages from the persistent store of an Endpoint. In this case, these removed messages will no longer be available for consumption. Note: If browsing a queue with an active consumer, no guarantee is made that the browser will receive all messages published to the queue. The consumer can receive and acknowledge messages before they are delivered to the browser.

One typical application is to use Browsers to allow message bus administrators to remove “stuck” Guaranteed messages from an Endpoint without having to modify or disrupt existing applications. A message can get stuck if:

1) It has been received by an application, but for some reason, that application has failed to acknowledge it. 2) All active message selectors have failed to match this particular message and therefore the message bus has not delivered it to any client yet. The current release only supports browsing Endpoints of type Queue.

Note that the delivery restrictions imposed by the queue’s Access type (exclusive or non-exclusive), do not apply when browsing messages with a Browser.

Browser characteristics and behavior are defined by solace.QueueBrowserProperties. The properties can also be supplied as a simple key-value {Object}. The queue descriptor, solace.QueueBrowserProperties#queueDescriptor must be specified to identify the Guaranteed Message Queue on the Solace Message Router.

The Browser is an EventEmitter, and will emit events to which the application may choose to subscribe, such as the connection to the Solace Message Router going up or down.

If a registered listener for an emitted event throws an exception, this is caught and emitted as an 'error'.

Fires

Constructor Top

  QueueBrowser ( )

Methods Top

void connect ( )
void disconnect ( )
void removeMessageFromQueue ( Message message )
void start ( )
void stop ( )

Constructor details Top

QueueBrowser ( )

This class is not exposed for construction by API users. A Queue Browser is created by calling solace.Session#createQueueBrowser.

A Queue Browser allows client applications to look at messages spooled on Endpoints without removing them. Messages are browsed from oldest to newest. After being browsed, messages are still available for consumption over normal flows. However, it is possible to selectively remove messages from the persistent store of an Endpoint. In this case, these removed messages will no longer be available for consumption. Note: If browsing a queue with an active consumer, no guarantee is made that the browser will receive all messages published to the queue. The consumer can receive and acknowledge messages before they are delivered to the browser.

One typical application is to use Browsers to allow message bus administrators to remove “stuck” Guaranteed messages from an Endpoint without having to modify or disrupt existing applications. A message can get stuck if:

1) It has been received by an application, but for some reason, that application has failed to acknowledge it. 2) All active message selectors have failed to match this particular message and therefore the message bus has not delivered it to any client yet. The current release only supports browsing Endpoints of type Queue.

Note that the delivery restrictions imposed by the queue’s Access type (exclusive or non-exclusive), do not apply when browsing messages with a Browser.

Browser characteristics and behavior are defined by solace.QueueBrowserProperties. The properties can also be supplied as a simple key-value {Object}. The queue descriptor, solace.QueueBrowserProperties#queueDescriptor must be specified to identify the Guaranteed Message Queue on the Solace Message Router.

The Browser is an EventEmitter, and will emit events to which the application may choose to subscribe, such as the connection to the Solace Message Router going up or down.

If a registered listener for an emitted event throws an exception, this is caught and emitted as an 'error'.

Fires

Methods Detail Top

public void connect ( )

Connects the queue browser immediately. The application should add event listeners (see solace.QueueBrowserEventName). If there is no listener added for solace.QueueBrowserEventName#event:MESSAGE then up to a window solace.QueueBrowserProperties.windowSize of messages can be queued internally. before calling this method.

Return Value

void

Throws

solace.OperationError

public void disconnect ( )

Initiates an orderly disconnection of the queue browser. The API will send an unbind request. Any messages subsequently received are discarded silently. When the unbind message is acknowledged, the application receives a solace.QueueBrowserEventName#event:DOWN event if it has set a listener for that event.

Return Value

void

Throws

solace.OperationError

public void removeMessageFromQueue ( Message message )

Removes a message from the queue by acknowledging it.

The solace.QueueBrowser does not automatically acknowledge messages. once they have been received.

The API does not send acknowledgments immediately. It stores the state for acknowledged messages internally and acknowledges messages, in bulk, when a threshold or timer is reached.

Parameters

Message message

The message to remove

Return Value

void

public void start ( )

Begins delivery of messages to this queue browser. This method opens the protocol window to the Solace Message Router so further messages can be received.

A newly created queue browser is in started state.

If the queue browser was already started, this method has no effect.

A consumer is stopped by calling solace.QueueBrowser.stop

Return Value

void

Throws

solace.OperationError

public void stop ( )

Stops messages from being delivered to this queue browser from the Solace Message Router. Messages may continue to be prefetched by the API and queued internally until solace.QueueBrowser#start is called.

If the queue browser was already stopped, this method has no effect.

Return Value

void

Throws

solace.OperationError