solace.messaging.utils package

solace.messaging.utils.cache_request_outcome module

This module includes any API items directly related to the CacheRequestOutcome enum.

class solace.messaging.utils.cache_request_outcome.CacheRequestOutcome(value)

Bases: Enum

Represents available cache request outcomes.

FAILED = 3: The request failed for some reason, accompanied exception should be used to determine a root cause.

NO_DATA = 1: There was no data in the reply.

OK = 0: Cached data was returned in a cache reply, or the cache request was fulfilled by live data.

SUSPECT_DATA = 2: There was suspect data in the cache reply.

solace.messaging.utils.cache_request_outcome_listener module

This module contains an abstract cache request completion listener class.

class solace.messaging.utils.cache_request_outcome_listener.CacheRequestOutcomeListener

Bases: ABC

A callback for listening for the results of a future computation with request id support.

abstract on_completion(result: CacheRequestOutcome, cache_request_id: int, exception: Exception | None)

A callback listener that accepts the results of a future computation. This callback executes on completion of an action with a result of the execution passed in or an exception as an indicator for failed execution.

Parameters:

result (CacheRequestOutcome) – The future execution result.
cache_request_id (int) – The cache request ID associated with the given completed computation unit.
exception (Exception) – An Exception, if execution fails, otherwise None.

solace.messaging.utils.converter module

This module is for type-safe object converter.

class solace.messaging.utils.converter.BytesToObject(*args, **kwds)

Bases: Generic[T], ABC

A class that converts a bytearray object to a business object.

abstract convert(src: bytearray) → T

Converts the bytearray to an business object.

Parameters:: src (bytearray) – The byte array to convert to a business object.
Returns:: The converted business object.
Return type:: T

class solace.messaging.utils.converter.ObjectToBytes(*args, **kwds)

Bases: Generic[T], ABC

A class that converts business objects to a bytes arrays and bytearrays to business objects.

abstract to_bytes(src: T) → bytes

Converts the provided business object into a bytearray value.

Parameters:: src (T) – The business object to convert.
Returns:: The bytes of the converted business object.
Return type:: bytes

solace.messaging.utils.error_monitoring module

This is a module for classes and methods for error monitoring.

class solace.messaging.utils.error_monitoring.ErrorMonitoring

Bases: ABC

An class for the global error monitoring capabilities.

abstract add_service_interruption_listener(listener: ServiceInterruptionListener)

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

Parameters:: listener – service interruption listener

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

solace.messaging.utils.interoperability_support module

This module contains the interface definition for messaging interoperability.

A Solace PubSub+ event broker supports many messaging protocols. When acting as a gateway from one protocol to another, there may be messaging headers that need to be carried in the messaging metadata.

One such protocol is REST. When you use the PubSub+ Messaging API for Python to receive messages that were originally published by a REST publisher, it may be necessary to know the original HTTP content-type or HTTP content-encoding which that is available for these interfaces.

class solace.messaging.utils.interoperability_support.InteroperabilitySupport

Bases: ABC

The base class for providing the methods related to the REST metadata.

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

class solace.messaging.utils.interoperability_support.RestInteroperabilitySupport

Bases: ABC

This class contains the methods to retrieve REST metadata.

abstract get_http_content_encoding() → str

Retrieves the HTTP content encoding value from message originally published by a REST client.

Returns:: HTTP content encoding(str) or None if the encoding is not present.
Return type:: str

abstract get_http_content_type() → str

Retrieves the HTTP content type header value from message originally published by a REST client.

Returns:: The HTTP content-type or None if no content-type is present.
Return type:: str

solace.messaging.utils.life_cycle_control module

This module contains the abstract classes used to define the MessagePublisher and MessageReceiver life cycle.

An object in the PubSub+ API for Python that contains these interfaces may be:

started
terminated
MessagePublisher and MessageReceiver state

class solace.messaging.utils.life_cycle_control.AsyncLifecycleControl

Bases: ABC

A class that abstracts asynchronous control service lifecycle operations such as start_async and terminate_async.

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_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.utils.life_cycle_control.LifecycleControl

Bases: ABC

A class that abstracts the control service lifecycle operations such as start and terminate.

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

class solace.messaging.utils.life_cycle_control.TerminationEvent

Bases: ABC

An event interface for non-user initiated non-recoverable LifeCylceControl object interruptions for which applications can listen.

property cause: PubSubPlusClientError: Retrieves the cause of the termination error for the event. :returns: The termination error for the event. :rtype: PubSubPlusClientError

property message: str

Retrieves the event message contents.

Returns:: An informational string that describes in further detail the cause of the event.
Return type:: str

