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:
- 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:
- abstract is_terminated() bool
Checks if message delivery process is terminated.
- Returns:
True if message delivery process is terminated, False otherwise.
- Return type:
- 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:
- 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 asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the overflow condition can be resolved by background publishing. At the end of the business logic to handle thePublisherOverflowError
, applications can callnotify_when_ready
to be guaranteed to receive a subsequentPublisherReadinessListener.ready()
callback.
- abstract publish(message: bytearray | str | OutboundMessage, destination: Topic, additional_message_properties: Dict[str, str | int | float | bool | dict | list | tuple | bytearray | None] = None)
Send outbound messages to the specified
destination
using a providedsolace.messaging.builder.outbound_message.OutboundMessageBuilder
instance. Alternatively, abytearray
orstr
payload can be passed to this method this API will creates asolace.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 specifiedPublishFailureListener
.- 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 thePublisherReadinessListener
interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after asolace.messaging.publisher.message_publisher.MessagePublisher
raises asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the application will callPublisherHealthCheck.notify_when_ready()
to guarantee that a subsequentPublisherReadinessListener.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:
- 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:
- 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)
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
- 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:
- 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:
- abstract is_terminated() bool
Checks if message delivery process is terminated.
- Returns:
True if message delivery process is terminated, False otherwise.
- Return type:
- 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:
- 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 asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the overflow condition can be resolved by background publishing. At the end of the business logic to handle thePublisherOverflowError
, applications can callnotify_when_ready
to be guaranteed to receive a subsequentPublisherReadinessListener.ready()
callback.
- abstract set_publisher_readiness_listener(listener: PublisherReadinessListener)
Sets a
solace.messaging.publisher.publisher_health_check.PublisherReadinessListener
. Applications can implement thePublisherReadinessListener
interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after asolace.messaging.publisher.message_publisher.MessagePublisher
raises asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the application will callPublisherHealthCheck.notify_when_ready()
to guarantee that a subsequentPublisherReadinessListener.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:
- 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:
- 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
-
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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- Raises:
PubSubPlusClientError – Any error if the priority of the message could not be retrieved.
- abstract get_properties() Dict[str, str | int | float | bool | dict | list | bytearray | None]
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:
- abstract get_property(name: str) str | int | float | bool | dict | list | bytearray | None
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.
- 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:
- 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:
- 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
.- abstract build(payload: T, additional_message_properties: Dict[str, str | int | float | bool | dict | list | tuple | bytearray | None] = None, converter: ObjectToBytes[T] = None) OutboundMessage
Builds a
solace.messaging.publisher.outbound_message.OutboundMessage
instance with the specified payload. The payload must be abytearray
orstr
; if it is not, you must specify asolace.messaging.utils.converter.ObjectToBytes
that converts the object to abytearray
.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 tobytearray
.
- 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:
- abstract from_properties(configuration: Dict[str, str | int | float | bool | dict | list | tuple | bytearray | None]) OutboundMessageBuilder
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:
- 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:
- 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:
- 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:
- 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:
- 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:
- Returns:
A builder object representing an outbound message object for method chaining.
- Return type:
- 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:
- abstract with_property(property_key: str, property_value: str | int | float | bool | dict | list | tuple | bytearray | None) OutboundMessageBuilder
Adds the user property/Solace defined property with the given
key
andvalue
. For Solace defined property thevalue
must be valid data type for the givenkey
- 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:
- 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:
- 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:
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 viasolace.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:
- 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:
- abstract is_terminated() bool
Checks if message delivery process is terminated.
- Returns:
True if message delivery process is terminated, False otherwise.
- Return type:
- 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:
- 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 asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the overflow condition can be resolved by background publishing. At the end of the business logic to handle thePublisherOverflowError
, applications can callnotify_when_ready
to be guaranteed to receive a subsequentPublisherReadinessListener.ready()
callback.
- abstract publish(message: bytearray | str | OutboundMessage, destination: Topic, user_context: Any = None, additional_message_properties: Dict[str, str | int | float | bool | dict | list | tuple | bytearray | None] = None)
Sends and outbound message to the given destination.
The
solace.messaging.builder.outbound_message.OutboundMessageBuilder
can be used to create theOutboundMessage
instance. Alternatively, a bytearray or string payload can be passed to this function and the API will create asolace.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 theuser_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
- abstract publish_await_acknowledgement(message: bytearray | str | OutboundMessage, destination: Topic, time_out: int = None, additional_message_properties: Dict[str, str | int | float | bool | dict | list | tuple | bytearray | None] = None)
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 thePublisherReadinessListener
interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after asolace.messaging.publisher.message_publisher.MessagePublisher
raises asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the application will callPublisherHealthCheck.notify_when_ready()
to guarantee that a subsequentPublisherReadinessListener.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:
- 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:
- 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)
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
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:
- 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 asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the overflow condition can be resolved by background publishing. At the end of the business logic to handle thePublisherOverflowError
, applications can callnotify_when_ready
to be guaranteed to receive a subsequentPublisherReadinessListener.ready()
callback.
- abstract set_publisher_readiness_listener(listener: PublisherReadinessListener)
Sets a
solace.messaging.publisher.publisher_health_check.PublisherReadinessListener
. Applications can implement thePublisherReadinessListener
interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after asolace.messaging.publisher.message_publisher.MessagePublisher
raises asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the application will callPublisherHealthCheck.notify_when_ready()
to guarantee that a subsequentPublisherReadinessListener.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 theready()
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 callready()
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 aready()
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:
- 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:
- abstract is_terminated() bool
Checks if message delivery process is terminated.
- Returns:
True if message delivery process is terminated, False otherwise.
- Return type:
- 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:
- 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 asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the overflow condition can be resolved by background publishing. At the end of the business logic to handle thePublisherOverflowError
, applications can callnotify_when_ready
to be guaranteed to receive a subsequentPublisherReadinessListener.ready()
callback.
- abstract publish(request_message: OutboundMessage, request_destination: Topic, reply_timeout: int, additional_message_properties: Dict[str, str | int | float | bool | dict | list | tuple | bytearray | None] = None) Future
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.
- abstract publish_await_response(request_message: OutboundMessage, request_destination: Topic, reply_timeout: int, additional_message_properties: Dict[str, str | int | float | bool | dict | list | tuple | bytearray | None] = None) InboundMessage
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 thePublisherReadinessListener
interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after asolace.messaging.publisher.message_publisher.MessagePublisher
raises asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the application will callPublisherHealthCheck.notify_when_ready()
to guarantee that a subsequentPublisherReadinessListener.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:
- 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:
- 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:
- 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:
- abstract is_terminated() bool
Checks if message delivery process is terminated.
- Returns:
True if message delivery process is terminated, False otherwise.
- Return type:
- 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:
- 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 asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the overflow condition can be resolved by background publishing. At the end of the business logic to handle thePublisherOverflowError
, applications can callnotify_when_ready
to be guaranteed to receive a subsequentPublisherReadinessListener.ready()
callback.
- publish(message: bytearray | str | OutboundMessage, destination: Topic, additional_message_properties: Dict[str, str | int | float | bool | dict | list | tuple | bytearray | None] = None)
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 thePublisherReadinessListener
interface and configure objects with this interface to receive notifications when the the publisher can send messages. Typically, after asolace.messaging.publisher.message_publisher.MessagePublisher
raises asolace.messaging.errors.pubsubplus_client_error.PublisherOverflowError
, the application will callPublisherHealthCheck.notify_when_ready()
to guarantee that a subsequentPublisherReadinessListener.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:
- 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:
- Raises:
IllegalArgumentError – If the grace_period is invalid.