com.solacesystems.jcsmp

Interface Browser

public interface Browser

A 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:

• It has been received by an application, but for some reason, that application has failed to acknowledge it.
• 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.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the Browser.
BytesXMLMessage	getNext() Retrieve the next message from the Browser's local message buffer, if one is available, waiting if necessary up to the timeout configured in BrowserProperties.
BytesXMLMessage	getNext(int timeoutInMillis) Retrieve the next message from the Browser's local message buffer, if one is available, waiting if necessary up to timeoutInMillis ms.
BytesXMLMessage	getNextNoWait() If there is at least one message available in the Browser's local message buffer, return it immediately; otherwise, return null.
boolean	hasMore() Returns true if there is at least one message available in the Browser's local message buffer.
void	remove(BytesXMLMessage message) Remove a message from the appliance's Queue Endpoint.

Method Detail

close

void close()

Closes the Browser.

hasMore

boolean hasMore()
         throws JCSMPException

Returns true if there is at least one message available in the Browser's local message buffer. Note: If this method returns false, it does not mean that the queue is empty; subsequent calls to Browser.hasMore() or Browser.getNext() might return true and a message respectively.

Returns:

True, if there is at least one message available in the Browser's local message buffer.

Throws:

JCSMPException - on error

getNext

BytesXMLMessage getNext()
                 throws JCSMPException

Retrieve the next message from the Browser's local message buffer, if one is available, waiting if necessary up to the timeout configured in BrowserProperties. If you want to wait indefinitely, use Browser.getNext(int) with a timeoutInMillis of 0.

Returns:

A message from the Browser's local message buffer or null, if timed out.

Throws:

JCSMPException - on error

getNext

BytesXMLMessage getNext(int timeoutInMillis)
                 throws JCSMPException

Retrieve the next message from the Browser's local message buffer, if one is available, waiting if necessary up to timeoutInMillis ms.

• If timeout is < 0, return immediately if there are no messages available locally.
• If timeout is equal to 0, wait forever. This blocks the calling thread; to unblock it, call Browser.close().

Parameters:

timeoutInMillis - Time to wait for a message.

Returns:

A message from the Browser's local message buffer, or null, if timed out.

Throws:

JCSMPException - on error

getNextNoWait

BytesXMLMessage getNextNoWait()
                       throws JCSMPException

If there is at least one message available in the Browser's local message buffer, return it immediately; otherwise, return null.

Returns:

A message from the Browsers local message buffer, or null, if none.

Throws:

JCSMPException - on error

remove

void remove(BytesXMLMessage message)
     throws JCSMPException

Remove a message from the appliance's Queue Endpoint.

Parameters:

message - Message to remove from the Endpoint.

Throws:

JCSMPException - on error