property timestamp: float: Retrieves the timestamp of the event. :returns: The time the event occurred. :rtype: float

class solace.messaging.utils.life_cycle_control.TerminationNotificationListener

Bases: ABC

A callback listener for notifications of TerminationEvent in API lifecycle objects, such as network interruptions or parent-triggered disconnect.

abstract on_termination(event: TerminationEvent)

Callback executed in situations when a LifecycleControl object goes down and can not be successfully restored.

Parameters:: event (TerminationEvent) – The service termination event that describes the nature of the failure.

solace.messaging.utils.manageable module

This modules abstracts different aspects of API manageability

class solace.messaging.utils.manageable.ApiInfo

Bases: ABC

An interface for access to API build, client, environment, and basic broker information.

abstract get_api_build_date() → str

Retrieves the API build information (date and time) using the pattern pubsubplus-python-client mmm dd yyyy HH:mm:ss / C API mmm dd HH:mm:ss.

Returns:: The API build timestamp.
Return type:: str

abstract get_api_implementation_vendor() → str

Retrieves the implementation venfor of the API.

Returns:: The implementation vendor of the API.
Return type:: str

abstract get_api_user_id() → str

Retrieves the API user identifier that was reported to the event broker. This information includes the OS user ID of the user running the application, the computer name of the machine running the application, and the PID of the process running the application.

Returns:: The API user ID.
Return type:: str

abstract get_api_version() → str

Retrieves the API version inforation using the pattern pubsubplus-python-client <semantic version> / C API <semantic version>

Returns:: The API version information.
Return type:: str

class solace.messaging.utils.manageable.ApiMetrics

Bases: ABC

An abstract class the contains the interfaces to retrieve metrics from a Manageable API.

abstract get_value(the_metric: Metric) → int

Retrieves the metrics current value/count.

Parameters:: the_metric (Metric) – The metric to retrieve the value/count for.
Returns:: The value or count for the specified metric.
Return type:: int

abstract reset(): Resets all metrics.

class solace.messaging.utils.manageable.Manageable

Bases: ABC

A class interface to get API metrics.

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

class solace.messaging.utils.manageable.Metric(value)

Bases: Enum

A class that is an enumeration of available statistics that may be retrieved from any class with the py:class:solace.messaging.utils.manageable.Manageable interface.

These metrics are a composite of native library metrics and Python API metrics. They will not always reflect the application experience. For example an application may publish some number of messages and not see that number in TOTAL_MESSAGES_SENT because this reflects messages sent to the broker and not messages that may still be queued within the Python API for sending.

When analyzing metrics therefore the developer should be aware of all the places messages and or event may be counted.

BROKER_DISCARD_NOTIFICATIONS_RECEIVED = 'SOLCLIENT_STATS_RX_DISCARD_IND': The number of receive messages with discard indication set.

CACHE_REQUESTS_FAILED = 'SOLCLIENT_STATS_RX_CACHEREQUEST_ERROR_RESPONSE': The total number of failed cache requests

CACHE_REQUESTS_SENT = 'SOLCLIENT_STATS_TX_CACHEREQUEST_SENT': The total number of cache requests that have been sent.

CACHE_REQUESTS_SUCCEEDED = 'CACHE_REQUESTS_SUCCEEDED': The total number of successful cache request/response paris.

COMPRESSED_BYTES_RECEIVED = 'SOLCLIENT_STATS_RX_COMPRESSED_BYTES': The number of bytes received before decompression.

CONNECTION_ATTEMPTS = 'SOLCLIENT_STATS_TX_TOTAL_CONNECTION_ATTEMPTS': The total number of TCP connections attempted by this MessageService.

CONTROL_BYTES_RECEIVED = 'SOLCLIENT_STATS_RX_CTL_BYTES': The number of bytes received in control (non-data) messages.

CONTROL_BYTES_SENT = 'SOLCLIENT_STATS_TX_CTL_BYTES': The number of bytes transmitted in control (non-data) messages.

CONTROL_MESSAGES_RECEIVED = 'SOLCLIENT_STATS_RX_CTL_MSGS': The number of control (non-data) messages received.

CONTROL_MESSAGES_SENT = 'SOLCLIENT_STATS_TX_CTL_MSGS': The number of control (non-data) messages transmitted.

DIRECT_BYTES_RECEIVED = 'SOLCLIENT_STATS_RX_DIRECT_BYTES': The number of bytes received.

DIRECT_BYTES_SENT = 'SOLCLIENT_STATS_TX_DIRECT_BYTES': The number of bytes transmitted in direct messages.

