solace.messaging.utils package — Solace PubSub+ API For Python 2024 documentation

solace.messaging.utils.cache_request_outcome module
solace.messaging.utils.cache_request_outcome_listener module
solace.messaging.utils.converter module
solace.messaging.utils.error_monitoring module
solace.messaging.utils.interoperability_support module
solace.messaging.utils.life_cycle_control module
solace.messaging.utils.manageable module
solace.messaging.utils.manageable_publisher module
solace.messaging.utils.manageable_receiver module
solace.messaging.message module
solace.messaging.messaging_service module

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.

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.

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 :

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 :

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 :

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 :

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 :

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

Returns :

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

Return type :

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 :

abstract get_api_implementation_vendor ( ) → str 

Retrieves the implementation venfor of the API.

Returns :

The implementation vendor of the API.

Return type :

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 :

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 :

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 :

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.

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

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

PUBLISHED_MESSAGES_ACKNOWLEDGED = 'SOLCLIENT_STATS_TX_GUARANTEED_MSGS_SENT_CONFIRMED' 

Guaranteed messages (Persistent/Non-Persistent) published that have been acknowledged.

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.

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.

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 :

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 :

a boolean that indicates whether the resource is durable True or not False .

Return type :

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