solace.messaging.publisher package

solace.messaging.publisher.direct_message_publisher module

This module contains classes for direct message publishers.

A direct message publisher must be created using solace.messaging.builder.direct_message_publisher_builder.DirectMessagePublisherBuilder. The DirectMessagePublisher instance is used to publish direct messages created by a solace.messaging.publisher.outbound_message.OutboundMessageBuilder. The topic (or destination) can be added when the message is a published.

The direct message publisher may also be use to publish simple messages containing only a bytearray or string payload.

class solace.messaging.publisher.direct_message_publisher.DirectMessagePublisher

Bases: MessagePublisher, ABC

A class that defines the interface to a publisher for direct (non-persisted) messages.

abstract is_ready() → bool

Checks if a publisher can publish messages.

Returns:: True if publisher can publish messages. False if publisher is prevented from sending messages including (e.g., full buffer or I/O problems).
Return type:: bool

abstract is_running() → bool

Checks if the process was successfully started and not stopped yet.

Returns:: False if process was not started or already stopped, True otherwise.
Return type:: bool

abstract is_terminated() → bool

Checks if message delivery process is terminated.

Returns:: True if message delivery process is terminated, False otherwise.
Return type:: bool

abstract is_terminating() → bool

Checks if message delivery process termination is on-going.

Returns:: True if message delivery process being terminated, but termination is not finished, False otherwise.
Return type:: bool

abstract notify_when_ready()

Makes a request to notify the application when the publisher is ready.

This method helps to overcome a race condition between the completion of the exception processing and the solace.messaging.publisher.message_publisher.MessagePublisher instance, subsequently becoming ready. While processing a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the overflow condition can be resolved by background publishing. At the end of the business logic to handle the PublisherOverflowError, applications can call notify_when_ready to be guaranteed to receive a subsequent PublisherReadinessListener.ready() callback.

Send outbound messages to the specified destination using a provided solace.messaging.builder.outbound_message.OutboundMessageBuilder instance. Alternatively, a bytearray or str payload can be passed to this method this API will creates a solace.messaging.core.message.Message instance to send.

Parameters:

message (bytearray, str, OutboundMessage) – The outbound message that can be an Outbound object, bytearray, or str.
destination (Topic) – The destination to add to the message.
additional_message_properties (Dict[str, Union[str, int, float, bool, dict,list, tuple, None, bytearray]]) – The additional properties to customize a particular message. Each key can be customer provided, or it can be a key from of type solace.messaging.config.solace_properties.message_properties, The value can either be a string or an integer or a float or a bool or a dict or list or a tuple or a None or a bytearray. additional_message_properties’s int type parameter can have minimum value as -9223372036854775808 and maximum value as 18446744073709551615

Raises:

PubSubPlusClientError – When the message cannot be send and retry attempts did not help in resolving problem.
PublisherOverflowError – Raised when the publisher sends messages faster than what the current I/O capabilities allow for or when internal buffering capabilities have been exceeded.
InvalidDataTypeError – Raised when additional_message_properties’s int type value is not in between the range of minimum value & maximum value

abstract set_publish_failure_listener(listener: PublishFailureListener)

Set the specified PublishFailureListener to listen for a provided instance of the publisher.

A solace.messaging.publisher.direct_message_publisher.PublishFailureListener is notified through it’s defined callback whenever a publish message attempt fails asynchronously.

Published messages can be queued for later transmission when the transport is flow-controlled. If queued messages cannot be published, the PublishFailureListener - if one is registered - is notified. The PubSub+ event broker can also reject messages which appear as rejection notices on the specified PublishFailureListener.

Parameters:: listener (PublishFailureListener) – The specified listener for publisher failures.

abstract set_publisher_readiness_listener(listener: PublisherReadinessListener)

Sets a solace.messaging.publisher.publisher_health_check.PublisherReadinessListener. Applications can implement the PublisherReadinessListener interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after a solace.messaging.publisher.message_publisher.MessagePublisher raises a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the application will call PublisherHealthCheck.notify_when_ready() to guarantee that a subsequent PublisherReadinessListener.ready() call is seen.

Parameters:: listener (PublisherReadinessListener) – A listener to observe the state of the publisher.

abstract set_termination_notification_listener(listener: TerminationNotificationListener)

Adds a listener to listen for non-recoverable lifecycle object interruption events.

Parameters:: listener – TerminationNotificationListener

abstract start() → LifecycleControl

Enables service regular duties. Before this method is called, service is considered off duty. In order to operate normally this method needs to be called on a service instance. If the service is already started, or starting, this operation has no effect.

Raises:

PubSubPlusClientError – When service start failed for some internal reason.
IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.

abstract start_async() → Future

Enables service regular duties. Before this method is called, service is considered off duty. In order to operate normally, this method needs to be called on a service instance. If the service is already started, or starting, this operation has no effect.

Returns:: An object that the application can use to determine when the service start has completed.
Return type:: concurrent.futures.Future
Raises:: IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.

abstract terminate(grace_period: int = 600000)

Disables regular duties of a service. If this service is already terminated or terminating, this operation has no effect. All attempts to use a service after termination is requested will be refused with an exception.

Parameters:

grace_period (int) – The positive integer grace period to use. The default is 600000ms.

Raises:

PubSubPlusClientError – When service termination failed for some internal reason.
IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.
IllegalArgumentError – If the grace_period is invalid.

abstract terminate_async(grace_period: int = 600000) → Future

Disables regular duties of a service. If this service is already terminated or terminating, this operation has no effect. All attempts to use a service after termination is requested will be refused with an exception.

