solace.messaging package

Solace PubSub+ Messaging API for Python

This package contains a full-featured Python API for developing Python applications. The API follows the builder pattern. Everything begins with a MessagingService.builder() call that returns a new MessagingServiceClientBuilder object. When you use a MessagingService instance, applications can:

The Messaging Service in turn can be used to:

solace.messaging.message module

This module is an abstract base class for a Message.

Message is the base class for:

Message instances are the objects that carry the payload and meta data to and from the solace.messaging.message_service.MessageService

class solace.messaging.message.Message

Bases: InteroperabilitySupport

An abstract class that abstracts a Solace PubSub+ Message.

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

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:

dict

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.

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.

solace.messaging.messaging_service module

The MessagingService (solace.messaging.messaging_service) is an abstract class that represents the Solace PubSub+ messaging service.

The MessagingService is used to:

  • connect the service

  • disconnect the service

  • create a MessagePublisherBuilder

  • create a MessageReceiverBuilder

The builder for the MessagingService contains the configuration to identify:

  • a Solace PubSub+ event broker

  • the client to the Solace PubSub+ Event Broker

  • messaging service characteristics such as flow control

class solace.messaging.messaging_service.MessagingService

Bases: Connectable, AsyncConnectable, Manageable, ErrorMonitoring, ABC

This is an abstract class for the messaging service and inherits Connectable, AsyncConnect, Manageable, and ErrorMonitoring. It contains abstract methods for connecting, disconnecting a service in both blocking and non-blocking mode and also contains the factory methods to create builders for a message receiver (solace.messaging.builder.message_receiver_builder.MessageReceiverBuilder) and message publishers (solace.messaging.builder.message_publisher_builder.MessagePublisherBuilder).

abstract add_reconnection_attempt_listener(listener: ReconnectionAttemptListener) → Connectable

Registers a solace.messaging.messaging_service.ReconnectionAttemptListener to receive notification of reconnection attempts. Reconnection attempt notifications are generated when an established connection fails and the API begins the reconnection process.

Parameters:

listener (ReconnectionListener) – The listener to register with the reconnection attempt.

Returns:

An object representing a synchronous connection.

Return type:

Connectable

abstract add_reconnection_listener(listener: ReconnectionListener) → Connectable

Registers a solace.messaging.messaging_service.ReconnectionListener to receive notification of successful reconnection. Reconnection notifications are generated when an established connection fails and is subsequently successfully reconnects.

Parameters:

listener (ReconnectionListener) – The listener to register.

Returns:

An object representing a synchronous connection.

Return type:

Connectable

abstract add_service_interruption_listener(listener: ServiceInterruptionListener)

Adds a service listener for listening to non recoverable service interruption events.

Parameters:

listener – service interruption listener

static builder() → MessagingServiceClientBuilder

Retrieves a MessagingServiceClientBuilder object.

Returns:

A builder object for the message service.

Return type:

MessagingServiceClientBuilder

abstract connect() → Connectable

Initiates the synchronous connection process with a PubSub+ event broker on a solace.messaging.messaging_service.MessagingService instance. In order to operate normally this method needs to be called on a service instance. After the method returns, the MessagingService has been successfully connected.

Raises:
abstract connect_async() → Future

Connects asynchronously with a PubSub+ event broker. This method initiates the connection process on the solace.messaging.messaging_service.MessagingService. The connection proceeds asynchronously, with the success or failure status available in the returned concurrent.futures.Future object.

This method initiates the connect process on the solace.messaging.messaging_service.MessagingService. The connection proceeds asynchronously, with the success or failure status available in the returned concurrent.futures.Future object.

Returns:

An object that the application may use to determine when the connection attempt has completed.

Return type:

concurrent.futures.Future

Raises:
abstract create_direct_message_publisher_builder() → DirectMessagePublisherBuilder

Defines the interface for a builder to create a direct message publisher.

Returns:

An DirectMessagePublisherBuilder object.

