solace.messaging.resources package

solace.messaging.resources.cached_message_subscription_request module

This module contains the factory and reader interfaces for CachedMessageSubscriptionRequests, which are required for sending cache requests through a DirectMessageReceiver by using the ReceiverCacheRequests interface.

class solace.messaging.resources.cached_message_subscription_request.CachedMessageSubscriptionRequest

Bases: ABC

This class provides constructors used to create cache request configurations.

static as_available(cache_name: str, subscription: TopicSubscription, cache_access_timeout: int, max_cached_messages: int = 0, cached_message_age: int = 0) → CachedMessageSubscriptionRequest

A factory method to create instances of a CachedMessageSubscriptionRequest to subscribe for a mix of live and cached messages matching specified topic subscription.

Parameters:

cache_name (str) – name of the Solace cache to retrieve from.
subscription (TopicSubscription) – matching topic subscription.
cache_access_timeout (int) – Solace cache request timeout (in milliseconds). A valid cache_access_timeout value ranges between 3000, and signed int 32 max. This value specifies a timer for the internal requests that occur between this API and a PubSub+ cache instance. A single call to request_cached() can lead to one or more of these internal requests. As long as each of these internal requests complete before the specified time-out, the timeout value is satisfied.
max_cached_messages (int) – The max number of messages expected to be received from a Solace cache. A valid max_cached_messages value range between 0 and signed int 32 max, with 0 as an indicator for NO restrictions on a number of messages. The default value is 0.
cached_message_age (int) – The maximum age (in seconds) of the messages to be retrieved from a Solace cache. A valid cached_message_age value range between 0 and signed int 32 max, with 0 as an indicator for NO restriction on a message age. 0 is the default value

Returns:

an instance of a cached topic subscription used to subscribe for a mix of live and cached messages.

Return type:

CachedMessageSubscriptionRequest

static cached_first(cache_name: str, subscription: TopicSubscription, cache_access_timeout: int, max_cached_messages: int = 0, cached_message_age: int = 0) → CachedMessageSubscriptionRequest

A factory method to create instances of a CachedMessageSubscriptionRequest to subscribe for cached messages when available, followed by live messages. Additional cached message filter properties such as max number of cached messages and age of a message from cache can be specified. Live messages will be queues until the Solace cache response is received. Queued live messages are delivered to the application after the cached messages are delivered.

Parameters:

cache_name (str) – Name of the Solace cache to retrieve from.
subscription (TopicSubscription) – matching topic subscription.
cache_access_timeout (int) – Solace cache request timeout, in milliseconds. A valid cache_access_timeout value ranges between 3000, and signed int 32 max. This value specifies a timer for the internal requests that occur between this API and a PubSub+ cache instance. A single call to request_cached() can lead to one or more of these internal requests. As long as each of these internal requests complete before the specified time-out, the timeout value is satisfied.
max_cached_messages (int) – The max number of messages expected to be received from a Solace cache. A valid max_cached_messages value range between 0 and signed int 32 max, with 0 as an indicator for NO restrictions on a number of messages. The default value is 0.
cached_message_age (int) – The maximum age, in seconds, of the messages to be retrieved from a Solace cache. A valid cached_message_age value range between 0 and signed int 32 max, with 0 as an indicator for NO restriction on a message age. The default value is 0.

Returns:

An instance of a cached topic subscription used to subscribe for messages delivered from a cache, followed by live messages.

Return type:

CachedMessageSubscriptionRequest

static cached_only(cache_name: str, subscription: TopicSubscription, cache_access_timeout: int, max_cached_messages: int = 0, cached_message_age: int = 0) → CachedMessageSubscriptionRequest

A factory method to create instances of a CachedMessageSubscriptionRequest to subscribe for cached messages when available, no live messages are expected to be received. Additional cached message filter properties such as max number of cached messages and age of a message from cache can be specified.

Note cache_only requests are limited to be used with subscribers without live data subscriptions. When used with matching live data subscriptions, cached message will be delivered for both the cache outcome and live subscription leading to duplicate message delivery. When needing cache data when live data subscriptions are already present use other CachedMessageSubscriptionRequest request types such as cached_first or as_available.

Parameters:

cache_name (str) – Name of Solace cache to retrieve from.
subscription (TopicSubscription) – Matching Topic Subscription.
cache_access_timeout (int) – Solace cache request timeout, in milliseconds. A valid cache_access_timeout value ranges between 3000, and signed int 32 max. This value specifies a timer for the internal requests that occur between this API and a PubSub+ cache instance. A single call to request_cached() can lead to one or more of these internal requests. As long as each of these internal requests complete before the specified time-out, the timeout value is satisfied.
max_cached_messages (int) – The max number of messages expected to be received from a Solace cache. A valid max_cached_messages value range between 0 and signed int 32 max, with 0 as an indicator for NO restrictions on number of messages. The default value is 0.
cached_message_age (int) – The maximum age, in seconds, of the messages to be retrieved from a Solace cache. A valid cached_message_age value range between 0 and signed int 32 max, with 0 as an indicator for NO restrictions on age of message. The default value is 0.

Returns:

An instance of a cached topic subscription used to subscribe for messages delivered from a cache.

Return type:

CachedMessageSubscriptionRequest

abstract get_cache_name() → str

Retrieves the name of the cache.

Returns:: The name of the cache.
Return type:: (str)

abstract get_name() → str

Retrieves the name of the topic subscription.

Returns:: The name of the topic subscription.
Return type:: (str)

static live_cancels_cached(cache_name: str, subscription: TopicSubscription, cache_access_timeout: int, max_cached_messages: int = 0, cached_message_age: int = 0) → CachedMessageSubscriptionRequest

A factory method to create instances of a CachedMessageSubscriptionRequest to subscribe for latest messages. When no live messages are available, cached messages matching specified topic subscription considered latest, live messages otherwise.

Parameters:

cache_name (str) – name of the Solace cache to retrieve from.
subscription (TopicSubscription) – matching topic subscription.
cache_access_timeout (int) – Solace cache request timeout (in milliseconds). A valid cache_access_timeout value ranges between 3000, and signed int 32 max. This value specifies a timer for the internal requests that occur between this API and a PubSub+ cache instance. A single call to request_cached() can lead to one or more of these internal requests. As long as each of these internal requests complete before the specified time-out, the timeout value is satisfied.
max_cached_messages (int) – The max number of messages expected to be received from a Solace cache. A valid max_cached_messages value range between 0 and signed int 32 max, with 0 as an indicator for NO restrictions on a number of messages. The default value is 0.
cached_message_age (int) – The max age in seconds of the messages to be retrieved from a Solace cache. A valid cached_message_age value range between 0 and signed int 32 max, with 0 as an indicator for NO restrictions on message age. The default value is 0.

Returns:

an instance of a cached topic subscription used to subscribe for a latest messages.

Return type:

CachedMessageSubscriptionRequest

solace.messaging.resources.destination module

This module contains an abstract class for named resources.

class solace.messaging.resources.destination.Destination

Bases: ABC

An abstract class that defines the interface to a remote resource that has a name.

abstract get_name() → str

Retrieves the name of the resource.

Returns:: The name of the resource.
Return type:: str

solace.messaging.resources.queue module

This module contains the classes and functions to work with Queues.

class solace.messaging.resources.queue.Queue

Bases: Destination, ResourceDurability, ResourceAccessibility, ABC

An interface that abstracts a PubSub+ event broker resource used primarily for receiving messages.

A Queue acts as an endpoint that clients can bind consumers to and consume messages from it can also act as a destination that clients can publish messages to. The primary use case for a queue is for the consumption of messages. It’s recommended that you you add topic subscriptions to a queue so messages published to matching topics are delivered to the queue.

static durable_exclusive_queue(queue_name: str) → Queue

Create an exclusive queue for durable consumers. More than one consumer can bind a flow to the queue, but only the first bound consumer receives messages. If the processing consumer fails, the next bound consumer receives unprocessed messages and becomes the active processing consumer. The queue persists whether there are consumers bound to the queue or not.

Parameters:: queue_name (str) – The name of the exclusive queue.
Returns:: A Queue object representing an exclusive queue.
Return type:: Queue

static durable_non_exclusive_queue(queue_name: str) → Queue

Create a non-exclusive queue for load-balancing and fault tolerance to durable consumers, and more than one consumer can bind to the queue. Messages are delivered in round-robin fashion for load-balancing. If a consumer fails, it’s unprocessed messages are forwarded to an active consumer. The queue persists whether there are consumers bound to the queue or not.

Parameters:: queue_name (str) – The name of the non-exclusive queue.
Returns:: A Queue object representing an non-exclusive queue.
Return type:: Queue

abstract get_name() → str

Retrieves the name of the resource.

Returns:: The name of the resource.
Return type:: str

abstract is_durable() → bool

Determines if resource is durable. Durable endpoints are provisioned objects on the event broker that have a life span independent of a particular client session.

Returns:: True if resource is durable, False otherwise.
Return type:: bool