Parameters:: grace_period (int) – The positive integer grace period to use. The default is 600000ms.
Returns:: An future object which the application can use to determine terminate completion.
Return type:: concurrent.futures.Future
Raises:: IllegalArgumentError – If the grace_period is invalid.

class solace.messaging.publisher.direct_message_publisher.FailedPublishEvent(message: OutboundMessage, destination: Destination, exception: PubSubPlusClientError, timestamp: int | None = None)

Bases: object

FailedPublishEvent carries the details of a failed attempt to publish.

When the application registers a solace.messaging.publisher.direct_message_publisher.PublishFailureListener. the listener will be informed of failures with a FailedPublishEvent containing:

Message: OutboundMessage that failed.
Destination: The topic of the message.
Exception: The exception that occurred on publish
Timestamp: The time of the failure.

get_destination() → Destination

Retrieves message destination (topic) on the failed message

Returns:: Destination associated with this instance of the FailedPublishEvent

get_exception() → PubSubPlusClientError

Retrieves exception associated with a given event

Returns:: Exception associated with this instance of the FailedPublishEvent

get_message() → OutboundMessage

Retrieves solace.messaging.publisher.outbound_message.OutboundMessage

Returns:: Message associated with this instance of the FailedPublishEvent

get_timestamp() → float

Retrieves the timestamp of the event

Returns:: Timestamp associated with this instance of the FailedPublsihEvent

class solace.messaging.publisher.direct_message_publisher.PublishFailureListener

Bases: ABC

Interface definition for a listener for publish failures.

abstract on_failed_publish(failed_publish_event: FailedPublishEvent)

Callback method executed when publish errors occur asynchronously.

Parameters:: failed_publish_event (FailedPublishEvent) – The publish event indicating a failure.

solace.messaging.publisher.message_publisher module

This module defines a message publisher.

class solace.messaging.publisher.message_publisher.MessagePublisher

Bases: LifecycleControl, AsyncLifecycleControl, PublisherHealthCheck, ABC

This is a base interface class that abstracts message publishing behavior.

abstract is_ready() → bool

Checks if a publisher can publish messages.

Returns:: True if publisher can publish messages. False if publisher is prevented from sending messages including (e.g., full buffer or I/O problems).
Return type:: bool

abstract is_running() → bool

Checks if the process was successfully started and not stopped yet.

Returns:: False if process was not started or already stopped, True otherwise.
Return type:: bool

abstract is_terminated() → bool

Checks if message delivery process is terminated.

Returns:: True if message delivery process is terminated, False otherwise.
Return type:: bool

abstract is_terminating() → bool

Checks if message delivery process termination is on-going.

Returns:: True if message delivery process being terminated, but termination is not finished, False otherwise.
Return type:: bool

abstract notify_when_ready()

Makes a request to notify the application when the publisher is ready.

This method helps to overcome a race condition between the completion of the exception processing and the solace.messaging.publisher.message_publisher.MessagePublisher instance, subsequently becoming ready. While processing a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the overflow condition can be resolved by background publishing. At the end of the business logic to handle the PublisherOverflowError, applications can call notify_when_ready to be guaranteed to receive a subsequent PublisherReadinessListener.ready() callback.

abstract set_publisher_readiness_listener(listener: PublisherReadinessListener)

Sets a solace.messaging.publisher.publisher_health_check.PublisherReadinessListener. Applications can implement the PublisherReadinessListener interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after a solace.messaging.publisher.message_publisher.MessagePublisher raises a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the application will call PublisherHealthCheck.notify_when_ready() to guarantee that a subsequent PublisherReadinessListener.ready() call is seen.

Parameters:: listener (PublisherReadinessListener) – A listener to observe the state of the publisher.

abstract set_termination_notification_listener(listener: TerminationNotificationListener)

Adds a listener to listen for non-recoverable lifecycle object interruption events.

Parameters:: listener – TerminationNotificationListener

abstract start() → LifecycleControl

Enables service regular duties. Before this method is called, service is considered off duty. In order to operate normally this method needs to be called on a service instance. If the service is already started, or starting, this operation has no effect.

Raises:

PubSubPlusClientError – When service start failed for some internal reason.
IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.

abstract start_async() → Future

Enables service regular duties. Before this method is called, service is considered off duty. In order to operate normally, this method needs to be called on a service instance. If the service is already started, or starting, this operation has no effect.

Returns:: An object that the application can use to determine when the service start has completed.
Return type:: concurrent.futures.Future
Raises:: IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.

abstract terminate(grace_period: int = 600000)

Disables regular duties of a service. If this service is already terminated or terminating, this operation has no effect. All attempts to use a service after termination is requested will be refused with an exception.

Parameters:

grace_period (int) – The positive integer grace period to use. The default is 600000ms.

Raises:

PubSubPlusClientError – When service termination failed for some internal reason.
IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.
IllegalArgumentError – If the grace_period is invalid.

abstract terminate_async(grace_period: int = 600000) → Future

Disables regular duties of a service. If this service is already terminated or terminating, this operation has no effect. All attempts to use a service after termination is requested will be refused with an exception.

Parameters:: grace_period (int) – The positive integer grace period to use. The default is 600000ms.
Returns:: An future object which the application can use to determine terminate completion.
Return type:: concurrent.futures.Future
Raises:: IllegalArgumentError – If the grace_period is invalid.

solace.messaging.publisher.outbound_message module

This module contains classes for an outbound message and the interface definition for a builder for an outbound message.

class solace.messaging.publisher.outbound_message.OutboundMessage

Bases: Message, ABC

An abstract class that defines the interface for an outbound message.

An instance OutboundMessage can be created using a solace.messaging.publisher.outbound_message.OutboundMessageBuilder instance.

