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, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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
-
A class that converts a
bytearray
object to a business object.
- class solace.messaging.utils.converter.ObjectToBytes
-
A class that converts business objects to a
bytes
arrays andbytearrays
to business objects.
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:
- class solace.messaging.utils.interoperability_support.RestInteroperabilitySupport
Bases:
ABC
This class contains the methods to retrieve REST metadata.
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
andMessageReceiver
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:
- 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:
- 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_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 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
- 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:
- class solace.messaging.utils.manageable.ApiMetrics
Bases:
ABC
An abstract class the contains the interfaces to retrieve metrics from a Manageable API.
- 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:
- 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:
- class solace.messaging.utils.manageable.Metric(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)
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 theMessageService
, it is the total number of Non-persistent bytes received across allMessageReceiver
.
- 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 theMessageService
, it is the total number of Non-persistent messages received across allMessageReceiver
.
- 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 theMessageService
, it is the total number of Persistent bytes received across allMessageReceiver
.
- 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 theMessageService
, it is the total number of Persistent messages received across allMessageReceiver
.
- 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_MESSSAGES_ACCEPTED = 'SOLCLIENT_STATS_RX_SETTLE_ACCEPTED'
Number of messages settled with “ACCEPTED” outcome.
- PERSISTENT_MESSSAGES_FAILED = 'SOLCLIENT_STATS_RX_SETTLE_FAILED'
Number of messages settled with “FAILED” outcome.
- PERSISTENT_MESSSAGES_REJECTED = 'SOLCLIENT_STATS_RX_SETTLE_REJECTED'
Number of messages settled with “REJECTED” outcome.
- 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:
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:
- 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
- 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
- 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