Return type:

DirectMessagePublisherBuilder

abstract create_direct_message_receiver_builder() → DirectMessageReceiverBuilder

Defines the interface for a builder to create direct message receiver.

Returns:

An DirectMessageReceiverBuilder object.

Return type:

DirectMessageReceiverBuilder

abstract create_persistent_message_publisher_builder() → PersistentMessagePublisherBuilder

Defines the interface for a builder to create a persistent message publisher.

Returns:

An PersistentMessagePublisherBuilder object.

Return type:

PersistentMessagePublisherBuilder

abstract create_persistent_message_receiver_builder() → PersistentMessageReceiverBuilder

Defines the interface for a builder to create a persistent message receiver.

Returns:

An PersistentMessageReceiverBuilder object.

Return type:

PersistentMessageReceiverBuilder

abstract create_transactional_service_builder() → TransactionalMessagingServiceBuilder

Creates a {@link TransactionalMessagingServiceBuilder} that is used to configure and create transactional messaging service instances :returns: new instance of TransactionalMessagingServiceBuilder :rtype: TransactionalMessagingServiceBuilder

abstract disconnect()

Initiates the disconnect (synchronous) process on the solace.messaging.messaging_service.MessagingService. The method does not return until the disconnect process completes. After the disconnect process completes, the Messaging Service can not be connected again.

abstract disconnect_async() → Future

Initiates the disconnection process on a solace.messaging.messaging_service.MessagingService instance. The disconnection process proceeds asynchronously with the completion notice available in the returned concurrent.futures.Future

Once disconnect is complete, the MessagingService can not be connected again.

Returns:

An object that your application can use to determine when the disconnection process has completed.

Return type:

concurrent.futures.Future

Raises:

PubSubPlusClientError – If the messaging service cannot be disconnected.

abstract get_application_id() → str

Retrieves the application identifier.

Returns:

The application identifier.

abstract info() → ApiInfo

Retrieves the API as an py:class:ApiInfo<solace.messaging.util.manageable.Manageable.ApiInfo>.

Returns:

The ApiInfo object.

Return type:

ApiInfo

abstract property is_connected: bool

Determines whether a service is currently connected and indicate the current state of the solace.messaging.messaging_service.MessagingService.

Returns:

True if service is connected to a PubSub+ event broker, otherwise False.

Return type:

bool

Raises:

PubSubPlusClientError – If the state of the service cannot be determined.

abstract message_builder() → OutboundMessageBuilder

Defines the interface for a builder to create an outbound message.

Returns:

An OutboundMessageBuilder object.

Return type:

OutboundMessageBuilder

abstract metrics() → ApiMetrics

Retrieves the API Metrics as a solace.messaging.utils.manageable.ApiMetrics object.

Returns:

The metrics transmitted/received data and events on the MessagingService.

Return type:

ApiMetrics

abstract remove_reconnection_attempt_listener(listener: ReconnectionAttemptListener) → Connectable

Remove a solace.messaging.messaging_service.ReconnectionAttemptListener

Parameters:

listener (ReconnectionListener) – The listener to deregister.

Returns:

An object representing a synchronous connection.

Return type:

Connectable

abstract remove_reconnection_listener(listener: ReconnectionListener) → Connectable

Removes a solace.messaging.messaging_service.ReconnectionListener.

Parameters:

listener (ReconnectionListener) – A reconnection listener to remove.

Returns:

An object representing a synchronous connection.

Return type:

Connectable

abstract remove_service_interruption_listener(listener: ServiceInterruptionListener) → bool

Removes a service listener for listening to non-recoverable service interruption events.

Parameters:

listener (ServiceInterruptionListener) – service interruption listener

Returns:

True if removal was successful, False otherwise.

Return type:

bool

abstract request_reply() → RequestReplyMessagingService

Creates RequestReplyMessagingService that inherits entire configuration from this instance.

Returns:

new instance of solace.messaging.messaging_service.RequestReplyMessagingService