abstract get_application_message_id()

Gets an optional application message identifier when sender application sets one.

Returns:: Sender application identifier if set by message publisher, or None/empty if not set.
Return type:: str

abstract get_application_message_type()

Gets the application message type. This value is used by applications only, and is passed through the API unmodified.

Returns:: Application message type or None if not set.
Return type:: str

abstract get_class_of_service() → int | None

Retrieves the class of service level of a given message. This feature is only relevant. for direct messaging. If no class of service is set, the message is given a default class of service of 0.

Returns:: An integer between 0 and 2, inclusive, representing the class of service of the message.
Return type:: (int)
Raises:: PubSubPlusClientError – If an error was encountered while trying to retrieve the class of service of the message.

abstract get_correlation_id() → str | None

Retrieves the correlation ID from the message. The correlation ID is user-defined, carried end-to-end, and can also be matched in a selector, but otherwise is not relevant to the event broker. The correlation ID may be used for peer-to-peer message synchronization. In JMS applications this field is carried as the JMSCorrelationID Message Header Field.

Returns:: A unique identifier for the message set by producer or None.
Return type:: str

abstract get_expiration() → int | None

Retrieves the expiration time.

The expiration time is the UTC time (in ms, from midnight, January 1, 1970 UTC) when the message is considered expired. A value of 0 means the message never expires. The default value is 0.

Returns:: The UTC time when the message is discarded or moved to a Dead Message Queue by the PubSub+ broker or None if it was not set.
Return type:: int

abstract get_payload_as_bytes() → bytearray | None

Retrieves the payload of the message.

Returns:: the byte array with the message payload or None if there is no payload.
Return type:: bytearray

abstract get_payload_as_dictionary() → Dict | None

Retrieves the dictionary format of payload of message.

PubSub+ messages can be published with a SDTMap payload. This is a platform-agnostic dictionary format that allows data types to be sent and received in messages that is independent of the publisher or consumer applications.

Returns:

dictionary found in the payload or None if there is no payload, or the payload is not a: dictionary

Return type:

dict

Raises:

PubSubPlusCoreClientError – Raises when there is an internal error
SolaceSDTError – Raises when unsupported data type is received

abstract get_payload_as_list() → List | None

Retrieves the list format of payload of message.

PubSub+ messages can be published with a SDTStream payload. This is a platform-agnostic list format that allows data types to be sent and received in messages that is independent of the publisher or consumer applications.

Returns:

list found in the payload or None if there is no payload, or the payload is not a List

Return type:

list

Raises:

PubSubPlusCoreClientError – Raises when there is an internal error
SolaceSDTError – Raises when unsupported data type is received

abstract get_payload_as_string() → str | None

Retrieves the string-encoded payload of message.

PubSub+ messages can be published with a string-encoded payload. This is a platform-agnostic string format that allows strings to be sent and received in messages that is independent of the publisher or consumer applications. For example, in this way a non-Python publishing application can send a Unicode string that can still be consumed by a Python-based application.

If message payload is not specifically encoded as a string, it cannot be retrieved as a string. For instance, a publisher if the publisher sends a UTF-8 string as a bytearray, this method cannot be used to extract the string. Even though the payload is a string (str), it is not encoded to identify it as such.

Returns:: String found in the payload or None if there is no payload, or the payload is not a String.
Return type:: str

abstract get_priority() → int | None

Retrieves the priority value. Valid values range from 0 to 255.

Returns:: A priority value from 0 to 255, or None if the priority is not set.
Return type:: int
Raises:: PubSubPlusClientError – Any error if the priority of the message could not be retrieved.

Retrieves the non-solace properties attached to the message.

Any property defined in Message Properties is not returned in this dictionary. Solace defined property keys all begin with “solace.messaging”, however any key even those beginning with “solace.” may be a a non solace property if it is not defined in this API.

Message Properties are carried in Message meta data in addition to the Message payload. Properties are stored in a dictionary of key-value pairs where the key is controlled by the application.

Returns:: The non-solace properties attached to the message.
Return type:: dict

Retrieves The value of a specific non-solace property.

Any property defined in Message Properties is not available and this method will return None. Solace defined property keys all begin with “solace.messaging”, however any key even those beginning with “solace.” may be a a non solace property if it is not defined in this API.

Parameters:

name (str) – The name of the property.

Returns:

The value of the named property if found in the: message otherwise, returns None.

Return type:

str, int, float, bool, dict, list, bytearray, None

abstract get_rest_interoperability_support() → RestInteroperabilitySupport

Retrieves access to the optional metadata used for interoperability with REST messaging clients.

Returns:: The metadata collection or None if not set.
Return type:: RestInteroperabilitySupport

abstract get_sequence_number() → int | None

Gets the sequence number of the message.

Sequence numbers may be set by publisher applications or automatically generated by publisher APIs. The sequence number is carried in the Message meta data in addition to the payload and may be retrieved by consumer applications.

Returns:: The positive sequence number or None if it was not set.
Return type:: int

abstract has_property(name: str) → bool

Checks if the message has a specific non-solace property attached.

Any property defined in Message Properties is not available and this method will return false. Solace defined property keys all begin with “solace.messaging”, however any key even those beginning with “solace.” may be a a non solace property if it is not defined in this API.

Parameters:: name (str) – the name of the property.
Returns:: True if the property is present. False otherwise.

class solace.messaging.publisher.outbound_message.OutboundMessageBuilder

Bases: PropertyBasedConfiguration

This builder is used for building outbound messages which are published using solace.messaging.publisher.message_publisher.MessagePublisher.

