com.solace.messaging.receiver

Interface MessageQueueBrowser

All Superinterfaces:

AsyncLifecycleControl, LifecycleControl, ManageableReceiver, MessageReceiver

@ProviderType
public interface MessageQueueBrowser
extends MessageReceiver

A Queue Browser allows client applications to look at messages stored in persistent store of Queue Endpoints without removing them. Messages are browsed from oldest to newest.

After being browsed, messages are still available for consumption over normal persistent receiver. 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 message 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.

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.

Since:

1.2.0

Nested Class Summary

Nested classes/interfaces inherited from interface com.solace.messaging.receiver.MessageReceiver

MessageReceiver.FailedReceiveEvent, MessageReceiver.InboundMessageSupplier, MessageReceiver.MessageHandler, MessageReceiver.ReceiveFailureListener

Nested classes/interfaces inherited from interface com.solace.messaging.util.LifecycleControl

LifecycleControl.TerminationEvent, LifecycleControl.TerminationNotificationListener

Nested classes/interfaces inherited from interface com.solace.messaging.util.ManageableReceiver

ManageableReceiver.DirectReceiverInfo, ManageableReceiver.PersistentReceiverInfo

Method Summary

Modifier and Type	Method and Description
InboundMessage	receiveMessage() Blocking request to receive a next message from a message browser without removing them from a persistent store of Queue Endpoints.
InboundMessage	receiveMessage(long timeOut) Blocking request to receive a next message from a message browser without removing them from a persistent store of Queue Endpoints.
InboundMessage	receiveOrElse(MessageReceiver.InboundMessageSupplier supplierOfAlternativeResponse) Request to receive a next message from a message browser without removing them from a persistent store of Queue Endpoints.
void	remove(InboundMessage message) Request to remove a message from the PubSubPlus broker's Queue Endpoint.
MessageQueueBrowser	start() Enables service regular duties.
<MessageQueueBrowser> CompletableFuture<MessageQueueBrowser>	startAsync() Asynchronously starts service for consuming/publishing operations.

Methods inherited from interface com.solace.messaging.receiver.MessageReceiver

setReceiveFailureListener

Methods inherited from interface com.solace.messaging.util.LifecycleControl

isRunning, isTerminated, isTerminating, setTerminationNotificationListener, terminate

Methods inherited from interface com.solace.messaging.util.AsyncLifecycleControl

startAsync, terminateAsync, terminateAsync

Methods inherited from interface com.solace.messaging.util.ManageableReceiver

receiverInfo

Method Detail

receiveMessage

InboundMessage receiveMessage()
                       throws PubSubPlusClientException,
                              PubSubPlusClientException.RequestInterruptedException

Blocking request to receive a next message from a message browser without removing them from a persistent store of Queue Endpoints. Caller thread is used to perform operation.

Returns:

next inbound message from a broker

Throws:

PubSubPlusClientException - when message could not be received for an internal reason

PubSubPlusClientException.RequestInterruptedException - when thread was interrupted while waiting for a next message. An interrupted flag is expected to be set on a thread in this case

Since:

1.2.0

receiveMessage

InboundMessage receiveMessage(long timeOut)
                       throws PubSubPlusClientException,
                              PubSubPlusClientException.RequestInterruptedException

Blocking request to receive a next message from a message browser without removing them from a persistent store of Queue Endpoints. Caller thread is used to perform operation.

Parameters:

timeOut - time out in milliseconds after that blocking receive exits, values > 0 are expected, use receiveOrElse (..) method when immediate response is required

Returns:

next inbound message from a broker or null after time out occurs

Throws:

PubSubPlusClientException - when message could not be received for an internal reason

PubSubPlusClientException.RequestInterruptedException - when thread was interrupted while waiting for a next message. An interrupted flag is expected to be set on a thread in this case

Since:

1.2.0

receiveOrElse

InboundMessage receiveOrElse(MessageReceiver.InboundMessageSupplier supplierOfAlternativeResponse)

Request to receive a next message from a message browser without removing them from a persistent store of Queue Endpoints. When no message is available, the specified supplier is used to generate a response. This method is non-blocking. This method represents a pull-based non-blocking interface. The caller's thread is used to perform the operation.

Parameters:

supplierOfAlternativeResponse - the alternative response if no new message is available

Returns:

the next message or generated response if no message at the time point of the call is available

Since:

1.2.0

remove

void remove(InboundMessage message)
     throws PubSubPlusClientException

Request to remove a message from the PubSubPlus broker's Queue Endpoint.

Note: If browsing a queue with an active message consumer, no guarantee is made that message removal removes a message before another consumer received it

Parameters:

message - a message to be removed from the PubSubPlus broker's Queue Endpoint

Throws:

PubSubPlusClientException - when message could not be tried to be removed for an internal reason

Since:

1.2.0

start

MessageQueueBrowser start()
                   throws PubSubPlusClientException,
                          IllegalStateException

Description copied from interface: LifecycleControl

Enables service regular duties. Before this method is called, the service is considered off-duty. To operate normally, this method needs to be called on a receiver or publisher instance. This method is idempotent.

Specified by:

start in interface LifecycleControl

Specified by:

start in interface MessageReceiver

Returns:

an instance of class on which the method was called to support chaining

Throws:

PubSubPlusClientException - if the instance fails to start for some internal reason

IllegalStateException - if the instance was previously terminated, being terminated, or the method has been invoked at an illegal or at an inappropriate time for some another reason

startAsync

<MessageQueueBrowser> CompletableFuture<MessageQueueBrowser> startAsync()
                                                                 throws PubSubPlusClientException,
                                                                        IllegalStateException

Description copied from interface: AsyncLifecycleControl

Asynchronously starts service for consuming/publishing operations. In order to operate normally, this method needs to be called on a service instance. If the service is started or in the process of being started, this operation has no effect.

This method is an idempotent operation when no another connect/disconnect operation is ongoing.

Specified by:

startAsync in interface AsyncLifecycleControl

Specified by:

startAsync in interface MessageReceiver

Returns:

a future state of the start request that can complete successfully or fail.

Throws:

PubSubPlusClientException - if the messaging service will not start in the future

IllegalStateException - if the method has been invoked at an illegal or inappropriate time