DIRECT_MESSAGES_RECEIVED = 'SOLCLIENT_STATS_RX_DIRECT_MSGS': The number of messages received.

DIRECT_MESSAGES_SENT = 'SOLCLIENT_STATS_TX_DIRECT_MSGS': The number of Direct messages transmitted.

INTERNAL_DISCARD_NOTIFICATIONS = 'INTERNAL_DISCARD_NOTIFICATIONS': Received messages with discard notifications.

NONPERSISTENT_BYTES_RECEIVED = 'SOLCLIENT_STATS_RX_NONPERSISTENT_BYTES': The number of Non-persistent bytes received on the MessageReceiver. On the MessageService, it is the total number of Non-persistent bytes received across all MessageReceiver.

NONPERSISTENT_BYTES_REDELIVERED = 'SOLCLIENT_STATS_TX_NONPERSISTENT_BYTES_REDELIVERED': The number of bytes redelivered in non-persistent messages.

NONPERSISTENT_BYTES_SENT = 'SOLCLIENT_STATS_TX_NONPERSISTENT_BYTES': The number of bytes transmitted in non-persistent messages.

NONPERSISTENT_MESSAGES_RECEIVED = 'SOLCLIENT_STATS_RX_NONPERSISTENT_MSGS': The number of Non-persistent messages received on the MessageReceiver. On the MessageService, it is the total number of Non-persistent messages received across all MessageReceiver.

NONPERSISTENT_MESSAGES_REDELIVERED = 'SOLCLIENT_STATS_TX_NONPERSISTENT_REDELIVERED': The number of non-persistent messages redelivered.

NONPERSISTENT_MESSAGES_SENT = 'SOLCLIENT_STATS_TX_NONPERSISTENT_MSGS': The number of non-persistent messages transmitted.

PERSISTENT_ACKNOWLEDGE_SENT = 'SOLCLIENT_STATS_RX_ACKED': The number of acknowledgments sent for Guaranteed messages.

PERSISTENT_BYTES_RECEIVED = 'SOLCLIENT_STATS_RX_PERSISTENT_BYTES': The number of Persistent bytes received on the MessageReceiver. On the MessageService, it is the total number of Persistent bytes received across all MessageReceiver.

PERSISTENT_BYTES_REDELIVERED = 'SOLCLIENT_STATS_TX_PERSISTENT_BYTES_REDELIVERED': The number of bytes redelivered in persistent messages.

PERSISTENT_BYTES_SENT = 'SOLCLIENT_STATS_TX_PERSISTENT_BYTES': The number of bytes transmitted in persistent messages.

PERSISTENT_DUPLICATE_MESSAGES_DISCARDED = 'SOLCLIENT_STATS_RX_DISCARD_DUPLICATE': The number of Guaranteed messages dropped for being duplicates.

PERSISTENT_MESSAGES_RECEIVED = 'SOLCLIENT_STATS_RX_PERSISTENT_MSGS': The number of Persistent messages received on the MessageReceiver. On the MessageService, it is the total number of Persistent messages received across all MessageReceiver.

PERSISTENT_MESSAGES_REDELIVERED = 'SOLCLIENT_STATS_TX_PERSISTENT_REDELIVERED': The number of persistent messages redelivered.

PERSISTENT_MESSAGES_SENT = 'SOLCLIENT_STATS_TX_PERSISTENT_MSGS': The number of persistent messages transmitted.

PERSISTENT_NO_MATCHING_FLOW_MESSAGES_DISCARDED = 'SOLCLIENT_STATS_RX_DISCARD_NO_MATCHING_FLOW': The number of Guaranteed messages discarded due to no match on the flowId.

PERSISTENT_OUT_OF_ORDER_MESSAGES_DISCARDED = 'SOLCLIENT_STATS_RX_DISCARD_OUTOFORDER': The number of Guaranteed messages discarded for being received out of order.

PUBLISHED_MESSAGES_ACKNOWLEDGED = 'SOLCLIENT_STATS_TX_GUARANTEED_MSGS_SENT_CONFIRMED': Guaranteed messages (Persistent/Non-Persistent) published that have been acknowledged.

PUBLISHER_ACKNOWLEDGEMENT_RECEIVED = 'SOLCLIENT_STATS_TX_ACKS_RXED': The number of acknowledgments received.

PUBLISHER_ACKNOWLEDGEMENT_TIMEOUTS = 'SOLCLIENT_STATS_TX_ACK_TIMEOUT': The number of times the acknowledgment timer expired.

PUBLISHER_WINDOW_CLOSED = 'SOLCLIENT_STATS_TX_WINDOW_CLOSE': The number of times the transmit window closed.

