com.solace.messaging.publisher

Interface PersistentMessagePublisher

All Superinterfaces:

AsyncLifecycleControl, LifecycleControl, ManageablePublisher, MessagePublisher, PublisherHealthCheck

@ProviderType
public interface PersistentMessagePublisher
extends MessagePublisher

An interface to create and interact with persistent message publishers.

Note: Due to the nature how the broker's confirmation receipts are sent, PersistentMessagePublisher.PublishReceipt is always available asynchronously only. Message correlation tokens are used to track broker responses.

Since:

1.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	PersistentMessagePublisher.MessagePublishReceiptListener An interface for listeners that process notifications about message delivered to the broker (success or failures).
static class	PersistentMessagePublisher.PublishReceipt A class that encapsulates broker acknowledgement or failed publishing attempts, used for message delivery notification processing such as timestamp, correlation token, original message, indicator if message was persisted on a broker.

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

LifecycleControl.TerminationEvent, LifecycleControl.TerminationNotificationListener

Nested classes/interfaces inherited from interface com.solace.messaging.publisher.PublisherHealthCheck

PublisherHealthCheck.PublisherReadinessListener

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

ManageablePublisher.DirectPublisherInfo, ManageablePublisher.PersistentPublisherInfo, ManageablePublisher.PublisherInfo

Method Summary

Modifier and Type	Method and Description
void	publish(byte[] message, Topic destination) Sends a persistent byte-array message to the given destination using defaults.
void	publish(byte[] message, Topic destination, Object userContext) Sends a persistent byte array message to the given destination using defaults.
void	publish(OutboundMessage message, Topic destination) Sends a persistent message; nonblocking
void	publish(OutboundMessage message, Topic destination, Object userContext) Sends a persistent message to the given destination, non blocking
void	publish(OutboundMessage message, Topic destination, Object userContext, Properties additionalMessageProperties) Sends a persistent message to the given destination, non-blocking
void	publish(String message, Topic destination) Sends a UTF-8 encoded persistent text message as a payload to the given destination using defaults.
void	publish(String message, Topic destination, Object userContext) Sends a UTF-8 encoded persistent text message as the payload to the given destination using defaults.
void	publishAwaitAcknowledgement(OutboundMessage message, Topic destination, long timeout) Sends a persistent message, blocking until delivery acknowledgement is received or timeout occurs.
void	publishAwaitAcknowledgement(OutboundMessage message, Topic destination, long timeout, Properties additionalMessageProperties) Sends a persistent message, blocking until delivery acknowledgement is received or timeout occurs
ManageablePublisher.PersistentPublisherInfo	publisherInfo() Provides access to the publisher information.
void	setMessagePublishReceiptListener(PersistentMessagePublisher.MessagePublishReceiptListener listener) Sets MessagePublishReceiptListener for the given instance of the publisher.
PersistentMessagePublisher	start() Enables service regular duties.
<PersistentMessagePublisher> CompletableFuture<PersistentMessagePublisher>	startAsync() Asynchronously starts service for consuming/publishing operations.
<PersistentMessagePublisher> void	startAsync(CompletionListener<PersistentMessagePublisher> startListener) Asynchronously starts service for consuming/publishing operations using a callback for completion notification.

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.publisher.PublisherHealthCheck

isReady, notifyWhenReady, setPublisherReadinessListener

Method Detail

publish

void publish(byte[] message,
             Topic destination)
      throws PubSubPlusClientException,
             IllegalStateException,
             IllegalArgumentException,
             PubSubPlusClientException.PublisherOverflowException

Sends a persistent byte-array message to the given destination using defaults. This method is non-blocking

Parameters:

message - the raw byte payload of the message to send

destination - the message destination (topic)

Throws:

PubSubPlusClientException - if the message cannot be sent and retry attempts would not help

PubSubPlusClientException.PublisherOverflowException - if the publisher sends messages faster then I/O capabilities allow for messages to be sent or internal message buffering capabilities have been exceeded

IllegalStateException - if the message publisher has not started or has been terminated

IllegalArgumentException - if the message or destination are null

Since:

1.0

publish

void publish(byte[] message,
             Topic destination,
             Object userContext)
      throws PubSubPlusClientException,
             IllegalStateException,
             IllegalArgumentException,
             PubSubPlusClientException.PublisherOverflowException

Sends a persistent byte array message to the given destination using defaults. The method is non-blocking.

Message acknowledgements are processed using separately registered PersistentMessagePublisher.MessagePublishReceiptListener calls.

Parameters:

message - the raw-byte payload of the message to send

destination - the message destination (topic)

userContext - the context associated with an action that is performed when the message delivery to the broker is confirmed using PersistentMessagePublisher.MessagePublishReceiptListener and PersistentMessagePublisher.PublishReceipt. When the user-context is not supposed to be available, use the method instead without the userContext parameter

Throws:

PubSubPlusClientException - if the message cannot be sent and retry attempts would not help