Builds a solace.messaging.publisher.outbound_message.OutboundMessage instance with the specified payload. The payload must be a bytearray or str; if it is not, you must specify a solace.messaging.utils.converter.ObjectToBytes that converts the object to a bytearray.

Message properties may be set on each build.

Parameters:

payload (T) – The payload to add to the message.
additional_message_properties (dict[str, Union[str, int, float, bool, dict, list, tuple, None, bytearray]]) –
The additional message properties to add to the message metadata. Each key can be customer provided, or it can be a key from Message Properties. The key for the property is a string.

The value can either be a string or an integer or a float or a bool or a dict or list or a tuple or a bytearray or None. When value is an integer, the minimum value is -9223372036854775808 and maximum value is 18446744073709551615.
converter (ObjectToBytes) – The converter to convert the payload object to bytearray.

Raises:

InvalidDataTypeError – Raised when additional_message_properties’s int type value is not in between the range of minimum value & maximum value

Returns:

An outbound message object.

Return type:

OutboundMessage

Adds user properties/Solace defined properties to the message. User properties are carried in the message metadata as key-value pairs.For Solace defined properties the value must be valid data type for the respective key

Parameters:

configuration (Dict[str, Union[str, int, float, bool, dict, list, tuple, None, bytearray]]) –

The message attributes dictionary,it can have the key as string. Each key can be customer provided, or it can be a key from Message Properties.

The value can either be a string or an integer or a float or a bool or a dict or list or a tuple or a bytearray or None. When value is an integer, the minimum value is -9223372036854775808 and maximum value is 18446744073709551615.

Raises:

InvalidDataTypeError – Raised when additional_message_properties’s int type value is not in between the range of minimum value & maximum value

Returns:

A builder object representing an outbound message object for method chaining.

Return type:

OutboundMessageBuilder

abstract with_application_message_id(application_message_id: str) → OutboundMessageBuilder

Sets the application message identifier for a message from a string or None (to delete it).

The application message identifier is carried in the message metadata. It is used for application to application signaling.

Parameters:: application_message_id (str) – The application identifier.
Returns:: A builder object representing an outbound message object for method chaining.
Return type:: OutboundMessageBuilder

abstract with_application_message_type(application_message_type: str) → OutboundMessageBuilder

Sets the application message type for a message using a string or None (to delete).

The Application Message type is carried in the message meta data. It is used for application to application signaling.

Parameters:: application_message_type (str) – The application message type.
Returns:: A builder object representing an outbound message object for method chaining.
Return type:: OutboundMessageBuilder

abstract with_correlation_id(correlation_id: str) → OutboundMessageBuilder

Sets the correlation ID for the message. The correlation ID is user-defined, carried end-to-end, and can also be matched in a selector, but otherwise not relevent to the event broker. The correlation ID may be used for peer-to-peer message synchronization. In JMS applications this field is carried as the JMSCorrelationID Message Header Field.

Parameters:: correlation_id (str) – The correlation ID to be set
Raises:: InvalidDataTypeError – If the passed correlation_id is not a string.
Returns:: A builder object representing an outbound message object for method chaining.
Return type:: OutboundMessageBuilder

abstract with_expiration(timestamp: int) → OutboundMessageBuilder

Sets message expiration time.

Parameters:: timestamp (int) – The timestamp in milliseconds (Unix Epoch time), or None (to delete).
Returns:: A builder object representing an outbound message object for method chaining.
Return type:: OutboundMessageBuilder

abstract with_http_content_header(content_type: str, content_encoding: str) → OutboundMessageBuilder

Sets the HTTP content-type and HTTP content-encoding for a message.

For interoperability with REST clients, it may be necessary to set the HTTP content-type and HTTP content-encoding parameters.

Parameters:

content_type (str) – The expected and valid HTTP content-type.
content_encoding (str) – The expected and valid HTTP content-encoding

Returns:

A builder object representing an outbound message object for method chaining.

Return type:

OutboundMessageBuilder

abstract with_priority(priority: int) → OutboundMessageBuilder

Sets the priority (0 to 9), where zero is the lowest priority. If the priority is set to a value larger than 9, it’s treated as a 9 (the highest priority possible).

Parameters:: priority (OutboundMessageBuilder.Priority) – The priority of the outbound message.
Returns:: A builder object representing an outbound message object for method chaining.
Return type:: OutboundMessageBuilder

Adds the user property/Solace defined property with the given key and value. For Solace defined property the value must be valid data type for the given key

Parameters:

property_key (str) – The key for the configuration. Each key can be customer provided, or it can be a key from Message Properties.
property_value (Union[str, int, float, bool, dict, list, tuple, None, bytearray]) – The value for the key, it can be a string or an integer or a float or a bool or a dict or list or a tuple or a bytearray or None. When value is an integer, the minimum value is -9223372036854775808 and maximum value is 18446744073709551615.

Raises:

InvalidDataTypeError – Raised when additional_message_properties’s int type value is not in between the range of minimum value & maximum value

Returns:

A builder object representing an outbound message object for method chaining.

Return type:

OutboundMessageBuilder

abstract with_sender_id(sender_id: str | None) → OutboundMessageBuilder

Sets the sender ID for a message from a string, or deletes it if None is passed. Note: if GENERATE_SENDER_ID is enabled on the messaging service, then passing a string to this method will override the API generated sender ID, but passing None to this method will not override the API generated sender ID.

The sender ID is carried in the message metadata. It is used to identify the sender of the message.

Parameters:: sender_id (str) – The sender ID.
Returns:: A builder object representing an outbound message object for method chaining.
Return type:: OutboundMessageBuilder

abstract with_sequence_number(sequence_number: int) → OutboundMessageBuilder

Sets the sequence number for the message.

