com.solace.messaging.receiver

Interface DirectMessageReceiver

All Superinterfaces:

AsyncLifecycleControl, AsyncReceiverSubscriptions, LifecycleControl, ManageableReceiver, MessageReceiver, ReceiverSubscriptions

@ProviderType
public interface DirectMessageReceiver
extends MessageReceiver, ReceiverSubscriptions, AsyncReceiverSubscriptions

An interface for using PubSub+ direct message consumers/receivers.

Note: A caller of any of blocking message receiving methods without the 'async' suffix, such as receiveMessage() will receive a new message for each call in a sequence.

Warning:

Co-usage of asynchronous and blocking message receiving methods on a single instance of receiver can have unexpected side-effects and must be avoided.

Asynchronous (Async*) methods must not be called multiple times or in combination with blocking, message receiving method on a same instance of a MessageReceiver to avoid unexpected 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 asynchronous message handler using supplied thread executor for callbacks.
InboundMessage	receiveMessage() Receive the next message.
InboundMessage	receiveMessage(long timeOut) Receive the next message.
InboundMessage	receiveOrElse(MessageReceiver.InboundMessageSupplier supplierOfAlternativeResponse) Request to receive a next message, when no message available, the specified supplier is used to generate a response.
ManageableReceiver.DirectReceiverInfo	receiverInfo() Provides access to the receiver information.
DirectMessageReceiver	start() Enables service regular duties.
<DirectMessageReceiver> CompletableFuture<DirectMessageReceiver>	startAsync() Asynchronously starts service for consuming/publishing operations.
<DirectMessageReceiver> void	startAsync(CompletionListener<DirectMessageReceiver> 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.ReceiverSubscriptions

addSubscription, removeSubscription

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

addSubscriptionAsync, removeSubscriptionAsync

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.

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

Parameters:

messageHandler - the message handler, to handle an ordered sequence of inbound messages

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 asynchronous message handler using supplied thread executor for callbacks. This method represents push- based non blocking interface.

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

Parameters:

messageHandler - the message handler to handle the sequence of inbound messages

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

Important:

The shutdown of the Executor service or any another maintenance work is the responsibility of the developer

When the order of the messages needs to be preserved, a single thread-based executor is required

Throws:

PubSubPlusClientException - if the messages handler cannot be registered

Since:

1.0

receiveMessage

InboundMessage receiveMessage()
                       throws PubSubPlusClientException,
                              PubSubPlusClientException.RequestInterruptedException

Receive the next message. This is a blocking request.

Returns:

next the inbound message

Throws:

PubSubPlusClientException - if the message could not be received

PubSubPlusClientException.RequestInterruptedException - if the thread is interrupted while waiting for the next message; an interrupted flag is expected to be set on the thread in this case

Since:

1.0

receiveMessage

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

Receive the next message. This method temporarily blocks while waiting to receive the next message

Parameters:

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

Returns:

the next inbound message or null, when no new message could be received and a timeout occurred

Throws:

PubSubPlusClientException - if the message could not be received

PubSubPlusClientException.RequestInterruptedException - if the thread was interrupted while waiting for the next message; an interrupted flag is expected to be set on the thread in this case

Since:

1.0

receiveOrElse

InboundMessage receiveOrElse(MessageReceiver.InboundMessageSupplier supplierOfAlternativeResponse)

Request to receive a next message, when no message 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.0

receiverInfo

ManageableReceiver.DirectReceiverInfo 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

DirectMessageReceiver 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

<DirectMessageReceiver> CompletableFuture<DirectMessageReceiver> 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

startAsync

<DirectMessageReceiver> void startAsync(CompletionListener<DirectMessageReceiver> 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:

DirectMessageReceiver - 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