abstract is_exclusively_accessible() → bool

Determines if a remote resource supports exclusive or shared access mode.

Returns:: True if a remote resource can serve only one consumer at any one time, False if a remote resource can serve multiple consumers; each consumer is serviced in round‑robin fashion.
Return type:: bool

static non_durable_exclusive_queue(queue_name: str | None = None) → Queue

Create an exclusive temporary queue for non-durable consumers. More than one consumer can bind a flow to the temporary queue, but only the first bound consumer receives messages. If the processing consumer fails, the next bound consumer receives unprocessed messages and becomes the active processing consumer. When there are no consumers connected to the queue, the queue doesn’t persist.

Parameters:: queue_name (str) – The name of the temporary, exclusive queue (optional).
Returns:: A Queue object representing an the temporary, exclusive queue.
Return type:: Queue

class solace.messaging.resources.queue.Queues

Bases: object

A class that contains different types of Queues.

class DurableQueue

Bases: Queue, ABC

A class that represents a durable queue.

static durable_exclusive_queue(queue_name: str) → Queue

Create an exclusive queue for durable consumers. More than one consumer can bind a flow to the queue, but only the first bound consumer receives messages. If the processing consumer fails, the next bound consumer receives unprocessed messages and becomes the active processing consumer. The queue persists whether there are consumers bound to the queue or not.

Parameters:: queue_name (str) – The name of the exclusive queue.
Returns:: A Queue object representing an exclusive queue.
Return type:: Queue

static durable_non_exclusive_queue(queue_name: str) → Queue

Create a non-exclusive queue for load-balancing and fault tolerance to durable consumers, and more than one consumer can bind to the queue. Messages are delivered in round-robin fashion for load-balancing. If a consumer fails, it’s unprocessed messages are forwarded to an active consumer. The queue persists whether there are consumers bound to the queue or not.

Parameters:: queue_name (str) – The name of the non-exclusive queue.
Returns:: A Queue object representing an non-exclusive queue.
Return type:: Queue

abstract get_name() → str

Retrieves the name of the resource.

Returns:: The name of the resource.
Return type:: str

is_durable() → bool

Determines if resource is durable. Durable endpoints are provisioned objects on the event broker that have a life span independent of a particular client session.

Returns:: True if resource is durable, False otherwise.
Return type:: bool

abstract is_exclusively_accessible() → bool

Determines if a remote resource supports exclusive or shared access mode.

Returns:: True if a remote resource can serve only one consumer at any one time, False if a remote resource can serve multiple consumers; each consumer is serviced in round‑robin fashion.
Return type:: bool

static non_durable_exclusive_queue(queue_name: str | None = None) → Queue

Create an exclusive temporary queue for non-durable consumers. More than one consumer can bind a flow to the temporary queue, but only the first bound consumer receives messages. If the processing consumer fails, the next bound consumer receives unprocessed messages and becomes the active processing consumer. When there are no consumers connected to the queue, the queue doesn’t persist.

Parameters:: queue_name (str) – The name of the temporary, exclusive queue (optional).
Returns:: A Queue object representing an the temporary, exclusive queue.
Return type:: Queue

class NonDurableQueue

Bases: Queue, ABC

A class that represents a non-durable queue.

static durable_exclusive_queue(queue_name: str) → Queue

Create an exclusive queue for durable consumers. More than one consumer can bind a flow to the queue, but only the first bound consumer receives messages. If the processing consumer fails, the next bound consumer receives unprocessed messages and becomes the active processing consumer. The queue persists whether there are consumers bound to the queue or not.

Parameters:: queue_name (str) – The name of the exclusive queue.
Returns:: A Queue object representing an exclusive queue.
Return type:: Queue

static durable_non_exclusive_queue(queue_name: str) → Queue

Create a non-exclusive queue for load-balancing and fault tolerance to durable consumers, and more than one consumer can bind to the queue. Messages are delivered in round-robin fashion for load-balancing. If a consumer fails, it’s unprocessed messages are forwarded to an active consumer. The queue persists whether there are consumers bound to the queue or not.

Parameters:: queue_name (str) – The name of the non-exclusive queue.
Returns:: A Queue object representing an non-exclusive queue.
Return type:: Queue

abstract get_name() → str

Retrieves the name of the resource.

Returns:: The name of the resource.
Return type:: str

is_durable() → bool

Determines if resource is durable. Durable endpoints are provisioned objects on the event broker that have a life span independent of a particular client session.

Returns:: True if resource is durable, False otherwise.
Return type:: bool

abstract is_exclusively_accessible() → bool