PubSubPlusClientException.PublisherOverflowException - if the publisher sends messages faster then I/O capabilities allow for messages to be sent or internal message buffering capabilities have been exceeded

IllegalStateException - if the message publisher has not started or has been terminated

IllegalArgumentException - if the message or destination are null

Since:

1.0

publish

void publish(OutboundMessage message,
             Topic destination)
      throws PubSubPlusClientException,
             IllegalStateException,
             IllegalArgumentException,
             PubSubPlusClientException.PublisherOverflowException

Sends a persistent message; nonblocking

Message acknowledgements processed using separately registered MessagePublishReceiptListener interface.

Parameters:

message - the message to send

destination - the message destination (topic)

Throws:

PubSubPlusClientException - when message can't be send and retry attempts would not help

PubSubPlusClientException - if the message cannot be sent and retry attempts would not help

PubSubPlusClientException.PublisherOverflowException - if the publisher sends messages faster then I/O capabilities allow for messages to be sent or internal message buffering capabilities have been exceeded

IllegalStateException - if the message publisher has not started or has been terminated

IllegalArgumentException - if the message or destination are null

Since:

1.0

publish

void publish(OutboundMessage message,
             Topic destination,
             Object userContext)
      throws PubSubPlusClientException,
             IllegalStateException,
             IllegalArgumentException,
             PubSubPlusClientException.PublisherOverflowException

Sends a persistent message to the given destination, non blocking

Message acknowledgements processed using separately registered PersistentMessagePublisher.MessagePublishReceiptListener

Parameters:

message - the message to send

destination - the message destination (topic)

userContext - the context associated with an action that is performed when the message delivery to the broker is confirmed using MessagePublishReceiptListener#onPublishReceipt(PublishReceipt). When the user-context is not supposed to be available, use the method instead without the userContext parameter

Throws:

PubSubPlusClientException - if the message cannot be sent and retry attempts would not help

PubSubPlusClientException.PublisherOverflowException - if the publisher sends messages faster then I/O capabilities allow for messages to be sent or internal message buffering capabilities have been exceeded

IllegalStateException - if the message publisher has not started or has been terminated

IllegalArgumentException - if the message or destination are null

Since:

1.0

publish

void publish(OutboundMessage message,
             Topic destination,
             Object userContext,
             Properties additionalMessageProperties)
      throws PubSubPlusClientException,
             IllegalStateException,
             IllegalArgumentException,
             PubSubPlusClientException.PublisherOverflowException

Sends a persistent message to the given destination, non-blocking

Message acknowledgements processed using separately registered PersistentMessagePublisher.MessagePublishReceiptListener

Parameters:

message - the message to send

destination - the message destination (topic)

userContext - the context associated with an action that is performed when the message delivery to the broker is confirmed using MessagePublishReceiptListener#onPublishReceipt(PublishReceipt) When the user-context is not supposed to be available, use the method instead without the userContext parameter

additionalMessageProperties - additional properties (Key of type String and Value of type String), to customize a particular message, each key can be customer provided, or it can be a key from a SolaceProperties.MessageProperties

Throws:

PubSubPlusClientException - if the message cannot be sent and retry attempts would not help

PubSubPlusClientException.PublisherOverflowException - if the publisher sends messages faster then I/O capabilities allow for messages to be sent or internal message buffering capabilities have been exceeded

IllegalStateException - if the message publisher has not started or has been terminated

IllegalArgumentException - if the message or destination are null

Since:

1.0

publish

void publish(String message,
             Topic destination)
      throws PubSubPlusClientException,
             IllegalStateException,
             IllegalArgumentException,
             PubSubPlusClientException.PublisherOverflowException

Sends a UTF-8 encoded persistent text message as a payload to the given destination using defaults. This methods is non-blocking.

Message acknowledgements processed using separately registered PersistentMessagePublisher.MessagePublishReceiptListener interface.

Parameters:

message - string payload of the message to be send

destination - the message destination (topic)

Throws:

PubSubPlusClientException - if the message cannot be sent and retry attempts would not help

PubSubPlusClientException.PublisherOverflowException - if the publisher sends messages faster then I/O capabilities allow for messages to be sent or internal message buffering capabilities have been exceeded

IllegalStateException - if the message publisher has not started or has been terminated

IllegalArgumentException - if the message or destination are null

Since:

1.0

publish

void publish(String message,
             Topic destination,
             Object userContext)
      throws PubSubPlusClientException,
             IllegalStateException,
             IllegalArgumentException,
             PubSubPlusClientException.PublisherOverflowException

Sends a UTF-8 encoded persistent text message as the payload to the given destination using defaults. The method is non-blocking.

Message acknowledgements processed using separately registered PersistentMessagePublisher.MessagePublishReceiptListener interface.

Parameters:

message - the string-based payload of the message to send

destination - the message destination (topic)