PUBLISHER_WOULD_BLOCK = 'SOLCLIENT_STATS_TX_WOULD_BLOCK': The number of messages not accepted due to would block (non-blocking only).

PUBLISH_MESSAGES_DISCARDED = 'SOLCLIENT_STATS_TX_DISCARD_CHANNEL_ERROR': Messages discarded due to channel failure.

PUBLISH_MESSAGES_TERMINATION_DISCARDED = 'PUBLISH_MESSAGES_TERMINATION_DISCARDED': Internally buffered published messages count, those which are discarded due to termination event failures and also during application initiated termination.

RECEIVED_MESSAGES_BACKPRESSURE_DISCARDED = 'RECEIVED_MESSAGES_BACKPRESSURE_DISCARDED': Received messages discarded by the Python API due to back pressure.

RECEIVED_MESSAGES_TERMINATION_DISCARDED = 'RECEIVED_MESSAGES_TERMINATION_DISCARDED': Internally buffered received messages count, those which are discarded due to termination event failures and also during application initiated termination.

TOO_BIG_MESSAGES_DISCARDED = 'SOLCLIENT_STATS_RX_DISCARD_MSG_TOO_BIG': The number of messages discarded due to msg too large.

TOTAL_BYTES_RECEIVED = 'SOLCLIENT_STATS_RX_TOTAL_DATA_BYTES': The total number of data bytes received.

TOTAL_BYTES_SENT = 'SOLCLIENT_STATS_TX_TOTAL_DATA_BYTES': The number of data bytes transmitted in total.

TOTAL_MESSAGES_RECEIVED = 'SOLCLIENT_STATS_RX_TOTAL_DATA_MSGS': The total number of data messages received.

TOTAL_MESSAGES_SENT = 'SOLCLIENT_STATS_TX_TOTAL_DATA_MSGS': The number of data messages transmitted in total.

UNKNOWN_PARAMETER_MESSAGES_DISCARDED = 'SOLCLIENT_STATS_RX_DISCARD_SMF_UNKNOWN_ELEMENT': The number of messages discarded due to the presence of an unknown element or unknown protocol in the Solace Message Format (SMF) header.

class solace.messaging.utils.manageable.TransactionalServiceInfo

Bases: ABC

An interface that abstracts access to advanced transactional messaging service information at runtime.

abstract get_transactional_service_id() → str | None

Retrieves transactional service identifier assigned to this transactional service instance on a PubSub+ Broker during connection establishment. This can also be known as the transacted session name.

Returns:

The transactional service identifier or None when the TransactionalService was not previously: connected.

Return type:

str

solace.messaging.utils.manageable_publisher module

solace.messaging.utils.manageable_receiver module

This module consists of the Receiver Information and its respective methods

class solace.messaging.utils.manageable_receiver.ManageableReceiver

Bases: ABC

An interface that abstracts different aspects of message receiver manageability

abstract receiver_info() → ReceiverInfo

Provides access to the receiver information

Returns:: an object that represents message receiver manageability.
Return type:: ReceiverInfo

class solace.messaging.utils.manageable_receiver.PersistentReceiverInfo

Bases: ABC

An interface that abstracts access to advanced persistent receiver information at runtime

abstract get_resource_info() → ResourceInfo

Returns the remote endpoint (resource) info for particular receiver at runtime.

Returns:: information about bonded resource endpoint at runtime
Raises:: IllegalStateError – will be thrown when receiver is not in connected to the appliance and endpoint binding is not established

class solace.messaging.utils.manageable_receiver.ReceiverInfo

Bases: ABC

An interface that abstracts access to advanced receiver information information at runtime

abstract get_instance_name() → str

Provides a name for an instance of a receiver.

Returns:: a string representing the instance name of the receiver.
Return type:: str

class solace.messaging.utils.manageable_receiver.ResourceInfo

Bases: ABC

An interface that abstracts access to the remote resource endpoint information particular receiver instance is bonded to at runtime

abstract get_name() → str

Returns the name of the resource.

Returns:: a string representing the name of the resource.
Return type:: str

abstract is_durable() → bool

Returns whether the resource is durable.

Returns:: a boolean that indicates whether the resource is durable True or not False.
Return type:: bool

class solace.messaging.utils.manageable_receiver.TransactionalReceiverInfo

Bases: ABC

An interface that abstracts access to advanced transactional receiver information at runtime

abstract get_resource_info() → ResourceInfo

Returns the remote endpoint (resource) info for particular receiver at runtime.

Returns:: information about bonded resource endpoint at runtime
Raises:: IllegalStateError – will be thrown when receiver is not in connected to the appliance and endpoint binding is not established