The sequence number is carried in the message meta data. It is used for application to application signaling.

Parameters:: sequence_number (int) – The expected integer value.
Returns:: A builder object representing an outbound message object for method chaining.
Return type:: OutboundMessageBuilder

solace.messaging.publisher.persistent_message_publisher module

Module that contains Persistent Message Publisher.

A Persistent Message Publisher must be created by solace.messaging.builder.persistent_message_publisher_builder.PersistentMessagePublisherBuilder. The PersistentMessagePublisher instance is used to publish Guaranteed Messages created by a solace.messaging.publisher.outbound_message.OutboundMessageBuilder. The Topic (or destination) can be added once the message is a published.

The persistent message publisher can also be used to publish simple messages containing only a bytearray or string payload.

class solace.messaging.publisher.persistent_message_publisher.MessagePublishReceiptListener

Bases: ABC

Message publish listener interface to process broker message publish notifications (success/failure).

abstract on_publish_receipt(publish_receipt: PublishReceipt)

On publish, sends the publish receipt.

Parameters:: publish_receipt (PublishReceipt) – The object to indicate that publish was done.

class solace.messaging.publisher.persistent_message_publisher.PersistentMessagePublisher

Bases: MessagePublisher, ABC

A class that defines the interface to a publisher for persistent messages.

Note

The PublishReceipt is available asynchronously via solace.messaging.publisher.persistent_message_publisher.MessagePublishReceiptListener. Message correlation tokens are used to PublishReceipt.

Alternatively, applications can get publish confirmation by publishing with the synchronous method PersistentMessagePublisher.publish_await_acknowledgement() method that does not return until the published message has been acknowledged by the PubSub+ event broker.

abstract is_ready() → bool

Checks if a publisher can publish messages.

Returns:: True if publisher can publish messages. False if publisher is prevented from sending messages including (e.g., full buffer or I/O problems).
Return type:: bool

abstract is_running() → bool

Checks if the process was successfully started and not stopped yet.

Returns:: False if process was not started or already stopped, True otherwise.
Return type:: bool

abstract is_terminated() → bool

Checks if message delivery process is terminated.

Returns:: True if message delivery process is terminated, False otherwise.
Return type:: bool

abstract is_terminating() → bool

Checks if message delivery process termination is on-going.

Returns:: True if message delivery process being terminated, but termination is not finished, False otherwise.
Return type:: bool

abstract notify_when_ready()

Makes a request to notify the application when the publisher is ready.

This method helps to overcome a race condition between the completion of the exception processing and the solace.messaging.publisher.message_publisher.MessagePublisher instance, subsequently becoming ready. While processing a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the overflow condition can be resolved by background publishing. At the end of the business logic to handle the PublisherOverflowError, applications can call notify_when_ready to be guaranteed to receive a subsequent PublisherReadinessListener.ready() callback.

Sends and outbound message to the given destination.

The solace.messaging.builder.outbound_message.OutboundMessageBuilder can be used to create the OutboundMessage instance. Alternatively, a bytearray or string payload can be passed to this function and the API will create a solace.messaging.core.message.Message to send.

Parameters:

message – (bytearray, str, OutboundMessage): The message or the or payload to publish.
destination – (Topic): The destination to add to the message.
user_context – (Any): the context associated with an action that is performed when the message delivery to the broker is confirmed using MessagePublishReceiptListener.on_publish_receipt() When the user-context is not supposed to be available, use the method instead without the user_context parameter.
additional_message_properties – (Dict[str, Union[str, int, float, bool, dict, list, tuple, None, bytearray]]): The additional message properties to add to the message metadata.Each key can be customer provided, or it can be a key from of type solace.messaging.config.solace_properties.message_properties. The key for the configuration is a string, the value can either be a string or an integer or a float or a bool or a dict or list or a tuple or a None or a bytearray. property_value’s int type parameter can have minimum value as -9223372036854775808 and maximum value as 18446744073709551615

Raises:

PubSubPlusClientError – When message can’t be send and retry attempts would not help.
PublisherOverflowError – When a publisher publishes messages faster then the I/O capabilities allow or internal message buffering capabilities are exceeded.
InvalidDataTypeError – Raised when additional_message_properties’s int type value is not in between the range of minimum value & maximum value

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

Parameters:

message – (bytearray, str, OutboundMessage): The message to send.
destination – (Topic): The message topic to send to, which is the message destination.
time_out – (int): The maximum time (in milliseconds) to wait for a message acknowledgement.
additional_message_properties – (Dict[str, Union[str, int, float, bool, dict, list, tuple, None, bytearray]]): The additional message properties to add to the message metadata.Each key can be customer provided, or it can be a key from of type solace.messaging.config.solace_properties.message_properties The key for the configuration is a string, the value can either be a string or an integer or a float or a bool or a dict or list or a tuple or a None or a bytearray. property_value’s int type parameter can have minimum value as -9223372036854775808 and maximum value as 18446744073709551615

Raises:

PubSubTimeoutError – After specified timeout when no-response received.
MessageRejectedByBrokerError – When a message was rejected from a broker for some reason.
PublisherOverflowError – When publisher publishes too fast, message can be republished immediately or after some time
MessageDestinationDoesNotExistError – When a given message destination does not exist.
MessageNotAcknowledgedByBrokerError – When a message broker could not acknowledge message persistence on an event broker.
PubSubPlusClientError – When some internal error occurs.
IllegalArgumentError – When the value of timeout is negative.
InvalidDataTypeError – Raised when additional_message_properties’s int type value is not in between the range of minimum value & maximum value

abstract set_message_publish_receipt_listener(listener: MessagePublishReceiptListener)