userContext - the context associated with an action that is performed when the message delivery to the broker is confirmed using MessagePublishReceiptListener#onPublishReceipt(PublishReceipt). When the user-context is not supposed to be available, use the method instead without the userContext parameter

Throws:

PubSubPlusClientException - if the message cannot be sent and retry attempts would not help

PubSubPlusClientException.PublisherOverflowException - if the publisher sends messages faster then I/O capabilities allow for messages to be sent or internal message buffering capabilities have been exceeded

IllegalStateException - if the message publisher has not started or has been terminated

IllegalArgumentException - if the message or destination are null

Since:

1.0

publishAwaitAcknowledgement

void publishAwaitAcknowledgement(OutboundMessage message,
                                 Topic destination,
                                 long timeout)
                          throws PubSubPlusClientException.TimeoutException,
                                 PubSubPlusClientException.MessageRejectedByBrokerException,
                                 PubSubPlusClientException.PublisherOverflowException,
                                 PubSubPlusClientException.MessageDestinationDoesNotExistException,
                                 PubSubPlusClientException.MessageNotAcknowledgedByBrokerException,
                                 PubSubPlusClientException,
                                 InterruptedException

Sends a persistent message, blocking until delivery acknowledgement is received or timeout occurs.

Parameters:

message - the message to send

destination - the message destination (topic)

timeout - the maximum time to wait for the message acknowledgement (in milliseconds)

Throws:

PubSubPlusClientException.TimeoutException - if after the specified timeout has elapsed and no response has been received

PubSubPlusClientException.MessageRejectedByBrokerException - if the message was rejected from the broker for some reason

PubSubPlusClientException.PublisherOverflowException - if the publisher sends messages too fast; an attempt to re-publish the message immediately or after some time can be done

PubSubPlusClientException.MessageDestinationDoesNotExistException - if the specified message destination does not exist

PubSubPlusClientException.MessageNotAcknowledgedByBrokerException - if the broker could not acknowledge message persistence on a broker

PubSubPlusClientException - if some internal error occurred

IllegalArgumentException - if the value of timeout is negative

InterruptedException - if any thread has interrupted the current thread; the interrupted status of the current thread is cleared when this exception is thrown

Since:

1.0

publishAwaitAcknowledgement

void publishAwaitAcknowledgement(OutboundMessage message,
                                 Topic destination,
                                 long timeout,
                                 Properties additionalMessageProperties)
                          throws PubSubPlusClientException.TimeoutException,
                                 PubSubPlusClientException.MessageRejectedByBrokerException,
                                 PubSubPlusClientException.PublisherOverflowException,
                                 PubSubPlusClientException.MessageDestinationDoesNotExistException,
                                 PubSubPlusClientException.MessageNotAcknowledgedByBrokerException,
                                 PubSubPlusClientException,
                                 InterruptedException

Sends a persistent message, blocking until delivery acknowledgement is received or timeout occurs

Parameters:

message - the message to send

destination - the message destination (topic)

timeout - the maximum time to wait for the message acknowledgement (in milliseconds)

additionalMessageProperties - the additional properties (Key of type String and Value of type String) to customize a particular message where each key can be customer-provided, or it can be a key from a SolaceProperties.MessageProperties object

Throws:

PubSubPlusClientException.TimeoutException - if after the specified timeout has elapsed and no response has been received

PubSubPlusClientException.MessageRejectedByBrokerException - if the message was rejected from the broker for some reason

PubSubPlusClientException.PublisherOverflowException - if the publisher sends messages too fast; an attempt to re-publish the message immediately or after some time can be done

PubSubPlusClientException.MessageDestinationDoesNotExistException - if the specified message destination does not exist

PubSubPlusClientException.MessageNotAcknowledgedByBrokerException - if the broker could not acknowledge message persistence on the broker

PubSubPlusClientException - if some internal error occurred

IllegalArgumentException - if the value of timeout is negative

InterruptedException - if any thread has interrupted the current thread; the interrupted status of the current thread is cleared when this exception is thrown

Since:

1.0

publisherInfo

ManageablePublisher.PersistentPublisherInfo publisherInfo()

Description copied from interface: ManageablePublisher

Provides access to the publisher information.

Specified by:

publisherInfo in interface ManageablePublisher

Returns:

the publisher information as a PublisherInfo object

setMessagePublishReceiptListener

void setMessagePublishReceiptListener(PersistentMessagePublisher.MessagePublishReceiptListener listener)

Sets MessagePublishReceiptListener for the given instance of the publisher. It is used to notify about all messages published to the broker with corresponding confirmations or failures.

Parameters:

listener - the listener to process message publish confirmations or failures

Since:

1.0

start

PersistentMessagePublisher start()

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

Returns:

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

startAsync

<PersistentMessagePublisher> CompletableFuture<PersistentMessagePublisher> startAsync()
                                                                               throws PubSubPlusClientException

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

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

startAsync

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

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