Determines if a remote resource supports exclusive or shared access mode.

Returns:: True if a remote resource can serve only one consumer at any one time, False if a remote resource can serve multiple consumers; each consumer is serviced in round‑robin fashion.
Return type:: bool

static non_durable_exclusive_queue(queue_name: str | None = None) → Queue

Create an exclusive temporary queue for non-durable consumers. More than one consumer can bind a flow to the temporary queue, but only the first bound consumer receives messages. If the processing consumer fails, the next bound consumer receives unprocessed messages and becomes the active processing consumer. When there are no consumers connected to the queue, the queue doesn’t persist.

Parameters:: queue_name (str) – The name of the temporary, exclusive queue (optional).
Returns:: A Queue object representing an the temporary, exclusive queue.
Return type:: Queue

class SimpleDurableQueue(name: str, exclusively_accessible: bool)

Bases: DurableQueue

A class that represents a simple durable queue.

static durable_exclusive_queue(queue_name: str) → Queue

Create an exclusive queue for durable consumers. More than one consumer can bind a flow to the queue, but only the first bound consumer receives messages. If the processing consumer fails, the next bound consumer receives unprocessed messages and becomes the active processing consumer. The queue persists whether there are consumers bound to the queue or not.

Parameters:: queue_name (str) – The name of the exclusive queue.
Returns:: A Queue object representing an exclusive queue.
Return type:: Queue

static durable_non_exclusive_queue(queue_name: str) → Queue

Create a non-exclusive queue for load-balancing and fault tolerance to durable consumers, and more than one consumer can bind to the queue. Messages are delivered in round-robin fashion for load-balancing. If a consumer fails, it’s unprocessed messages are forwarded to an active consumer. The queue persists whether there are consumers bound to the queue or not.

Parameters:: queue_name (str) – The name of the non-exclusive queue.
Returns:: A Queue object representing an non-exclusive queue.
Return type:: Queue

get_name() → str

Retrieves the name of the resource.

Returns:: The name of the resource.
Return type:: str

is_durable() → bool

Determines if resource is durable. Durable endpoints are provisioned objects on the event broker that have a life span independent of a particular client session.

Returns:: True if resource is durable, False otherwise.
Return type:: bool

is_exclusively_accessible() → bool

Determines if a remote resource supports exclusive or shared access mode.

Returns:: True if a remote resource can serve only one consumer at any one time, False if a remote resource can serve multiple consumers; each consumer is serviced in round‑robin fashion.
Return type:: bool

static non_durable_exclusive_queue(queue_name: str | None = None) → Queue

Create an exclusive temporary queue for non-durable consumers. More than one consumer can bind a flow to the temporary queue, but only the first bound consumer receives messages. If the processing consumer fails, the next bound consumer receives unprocessed messages and becomes the active processing consumer. When there are no consumers connected to the queue, the queue doesn’t persist.

Parameters:: queue_name (str) – The name of the temporary, exclusive queue (optional).
Returns:: A Queue object representing an the temporary, exclusive queue.
Return type:: Queue

class SimpleNonDurableQueue(name: str | None)

Bases: NonDurableQueue

A class that represents a simple non-durable queue.

static durable_exclusive_queue(queue_name: str) → Queue

Create an exclusive queue for durable consumers. More than one consumer can bind a flow to the queue, but only the first bound consumer receives messages. If the processing consumer fails, the next bound consumer receives unprocessed messages and becomes the active processing consumer. The queue persists whether there are consumers bound to the queue or not.

Parameters:: queue_name (str) – The name of the exclusive queue.
Returns:: A Queue object representing an exclusive queue.
Return type:: Queue

static durable_non_exclusive_queue(queue_name: str) → Queue

Create a non-exclusive queue for load-balancing and fault tolerance to durable consumers, and more than one consumer can bind to the queue. Messages are delivered in round-robin fashion for load-balancing. If a consumer fails, it’s unprocessed messages are forwarded to an active consumer. The queue persists whether there are consumers bound to the queue or not.

Parameters:: queue_name (str) – The name of the non-exclusive queue.
Returns:: A Queue object representing an non-exclusive queue.
Return type:: Queue

get_name() → str

Retrieves the name of the resource.

Returns:: The name of the resource.
Return type:: str

is_durable() → bool

Determines if resource is durable. Durable endpoints are provisioned objects on the event broker that have a life span independent of a particular client session.

Returns:: True if resource is durable, False otherwise.
Return type:: bool

is_exclusively_accessible() → bool

Determines if a remote resource supports exclusive or shared access mode.