Sets the MessagePublishReceiptListener for the given instance of the publisher. It is used to handle broker message acknowledgement or broker message reject for all the messages published.

Parameters:: listener (MessagePublishReceiptListener) – A listener that handles message publish confirmations or message publish failures.

abstract set_publisher_readiness_listener(listener: PublisherReadinessListener)

Sets a solace.messaging.publisher.publisher_health_check.PublisherReadinessListener. Applications can implement the PublisherReadinessListener interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after a solace.messaging.publisher.message_publisher.MessagePublisher raises a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the application will call PublisherHealthCheck.notify_when_ready() to guarantee that a subsequent PublisherReadinessListener.ready() call is seen.

Parameters:: listener (PublisherReadinessListener) – A listener to observe the state of the publisher.

abstract set_termination_notification_listener(listener: TerminationNotificationListener)

Adds a listener to listen for non-recoverable lifecycle object interruption events.

Parameters:: listener – TerminationNotificationListener

abstract start() → LifecycleControl

Enables service regular duties. Before this method is called, service is considered off duty. In order to operate normally this method needs to be called on a service instance. If the service is already started, or starting, this operation has no effect.

Raises:

PubSubPlusClientError – When service start failed for some internal reason.
IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.

abstract start_async() → Future

Enables service regular duties. Before this method is called, service is considered off duty. In order to operate normally, this method needs to be called on a service instance. If the service is already started, or starting, this operation has no effect.

Returns:: An object that the application can use to determine when the service start has completed.
Return type:: concurrent.futures.Future
Raises:: IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.

abstract terminate(grace_period: int = 600000)

Disables regular duties of a service. If this service is already terminated or terminating, this operation has no effect. All attempts to use a service after termination is requested will be refused with an exception.

Parameters:

grace_period (int) – The positive integer grace period to use. The default is 600000ms.

Raises:

PubSubPlusClientError – When service termination failed for some internal reason.
IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.
IllegalArgumentError – If the grace_period is invalid.

abstract terminate_async(grace_period: int = 600000) → Future

Disables regular duties of a service. If this service is already terminated or terminating, this operation has no effect. All attempts to use a service after termination is requested will be refused with an exception.

Parameters:: grace_period (int) – The positive integer grace period to use. The default is 600000ms.
Returns:: An future object which the application can use to determine terminate completion.
Return type:: concurrent.futures.Future
Raises:: IllegalArgumentError – If the grace_period is invalid.

class solace.messaging.publisher.persistent_message_publisher.PublishReceipt(message: OutboundMessage, exception: PubSubPlusClientError, time_stamp: int, persisted: bool, user_context: object | None = None)

Bases: object

Encapsulates broker acknowledgement or failed publishing attempt details, used for message publish notification processing such as timestamp, correlation token, original message, indicator if message was persisted on a broker, exception if any.

property exception: PubSubPlusClientError

Gets exception if any, indicating failure case

Returns:: not None value indicates failure by publishing to the broker or during persistence on a broker

property is_persisted: bool

Gets information if message reached a broker and persistence confirmation was received back

Returns:: true if broker confirmed that message is received and persisted, false otherwise

property message: OutboundMessage

Retrieves message associated with a Receipt

Returns:: message associated with this instance of the Receipt

property time_stamp: int

Retrieves the timestamp associated with the Receipt, The number of milliseconds from the epoch of 1970-01-01T00:00:00Z

Returns:: int value of the timestamp

property user_context: object

Retrieve the context associated with an action if provided during publishing

Returns:: context associated with broker publish confirmation action or None if there is nothing.

solace.messaging.publisher.publisher_health_check module

This module provides an interface for readiness checks on a solace.messaging.publisher.message_publisher.MessagePublisher object.

class solace.messaging.publisher.publisher_health_check.PublisherHealthCheck

Bases: ABC

An abstract class that defines the interfaces for readiness checks on a solace.messaging.publisher.message_publisher.MessagePublisher.

abstract is_ready() → bool

Checks if a publisher can publish messages.

Returns:: True if publisher can publish messages. False if publisher is prevented from sending messages including (e.g., full buffer or I/O problems).
Return type:: bool

abstract notify_when_ready()

Makes a request to notify the application when the publisher is ready.

This method helps to overcome a race condition between the completion of the exception processing and the solace.messaging.publisher.message_publisher.MessagePublisher instance, subsequently becoming ready. While processing a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the overflow condition can be resolved by background publishing. At the end of the business logic to handle the PublisherOverflowError, applications can call notify_when_ready to be guaranteed to receive a subsequent PublisherReadinessListener.ready() callback.

abstract set_publisher_readiness_listener(listener: PublisherReadinessListener)

Sets a solace.messaging.publisher.publisher_health_check.PublisherReadinessListener. Applications can implement the PublisherReadinessListener interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after a solace.messaging.publisher.message_publisher.MessagePublisher raises a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the application will call PublisherHealthCheck.notify_when_ready() to guarantee that a subsequent PublisherReadinessListener.ready() call is seen.

Parameters:: listener (PublisherReadinessListener) – A listener to observe the state of the publisher.

class solace.messaging.publisher.publisher_health_check.PublisherReadinessListener

Bases: ABC

An abstract class that defines the interface for receiving publisher ready notification

Interested applications can call PublisherHealthCheck.notify_when_ready() to request a ready notification. Subsequent to this, when the publisher is ready to publish messages the ready() method is called.

abstract ready()

Executes when the publisher is in a state when it can publish.

After a failure to publish due to solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError. The API will always call ready() when the Publisher Overflow condition has eased. This can lead to race conditions and synchronization issues with the publisher thread, if the publisher thread is still processing the exception.

