com.solace.messaging.receiver

Interface PersistentMessageReceiver

All Superinterfaces:

AcknowledgementSupport, AsyncLifecycleControl, AsyncReceiverSubscriptions, LifecycleControl, ManageableReceiver, MessageReceiver, ReceiverFlowControl, ReceiverSubscriptions

@ProviderType
public interface PersistentMessageReceiver
extends MessageReceiver, ReceiverFlowControl, ReceiverSubscriptions, AsyncReceiverSubscriptions, AcknowledgementSupport

An interface that abstracts behavior of PubSub+ persistent message consumer/receiver.

WARNING:

Co-usage of async and blocking message receiving methods on a single instance of receiver can have some not intended side effects and should be avoided.

'Async' methods should NOT be called multiple times or in combination with blocking message receiving method on a same instance of a MessageReceiver to avoid any not intended side effects.

Since:

1.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

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

AsyncReceiverSubscriptions.SubscriptionChangeListener

Method Summary

Modifier and Type	Method and Description
void	receiveAsync(MessageReceiver.MessageHandler messageHandler) Request to register an async message handler.
void	receiveAsync(MessageReceiver.MessageHandler messageHandler, ExecutorService executorService) Request to register an async message handler using own thread executor for callbacks.
InboundMessage	receiveMessage() Blocking request to receive a next message.
InboundMessage	receiveMessage(long timeOut) Temporarily blocking request to receive a next message;
InboundMessage	receiveOrElse(MessageReceiver.InboundMessageSupplier supplierOfAlternativeResponse) Request to receive a next message, when no message available, given supplier is used to generate a response, this method is nonblocking.
ManageableReceiver.PersistentReceiverInfo	receiverInfo() Provides access to the receiver information.
PersistentMessageReceiver	start() Enables service regular duties.
<PersistentMessageReceiver> CompletableFuture<PersistentMessageReceiver>	startAsync() Asynchronously starts service for consuming/publishing operations.
<PersistentMessageReceiver> void	startAsync(CompletionListener<PersistentMessageReceiver> startListener) Asynchronously starts service for consuming/publishing operations using a callback for completion notification.

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

terminateAsync, terminateAsync

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

pause, resume

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

addSubscription, removeSubscription

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

addSubscriptionAsync, removeSubscriptionAsync

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

ack, settle

Method Detail

receiveAsync

void receiveAsync(MessageReceiver.MessageHandler messageHandler)
           throws PubSubPlusClientException

Request to register an async message handler.

This method represents push- based non blocking interface. Callback method of a message handler will be executed on an internal API thread.

If enabled, auto-ack is going to be performed when message processing callback method is finished without an error, do not use another thread to process message within a callback method, auto ack not going to be accurate in this case.

Note: usage of receiveAsync method is CURRENTLY mutually exclusive with a non async methods receiveMessage and can be used once only

Parameters:

messageHandler - handler which is used to process each message asynchronously, not expected to be null

Throws:

PubSubPlusClientException - is thrown when messages handler can't be registered

Since:

1.0

receiveAsync

void receiveAsync(MessageReceiver.MessageHandler messageHandler,
                  ExecutorService executorService)
           throws PubSubPlusClientException

Request to register an async message handler using own thread executor for callbacks.

If enabled auto-ack is going to be performed performed when message processing callback method is finished without an error, do not use another thread to process message within a callback method, auto ack not going to be accurate in this case.

Note: usage of receiveAsync method is CURRENTLY mutually exclusive with a non async OR sync methods and can be used once only

Parameters:

messageHandler - message handler, to handle sequence of inbound messages

executorService - user provided instance of thread executor for message scheduling and * MessageReceiver.MessageHandler.onMessage(InboundMessage) execution.

IMPORTANT NOTE: Shutdown of the Executor service or any another maintenance work is responsibility of the developer.

IMPORTANT NOTE: when message order needs to be preserved, a SINGLE thread based executor is required.

Throws:

PubSubPlusClientException - for any of listed below reasons

Since:

1.0

receiveMessage

InboundMessage receiveMessage()
                       throws PubSubPlusClientException,
                              PubSubPlusClientException.RequestInterruptedException

Blocking request to receive a next message.

Acknowledgement can be performed using a this.ack(inboundMessage) where this refers to the current instance of PersistentMessageReceiver

This method can be used individually or usually in a while loop.

Usage of this method is CURRENTLY mutually exclusive with async methods

Returns:

new inbound message received message

Throws:

PubSubPlusClientException - when message could not be received

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.0

receiveMessage

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

Temporarily blocking request to receive a next message;

Acknowledgement can be performed using a this.ack(inboundMessage) where this refers to the current instance of PersistentMessageReceiver

This method can be used individually or usually in a while loop.

Usage of this method is CURRENTLY mutually exclusive with async methods

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 or null, when no new message could be received be received and a timeout occurred

Throws:

PubSubPlusClientException - when message could not be received

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

Since:

1.0 thread in this case

receiveOrElse

InboundMessage receiveOrElse(MessageReceiver.InboundMessageSupplier supplierOfAlternativeResponse)

Request to receive a next message, when no message available, given supplier is used to generate a response, this method is nonblocking. This method represents pull- based non blocking interface. Caller thread is used to perform operation.

Parameters:

supplierOfAlternativeResponse - supplies alternative response if no new message is available

Returns:

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

Since:

1.0

receiverInfo

ManageableReceiver.PersistentReceiverInfo receiverInfo()

Description copied from interface: ManageableReceiver

Provides access to the receiver information.

Specified by:

receiverInfo in interface ManageableReceiver

Returns:

a ReceiverInfo object that represents message receiver manageability.

start

PersistentMessageReceiver start()
                         throws PubSubPlusClientException

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

startAsync

<PersistentMessageReceiver> CompletableFuture<PersistentMessageReceiver> startAsync()

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.

startAsync

<PersistentMessageReceiver> void startAsync(CompletionListener<PersistentMessageReceiver> startListener)
                                     throws PubSubPlusClientException,
                                            IllegalStateException

Description copied from interface: AsyncLifecycleControl

Asynchronously starts service for consuming/publishing operations using a callback for completion notification. 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.

Specified by:

startAsync in interface AsyncLifecycleControl

Type Parameters:

PersistentMessageReceiver - the type of response returned on a successful start operation

Parameters:

startListener - the callback for future notifications about the completion of the start process

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