static set_core_messaging_log_level(level: str, file=None)

Sets the core (Native) API log level. The Native API only generates logs at the given level or higher, which may be further filtered by Python logging.

Warning

Don’t set the message log level to be too high or you’ll impact the messaging service performance. For example, though it may seem like a good idea to set the core log level to a DEBUG level and then rely on Python logging to filter the logs, doing so severely affects the messaging service performance. For this reason, don’t do this. The core log level must be set lower than WARNING as a diagnostic aid.

Parameters:

  • file (str) – The name of the file.

  • level (str) – A valid string representation of the Python logging level you want using one of the following values (ordered from lowest to highest), CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET.

abstract update_property(name: str, value: Any)

Updates the value of a modifiable service property once the service has been created. Modifiable service properties include:

Modification of a service property may occur instantly, or may occur during the next service reconnection. Modification of a service property during an ongoing service reconnection may apply to the next reconnection attempt.

Parameters:

  • name (str) – The name of the property to modify.

  • value (Any) – The new value of the property.

Raises:
class solace.messaging.messaging_service.MessagingServiceClientBuilder

Bases: TransportProtocolConfiguration, AuthenticationConfiguration, PropertyBasedConfiguration

Builder class for messaging service builder

build(application_id: str | None = None) → MessagingService

Builds a MessagingService instance.

Parameters:

application_id (str) – Application id

Returns:

An Messaging Service object.

Return type:

MessagingService

from_properties(configuration: dict) → MessagingServiceClientBuilder

Passes a configuration dictionary for configuration information.

Parameters:

configuration (dict) – Pass a configuration dictionary.

Returns:

An object for method chaining.

Return type:

MessagingServiceClientBuilder

with_authentication_strategy(authentication_strategy: AuthenticationStrategy) → MessagingServiceClientBuilder

Configures the MessageService instance with the authentication strategy. For more information, see the base class solace.messaging.config.authentication_strategy.AuthenticationConfiguration.

Parameters:

authentication_strategy (AuthenticationStrategy) – The authentication strategy.

Returns:

An object for method chaining.

Return type:

MessagingServiceClientBuilder

with_connection_retry_strategy(strategy: RetryStrategy) → MessagingServiceClientBuilder

Configures the MessageService instance with the connection retry strategy. For more information, see the base class solace.messaging.config.retry_strategy.RetryStrategy.

Parameters:

strategy (RetryStrategy) – The retry strategy.

Returns:

An object for method chaining.

Return type:

MessagingServiceClientBuilder

with_message_compression(compression_factor: int = 0) → MessagingServiceClientBuilder

Configures the MessageService instance with so that messages are compressed with ZLIB before transmission and decompressed on receive.

Parameters:

compression_factor (int) – Enables messages to be compressed with ZLIB before transmission and decompressed on receive. The valid values to use are 0 (off) or 1..9, where 1 is least amount of compression (fastest) and 9 is the most amount of compression (slowest).

Returns:

An object for method chaining.

Return type:

MessagingServiceClientBuilder

with_reconnection_retry_strategy(strategy: RetryStrategy) → MessagingServiceClientBuilder

Configures the MessageService instance with the reconnection retry strategy. For more information, see the base class solace.messaging.config.transport_protocol_configuration.TransportProtocolConfiguration.

Parameters:

strategy (RetryStrategy) – The retry strategy.

Returns:

An object for method chaining.

Return type:

MessagingServiceClientBuilder

with_transport_security_strategy(transport_layer_security_strategy: TransportSecurityStrategy) → MessagingServiceClientBuilder

Configures a message with Transport Layer Security configuration. For more information, see the base class solace.messaging.config.transport_protocol_configuration.TransportProtocolConfiguration.

Parameters:

transport_layer_security_strategy (TransportSecurityStrategy) – The transport security strategy.

Returns:

An object for method chaining.

Return type:

MessagingServiceClientBuilder