Consequently, the publisher thread can always use PublisherHealthCheck.notify_when_ready() to request a ready() callback that is guaranteed to occur subsequent to the notify request.

Note

This ready() method is executed on a thread separate from the publisher thread.

solace.messaging.publisher.request_reply_message_publisher module

A Request Message Publisher must be created by solace.messaging.builder.request_reply_message_publisher_builder.RequestReplyMessagePublisherBuilder.The RequestReplyMessagePublisher instance is used to send request-reply messages created by a solace.messaging.publisher.outbound_message.OutboundMessageBuilder. Topic (destination) must be specified when the message is published.

class solace.messaging.publisher.request_reply_message_publisher.RequestReplyMessagePublisher

Bases: MessagePublisher, ABC

An interface that abstracts message request publishing feature for request-reply messaging using direct messaging paradigm Request destination is specified at publisher time

abstract is_ready() → bool

Checks if a publisher can publish messages.

Returns:: True if publisher can publish messages. False if publisher is prevented from sending messages including (e.g., full buffer or I/O problems).
Return type:: bool

abstract is_running() → bool

Checks if the process was successfully started and not stopped yet.

Returns:: False if process was not started or already stopped, True otherwise.
Return type:: bool

abstract is_terminated() → bool

Checks if message delivery process is terminated.

Returns:: True if message delivery process is terminated, False otherwise.
Return type:: bool

abstract is_terminating() → bool

Checks if message delivery process termination is on-going.

Returns:: True if message delivery process being terminated, but termination is not finished, False otherwise.
Return type:: bool

abstract notify_when_ready()

Makes a request to notify the application when the publisher is ready.

This method helps to overcome a race condition between the completion of the exception processing and the solace.messaging.publisher.message_publisher.MessagePublisher instance, subsequently becoming ready. While processing a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the overflow condition can be resolved by background publishing. At the end of the business logic to handle the PublisherOverflowError, applications can call notify_when_ready to be guaranteed to receive a subsequent PublisherReadinessListener.ready() callback.

Sends a request for reply message; nonblocking

No correlation id is required to be provided, correlation is handled internally by API

Parameters:

request_message – request message to be sent
request_destination – destination for request messages
reply_timeout – wait time in ms to get a reply message. Timeout has to be a positive integer value, and must be be passed since there is no default value.
additional_message_properties – (Dict[str, Union[str, int, float, bool, dict, list, tuple, None, bytearray]]): The additional message properties to add to the message metadata.Each key can be customer provided, or it can be a key from of type solace.messaging.config.solace_properties.message_properties. The key for the configuration is a string, the value can either be a string or an integer or a float or a bool or a dict or list or a tuple or a None or a bytearray. property_value’s int type parameter can have minimum value as -9223372036854775808 and maximum value as 18446744073709551615

Returns:

A future object that can be used to retrieve the reply message after is has been received.

Sends a request message return response message, blocking until response is received or timeout occurs

Parameters:

request_message – request message to be sent
request_destination – destination for request messages
reply_timeout – wait time in ms to get a reply message. Timeout has to be a positive integer value, and must be passed since there is no default value.
additional_message_properties – (Dict[str, Union[str, int, float, bool, dict, list, tuple, None, bytearray]]): The additional message properties to add to the message metadata.Each key can be customer provided, or it can be a key from of type solace.messaging.config.solace_properties.message_properties. The key for the configuration is a string, the value can either be a string or an integer or a float or a bool or a dict or list or a tuple or a None or a bytearray. property_value’s int type parameter can have minimum value as -9223372036854775808 and maximum value as 18446744073709551615

Returns:

response message when any received

Raises:

PubSubTimeoutError – if response from a replier does not come on time
MessageRejectedByBrokerError – if broker is rejecting messages from a publisher(only when service interruption listener available , warning log will be emitted)
PubSubPlusClientError – if some internal error occurs
IllegalArgumentError – if the value of timeout is negative
InvalidDataTypeError – if the value of timeout is None also when additional_message_properties’s int
type value is not in between the range of minimum value & maximum value –

abstract set_publisher_readiness_listener(listener: PublisherReadinessListener)

Sets a solace.messaging.publisher.publisher_health_check.PublisherReadinessListener. Applications can implement the PublisherReadinessListener interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after a solace.messaging.publisher.message_publisher.MessagePublisher raises a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the application will call PublisherHealthCheck.notify_when_ready() to guarantee that a subsequent PublisherReadinessListener.ready() call is seen.

Parameters:: listener (PublisherReadinessListener) – A listener to observe the state of the publisher.

abstract set_termination_notification_listener(listener: TerminationNotificationListener)

Adds a listener to listen for non-recoverable lifecycle object interruption events.

Parameters:: listener – TerminationNotificationListener

abstract start() → LifecycleControl

Enables service regular duties. Before this method is called, service is considered off duty. In order to operate normally this method needs to be called on a service instance. If the service is already started, or starting, this operation has no effect.

Raises:

PubSubPlusClientError – When service start failed for some internal reason.
IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.

abstract start_async() → Future

Enables service regular duties. Before this method is called, service is considered off duty. In order to operate normally, this method needs to be called on a service instance. If the service is already started, or starting, this operation has no effect.

Returns:: An object that the application can use to determine when the service start has completed.
Return type:: concurrent.futures.Future
Raises:: IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.

abstract terminate(grace_period: int = 600000)

Disables regular duties of a service. If this service is already terminated or terminating, this operation has no effect. All attempts to use a service after termination is requested will be refused with an exception.

Parameters:

grace_period (int) – The positive integer grace period to use. The default is 600000ms.

Raises:

PubSubPlusClientError – When service termination failed for some internal reason.
IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.
IllegalArgumentError – If the grace_period is invalid.

abstract terminate_async(grace_period: int = 600000) → Future

Disables regular duties of a service. If this service is already terminated or terminating, this operation has no effect. All attempts to use a service after termination is requested will be refused with an exception.

Parameters:: grace_period (int) – The positive integer grace period to use. The default is 600000ms.
Returns:: An future object which the application can use to determine terminate completion.
Return type:: concurrent.futures.Future
Raises:: IllegalArgumentError – If the grace_period is invalid.

solace.messaging.publisher.transactional_message_publisher module

This module contains the TramsactionalMessagePublisher class.

A transactional message publisher must be created using solace.messaging.builder.transactional_message_publisher_builder.TransactionalMessagePublisherBuilder. The TransactionalMessagePublisher instance is used to publish messages created by a solace.messaging.publisher.outbound_message.OutboundMessageBuilder on the transacted session. The topic (or destination) can be added when the message is a published.

The transactional message publisher may also be used to publish simple messages containing only a bytearray or string payload.

class solace.messaging.publisher.transactional_message_publisher.TransactionalMessagePublisher

Bases: MessagePublisher, ABC

An interface for publishing transactional messages.

abstract is_ready() → bool

Checks if a publisher can publish messages.

Returns:: True if publisher can publish messages. False if publisher is prevented from sending messages including (e.g., full buffer or I/O problems).
Return type:: bool

abstract is_running() → bool

Checks if the process was successfully started and not stopped yet.

Returns:: False if process was not started or already stopped, True otherwise.
Return type:: bool

abstract is_terminated() → bool

Checks if message delivery process is terminated.

Returns:: True if message delivery process is terminated, False otherwise.
Return type:: bool

abstract is_terminating() → bool

Checks if message delivery process termination is on-going.

Returns:: True if message delivery process being terminated, but termination is not finished, False otherwise.
Return type:: bool

abstract notify_when_ready()

Makes a request to notify the application when the publisher is ready.

This method helps to overcome a race condition between the completion of the exception processing and the solace.messaging.publisher.message_publisher.MessagePublisher instance, subsequently becoming ready. While processing a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the overflow condition can be resolved by background publishing. At the end of the business logic to handle the PublisherOverflowError, applications can call notify_when_ready to be guaranteed to receive a subsequent PublisherReadinessListener.ready() callback.

Sends {@link OutboundMessage} to the given destination {@link OutboundMessageBuilder} can be used to create a new message instance.

Parameters:

message – (bytearray, str, OutboundMessage): The message or the or payload to publish.
destination – (Topic): The destination to add to the message.
additional_message_properties – (Dict[str, Union[str, int, float, bool, dict, list, tuple, None, bytearray]]): The additional message properties to add to the message metadata.Each key can be customer provided, or it can be a key from of type solace.messaging.config.solace_properties.message_properties. The key for the configuration is a string, the value can either be a string or an integer or a float or a bool or a dict or list or a tuple or a None or a bytearray. property_value’s int type parameter can have minimum value as -9223372036854775808 and maximum value as 18446744073709551615

Raises:

PubSubPlusClientError – When message can’t be send and retry attempts would not help.
PublisherOverflowError – When a publisher publishes messages faster than the I/O capabilities allow or internal message buffering capabilities are exceeded.
InvalidDataTypeError – Raised when additional_message_properties’s int type value is not in between the range of minimum value & maximum value

abstract set_publisher_readiness_listener(listener: PublisherReadinessListener)

Sets a solace.messaging.publisher.publisher_health_check.PublisherReadinessListener. Applications can implement the PublisherReadinessListener interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after a solace.messaging.publisher.message_publisher.MessagePublisher raises a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError, the application will call PublisherHealthCheck.notify_when_ready() to guarantee that a subsequent PublisherReadinessListener.ready() call is seen.

Parameters:: listener (PublisherReadinessListener) – A listener to observe the state of the publisher.

abstract set_termination_notification_listener(listener: TerminationNotificationListener)

Adds a listener to listen for non-recoverable lifecycle object interruption events.

Parameters:: listener – TerminationNotificationListener

abstract start() → LifecycleControl

Enables service regular duties. Before this method is called, service is considered off duty. In order to operate normally this method needs to be called on a service instance. If the service is already started, or starting, this operation has no effect.

Raises:

PubSubPlusClientError – When service start failed for some internal reason.
IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.

abstract start_async() → Future

Enables service regular duties. Before this method is called, service is considered off duty. In order to operate normally, this method needs to be called on a service instance. If the service is already started, or starting, this operation has no effect.

Returns:: An object that the application can use to determine when the service start has completed.
Return type:: concurrent.futures.Future
Raises:: IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.

abstract terminate(grace_period: int = 600000)

Disables regular duties of a service. If this service is already terminated or terminating, this operation has no effect. All attempts to use a service after termination is requested will be refused with an exception.

Parameters:

grace_period (int) – The positive integer grace period to use. The default is 600000ms.

Raises:

PubSubPlusClientError – When service termination failed for some internal reason.
IllegalStateError – If method has been invoked at an illegal or inappropriate time for some another reason.
IllegalArgumentError – If the grace_period is invalid.

abstract terminate_async(grace_period: int = 600000) → Future

Disables regular duties of a service. If this service is already terminated or terminating, this operation has no effect. All attempts to use a service after termination is requested will be refused with an exception.

Parameters:: grace_period (int) – The positive integer grace period to use. The default is 600000ms.
Returns:: An future object which the application can use to determine terminate completion.
Return type:: concurrent.futures.Future
Raises:: IllegalArgumentError – If the grace_period is invalid.