Returns:: True if a remote resource can serve only one consumer at any one time, False if a remote resource can serve multiple consumers; each consumer is serviced in round‑robin fashion.
Return type:: bool

static non_durable_exclusive_queue(queue_name: str | None = None) → Queue

Create an exclusive temporary queue for non-durable consumers. More than one consumer can bind a flow to the temporary queue, but only the first bound consumer receives messages. If the processing consumer fails, the next bound consumer receives unprocessed messages and becomes the active processing consumer. When there are no consumers connected to the queue, the queue doesn’t persist.

Parameters:: queue_name (str) – The name of the temporary, exclusive queue (optional).
Returns:: A Queue object representing an the temporary, exclusive queue.
Return type:: Queue

solace.messaging.resources.resource_accessibility module

This module contains a class that pertains to resource accessibility.

class solace.messaging.resources.resource_accessibility.ResourceAccessibility

Bases: ABC

An abstract class that abstracts remote resource accessibility.

PubSub+ Broker resources (queues and topic endpoints) can be accessed exclusively or non-exclusively. A resource with exclusive accessibility can serve only one consumer at any one time, while additional consumers may be connected as standby. A resource with non-exclusive accessibility can serve multiple consumers and each consumer is serviced in a round‑robin fashion.

abstract is_exclusively_accessible() → bool

Determines if a remote resource supports exclusive or shared access mode.

Returns:: True if a remote resource can serve only one consumer at any one time, False if a remote resource can serve multiple consumers; each consumer is serviced in round‑robin fashion.
Return type:: bool

solace.messaging.resources.resource_durability module

This module contains a class that pertains to resource durability.

class solace.messaging.resources.resource_durability.ResourceDurability

Bases: ABC

An abstract class that abstracts a remote resource durability.

PubSub+ event broker resources (queues and topic endpoints) may be durable or non-durable. A durable resource is a provisioned object on the event broker that has a lifespan independent of a particular client MessageService. They also survive an event broker restart and are preserved as part of the event broker configuration for backup and restoration purposes. A non-durable resource exists only so long as a MessageService is connected to the PubSub+ event broker.

abstract is_durable() → bool

Determines if resource is durable. Durable endpoints are provisioned objects on the event broker that have a life span independent of a particular client session.

Returns:: True if resource is durable, False otherwise.
Return type:: bool

solace.messaging.resources.share_name module

This is a module for the share name.

class solace.messaging.resources.share_name.ShareName

Bases: Destination, ABC

A class that abstracts an identifier associated with the shared subscription.

The ShareName class, in conjunction with a topic subscription, allows application developers to create horizontally-scaled applications. Messages whose topic match the subscription are delivered in a round-robin fashion to all applications with the same shared subscription.

abstract get_name() → str

Retrieves the name of the resource.

Returns:: The name of the resource.
Return type:: str

static no_op() → ShareName

static of(group_name: str) → ShareName

Creates the instance of ShareName (solace.messaging.resources.share_name.ShareName).

Parameters:: group_name (str) – The name of the group.
Returns:: The identifier of the shared subscription.
Return type:: ShareName

abstract validate() → None

solace.messaging.resources.topic module

This is a module that contains the Abstract, API representation of a PubSub+ event Broker message topic.

class solace.messaging.resources.topic.Topic

Bases: Destination, ABC

An interface class that abstracts a PubSub+ event broker resource that’s used primarily for publishing messages. A topic acts as a destination that a MessagePublisher can publish messages to. MessageReceivers add subscriptions that can be exactly a topic, or expressions that may match one or more topics.

abstract get_name() → str

Retrieves the name of the resource.

Returns:: The name of the resource.
Return type:: str

static of(topic_string: str) → Topic

Takes the topic in the form of a string and returns the topic.

Parameters:: topic_string (str) – The topic as a string.
Returns:: An object representing the topic subscription.
Return type:: Topic

solace.messaging.resources.topic_subscription module

A module for topic subscriptions.

class solace.messaging.resources.topic_subscription.TopicSubscription

Bases: Destination, ABC

An interface class that abstracts a topic subscription.

Topic subscriptions are expressions to match topics. Messages from matching topics can be delivered to the MessageReceiver (solace.messaging.receiver.message_receiver.MessageReceiver) object.

abstract get_name() → str

Retrieves the name of the resource.

Returns:: The name of the resource.
Return type:: str

static of(expression: str) → TopicSubscription

Takes the subscription expression in the form of a string and returns a TopicSubscription object.

Parameters:: expression (str) – The topic expression.
Returns:: An expression to match a topic.
Return type:: TopicSubscription