class solace.messaging.messaging_service.ReconnectionAttemptListener

Bases: ABC

A class interface definition for a reconnection attempt event listener. Applications that are interested in ReconnectionAttempt events must instantiate an object implementing the ReconnectionAttemptListener class and register the listener with MessagingService.add_reconnection_attempt_listener.

abstract on_reconnecting(event: ServiceEvent)

Callback executed for the MessagingService connection fails and reconnection attempts begin.

Parameters:

event (ServiceEvent) – The Reconnection event with detailed information for each reconnection attempt.

class solace.messaging.messaging_service.ReconnectionListener

Bases: ABC

A class interface definition for a ReconnectionListener Applications interested in Reconnection events must instantiate an object implementing the ReconnectionListener class and register the listener with MessagingService.add_reconnection_listener().

abstract on_reconnected(service_event: ServiceEvent)

Callback invoked by MessagingService (solace.messaging.messaging_service.MessagingService) object when it is successfully reconnected.

Parameters:

service_event (ServiceEvent) – The detailed information for the event.

class solace.messaging.messaging_service.RequestReplyMessagingService

Bases: ABC

An interface that abstracts request-reply behavior.

abstract create_request_reply_message_publisher_builder() → RequestReplyMessagePublisherBuilder

Abstract method to create request reply publisher builder Class

Returns:

RequestReplyMessagePublisherBuilder instance

abstract create_request_reply_message_receiver_builder() → RequestReplyMessageReceiverBuilder

Abstract method to create request reply receiver builder Class

Returns:

RequestReplyMessageReceiverBuilder instance

class solace.messaging.messaging_service.ServiceEvent

Bases: ABC

This class represents an event that can occur asynchronously on a solace.messaging.messaging_service.MessagingService object. Applications that are interested in ServiceEvent objects must register a listener for the one of interest.

The available listeners for service events are listed below.

abstract get_broker_uri() → str

Retrieves the URI of the event broker.

Returns:

The event broker URI associated with the Messaging Service.

Return type:

str

abstract get_cause() → PubSubPlusClientError

Retrieves the cause of the client exception (solace.messaging.errors.pubsubplus_client_error.PubSubPlusClientError).

Returns:

The client error for the event.

Return type:

PubSubPlusClientError

abstract get_message() → str

Retrieves the message contents.

Returns:

An informational string that describes in further detail the cause of the event.

Return type:

str

abstract get_time_stamp() → float

Retrieves the timestamp of the event.

Returns:

The time the event occurred.

Return type:

float

class solace.messaging.messaging_service.ServiceInterruptionListener

Bases: ABC

An interface that abstracts notification about non recoverable service interruption.

abstract on_service_interrupted(event: ServiceEvent)

Callback executed in situation when connection goes down and cannot be successfully restored.

Parameters:

event – The service interruption event describing nature of the failure.

class solace.messaging.messaging_service.TransactionalMessagingService

Bases: TransactionalSupport, Connectable, ABC

An interface for transactional (non-XA, broker transacted session) use case of a PubSub+ event broker. Transactions are feature of the PubSub+ event broker, client just enables broker-side transactional support.

abstract add_reconnection_attempt_listener(listener: ReconnectionAttemptListener) → Connectable

Registers a solace.messaging.messaging_service.ReconnectionAttemptListener to receive notification of reconnection attempts. Reconnection attempt notifications are generated when an established connection fails and the API begins the reconnection process.

Parameters:

listener (ReconnectionListener) – The listener to register with the reconnection attempt.

Returns:

An object representing a synchronous connection.

Return type:

Connectable

abstract add_reconnection_listener(listener: ReconnectionListener) → Connectable

Registers a solace.messaging.messaging_service.ReconnectionListener to receive notification of successful reconnection. Reconnection notifications are generated when an established connection fails and is subsequently successfully reconnects.

Parameters:

listener (ReconnectionListener) – The listener to register.

Returns:

An object representing a synchronous connection.

Return type:

Connectable

commit()
Commits all messages based on this following:

  • For all messages published to the broker within given transaction, ‘commit’ allows PubSub+ Broker to deliver them.

  • For all messages received in a given transaction ‘commit’ allows broker to delete them on a broker.

After commit is called, a ‘new’ transactions are automatically started for publisher and receiver

if any associated.

Raises:

  • TransactionRollbackError – can be thrown if commit fails and broker indicates rollback. This starts a new transaction.

  • UnknownTransactionStateError – can be thrown when transaction state is lost and can not be recovered between the remote broker and client service. In this case it is unknown whether the borker completed the transaction or not.

  • PubSubPlusClientError – can be thrown if the service has an error on commit

abstract connect() → Connectable

Initiates the synchronous connection process with a PubSub+ event broker on a solace.messaging.messaging_service.MessagingService instance. In order to operate normally this method needs to be called on a service instance. After the method returns, the MessagingService has been successfully connected.

Raises:
create_transactional_message_publisher_builder() → TransactionalMessagePublisherBuilder

Creates a transactional message publisher builder instance.

create_transactional_message_receiver_builder() → TransactionalMessageReceiverBuilder

Creates a transactional message receiver builder instance.

abstract disconnect()

Initiates the disconnect (synchronous) process on the solace.messaging.messaging_service.MessagingService. The method does not return until the disconnect process completes. After the disconnect process completes, the Messaging Service can not be connected again.

abstract property is_connected: bool

Determines whether a service is currently connected and indicate the current state of the solace.messaging.messaging_service.MessagingService.

Returns:

True if service is connected to a PubSub+ event broker, otherwise False.

Return type:

bool

Raises:

PubSubPlusClientError – If the state of the service cannot be determined.

abstract remove_reconnection_attempt_listener(listener: ReconnectionAttemptListener) → Connectable

Remove a solace.messaging.messaging_service.ReconnectionAttemptListener

Parameters:

listener (ReconnectionListener) – The listener to deregister.

Returns:

An object representing a synchronous connection.

Return type:

Connectable

abstract remove_reconnection_listener(listener: ReconnectionListener) → Connectable

Removes a solace.messaging.messaging_service.ReconnectionListener.

Parameters:

listener (ReconnectionListener) – A reconnection listener to remove.

Returns:

An object representing a synchronous connection.

Return type:

Connectable

rollback()

Forces a broker to redeliver all messages and/or remove messages that were published as part of a rolled-back transaction.

Raises:

PubSubPlusClientError – can be thrown if the service has an error on rollback

transactional_service_info() → TransactionalServiceInfo

Provides access to the advanced information about transactional service at runtime.

Returns:

to access advanced information about the

transactional messaging service.

Return type:

TransactionalServiceInfo

class solace.messaging.messaging_service.TransactionalMessagingServiceBuilder(messaging_service)

Bases: PropertyBasedConfiguration

An interface to create transactional (non-XA) messaging service with a PubSub+ event broker. Transactions are feature of the PubSub+ event broker, client just enables broker-side transactional support.

build() → TransactionalMessagingService

Creates a new instance of transactional messaging service using the configuration provided by self instance of a builder.

Returns:

a new immutable instance of a TransactionalMessagingService to be used for transactional message publishing or receive purposes

Return type:

TransactionalMessagingService

from_properties(configuration: dict) → TransactionalMessagingServiceBuilder

Passes a configuration dictionary for configuration information.

Parameters:

configuration (dict) – Pass a configuration dictionary.

Returns:

An object for method chaining.

Return type:

TransactionalMessagingServiceBuilder

set_transaction_request_timeout(timeout: int = 10000) → TransactionalMessagingServiceBuilder

Timeout (in milliseconds) to wait for a response. Default is 10000. This is used for service requests like connect, disconnect, commit and rollback. :param timeout: time in milliseconds, the minimum configuration value is 1000. :type timeout: int