solace.messaging.builder package

solace.messaging.builder.direct_message_publisher_builder module

This module contains a builder for direct message publishers. Applications that need to publish direct messages must first create a DirectMessagePublisherBuilder using the solace.messaging.messaging_service.MessagingService.create_direct_message_publisher_builder().

The DirectMessagePublisherBuilder then creates one or more DirectMessagePublisher instances as necessary.

class solace.messaging.builder.direct_message_publisher_builder.DirectMessagePublisherBuilder

Bases: MessagePublisherBuilder

A class for a builder of direct message publishers.

abstract build() → DirectMessagePublisher

Builds a direct message publisher object.

Returns:: A direct message publisher.
Return type:: DirectMessagePublisher

abstract from_properties(configuration: dict) → PropertyBasedConfiguration

Enables a dictionary based on the configuration.

Parameters:: configuration (dict) – The dictionary containing the properties.
Raises:: IllegalArgumentError – When invalid properties are added.

abstract on_back_pressure_elastic() → PublisherBackPressureConfiguration

Configures the publisher to buffer indefinitely, consuming as much memory as required for buffered messages. On memory exhaustion publisher behavior is undefined. Elastic, essential no, back-pressure is an ideal strategy for applications that publish messages at a low rate with infrequent small bursts of activity. It should not be considered for use in all cases.

Returns:: An instance of itself for method chaining.
Raises:: PubSubPlusClientError – When unable to configure the publisher.

abstract on_back_pressure_reject(buffer_capacity: int) → PublisherBackPressureConfiguration

Configures the publisher with capacity-bounded, buffered back-pressure; when the application keeps publishing, the publish method raises a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError if the specified buffer_capacity is exceeded. If the capacity is 0 an exception is thrown when the transport is full. And there is no internal buffer capacity.

Parameters:

buffer_capacity (int) – The maximum number of messages to buffer before raising an exception.

Returns:

An instance of itself for method chaining.

Raises:

IllegalArgumentError – With invalid capacity value. Valid capacity is 0 or greater.
InvalidDataTypeError – With invalid capacity type. Valid capacity is of type int.

abstract on_back_pressure_wait(buffer_capacity: int) → PublisherBackPressureConfiguration

Configures the publisher with capacity bounded buffered back-pressure. If the application application keeps publishing using the publish() method, it blocks and waits for room if the specified buffer_capacity has been exceeded.

Parameters:

buffer_capacity (int) – The maximum number of messages to buffer before raising an error.

Returns:

An instance of itself for method chaining.

Raises:

IllegalArgumentError – With invalid capacity value. Valid capacity is 1 or greater.
InvalidDataTypeError – With invalid capacity type. Valid capacity is of type int.

solace.messaging.builder.direct_message_receiver_builder module

This module contains builders for direct message receivers. Applications that need to receive direct messages must first create a DirectMessageReceiverBuilder instance using the solace.messaging.message_service.MessagingService.create_direct_message_receiver_builder()

The DirectMessageReceiverBuilder then creates one or more DirectMessageReceiver as necessary.

class solace.messaging.builder.direct_message_receiver_builder.DirectMessageReceiverBuilder

Bases: MessageReceiverBuilder, DirectReceiverBackPressureConfiguration

A class for a builder of direct message receivers.

abstract build(shared_subscription_group: ShareName = None) → DirectMessageReceiver

Creates an instance of a direct message receiver (solace.messaging.receiver.direct_message_receiver.DirectMessageReceiver). If the optional ShareName argument is given, the DirectMessageReceiver is implemented with Horizontal Scalability in mind. This method should be used when more then one instance of the application is running for horizontal scaling and messages are distributed by the PubSub+ event broker to all applications in the subscription group. When the ShareName argument is not specified, then the DirectMessageReceiver receives copies of all messages that match the configured subscriptions. If multiple applications have the same subscriptions, then all matching messages are sent to all of the applications.

Parameters:: shared_subscription_group (ShareName) – ShareName as the shared group name.
Returns:: A direct message receiver object.
Return type:: DirectMessageReceiver

abstract from_properties(configuration: dict) → MessageReceiverBuilder

Sets the properties for a message receiver using a dictionary. The dictionary is comprised of property-value pairs.

Parameters:: configuration (dict) – The configuration properties.
Returns:: The message receiver builder instance for method chaining.
Return type:: MessageReceiverBuilder

abstract on_back_pressure_drop_latest(buffer_capacity: int) → DirectReceiverBackPressureConfiguration

Configures the publisher with capacity-bounded, buffered back-pressure. If the buffer is full and is still receiving messages, the incoming message will be discarded. The maximum capacity of the buffer is given by the parameter of this method, buffer_capacity.

Parameters:

buffer_capacity (int) – The maximum number of messages to buffer before discarding the latest incoming message.

Returns:

An instance of itself for method chaining.

Return type:

DirectReceiverBackPressureConfiguration

Raises:

IllegalArgumentError – If an invalid buffer capacity is passed to this method. Valid buffer capacity is 0 or greater.
InvalidDataTypeError – If a buffer capacity of invalid type is passed to this method. Valid buffer capacity type is int.

abstract on_back_pressure_drop_oldest(buffer_capacity: int) → DirectReceiverBackPressureConfiguration

Configures the publisher with capacity-bounded, buffered back-pressure. If the buffer is full and is still receiving messages, the oldest message in the buffer is discarded. The maximum capacity of the buffer is given by the parameter of this method, buffer_capacity.

Parameters:

buffer_capacity (int) – The maximum number of messages to buffer before discarding the oldest message.

Returns:

An instance of itself for method chaining.

Return type:

DirectReceiverBackPressureConfiguration

Raises:

PubSubPlusClientError – If an invalid buffer capacity is passed to this method. Valid buffer capacity is 0 or greater.
InvalidDataTypeError – If a buffer capacity of invalid type is passed to this method. Valid buffer capacity type is int.

abstract on_back_pressure_elastic() → DirectReceiverBackPressureConfiguration

Configures the receiver to buffer indefinitely, consuming as much memory as required for buffered messages. On memory exhaustion receiver behaviour is undefined. Elastic, essentially no, back-pressure is an ideal strategy for applications that process received messages at a low rate with infrequent small bursts of activity. It should not be considered for use in all cases.

Returns:: An instance of itself for method chaining.
Return type:: DirectReceiverBackPressureConfiguration
Raises:: PubSubPlusClientError – When unable to configure the receiver.

abstract with_subscriptions(subscriptions: List[TopicSubscription]) → MessageReceiverBuilder

Adds a list of subscriptions to be applied to all MessageReceiver that are subsequently created with this builder.

Parameters:: subscriptions (List[TopicSubscription]) – The list of topic subscriptions to be added.
Returns:: The message receiver builder instance for method chaining.
Return type:: MessageReceiverBuilder

solace.messaging.builder.message_publisher_builder module

An abstract base class for the MessagePublisherBuilder.

class solace.messaging.builder.message_publisher_builder.MessagePublisherBuilder

Bases: PublisherBackPressureConfiguration, PropertyBasedConfiguration, ABC

A class that abstracts the behavior of configuration and creation of different types of message publishers.

abstract from_properties(configuration: dict) → PropertyBasedConfiguration

Enables a dictionary based on the configuration.

Parameters:: configuration (dict) – The dictionary containing the properties.
Raises:: IllegalArgumentError – When invalid properties are added.

abstract on_back_pressure_elastic() → PublisherBackPressureConfiguration

Configures the publisher to buffer indefinitely, consuming as much memory as required for buffered messages. On memory exhaustion publisher behavior is undefined. Elastic, essential no, back-pressure is an ideal strategy for applications that publish messages at a low rate with infrequent small bursts of activity. It should not be considered for use in all cases.

Returns:: An instance of itself for method chaining.
Raises:: PubSubPlusClientError – When unable to configure the publisher.

abstract on_back_pressure_reject(buffer_capacity: int) → PublisherBackPressureConfiguration

Configures the publisher with capacity-bounded, buffered back-pressure; when the application keeps publishing, the publish method raises a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError if the specified buffer_capacity is exceeded. If the capacity is 0 an exception is thrown when the transport is full. And there is no internal buffer capacity.

Parameters:

buffer_capacity (int) – The maximum number of messages to buffer before raising an exception.

Returns:

An instance of itself for method chaining.

Raises:

IllegalArgumentError – With invalid capacity value. Valid capacity is 0 or greater.
InvalidDataTypeError – With invalid capacity type. Valid capacity is of type int.

abstract on_back_pressure_wait(buffer_capacity: int) → PublisherBackPressureConfiguration

Configures the publisher with capacity bounded buffered back-pressure. If the application application keeps publishing using the publish() method, it blocks and waits for room if the specified buffer_capacity has been exceeded.

Parameters:

buffer_capacity (int) – The maximum number of messages to buffer before raising an error.

Returns:

An instance of itself for method chaining.

Raises:

IllegalArgumentError – With invalid capacity value. Valid capacity is 1 or greater.
InvalidDataTypeError – With invalid capacity type. Valid capacity is of type int.

solace.messaging.builder.message_receiver_builder module

class solace.messaging.builder.message_receiver_builder.MessageReceiverBuilder

Bases: PropertyBasedConfiguration

An abstract base class for builders of message receivers.

abstract from_properties(configuration: dict) → MessageReceiverBuilder

Sets the properties for a message receiver using a dictionary. The dictionary is comprised of property-value pairs.

Parameters:: configuration (dict) – The configuration properties.
Returns:: The message receiver builder instance for method chaining.
Return type:: MessageReceiverBuilder

abstract with_subscriptions(subscriptions: List[TopicSubscription]) → MessageReceiverBuilder

Adds a list of subscriptions to be applied to all MessageReceiver that are subsequently created with this builder.

Parameters:: subscriptions (List[TopicSubscription]) – The list of topic subscriptions to be added.
Returns:: The message receiver builder instance for method chaining.
Return type:: MessageReceiverBuilder

solace.messaging.builder.persistent_message_publisher_builder module

module contains persistent message publisher builder Applications that need to publish guaranteed messages must first create a PersistentMessagePublisherBuilder using the MessagingService.create_persistent_message_publisher_builder( )

The PersistentMessagePublisherBuilder then creates one or more PersistentMessagePublisher as necessary.

class solace.messaging.builder.persistent_message_publisher_builder.PersistentMessagePublisherBuilder

Bases: MessagePublisherBuilder

A class that configures and creates instances of PersistentMessagePublisherBuilder. The PersistentMessagePublisherBuilder builds the solace.messaging.publisher.persistent_message_publisher.PersistentMessagePublisher instances.

abstract build() → PersistentMessagePublisher

Creates an instance of solace.messaging.publisher.persistent_message_publisher.PersistentMessagePublisher.

Returns:: A persistent message publisher.
Return type:: PersistentMessagePublisher

abstract from_properties(configuration: dict) → PropertyBasedConfiguration

Enables a dictionary based on the configuration.

Parameters:: configuration (dict) – The dictionary containing the properties.
Raises:: IllegalArgumentError – When invalid properties are added.

abstract on_back_pressure_elastic() → PublisherBackPressureConfiguration

Configures the publisher to buffer indefinitely, consuming as much memory as required for buffered messages. On memory exhaustion publisher behavior is undefined. Elastic, essential no, back-pressure is an ideal strategy for applications that publish messages at a low rate with infrequent small bursts of activity. It should not be considered for use in all cases.

Returns:: An instance of itself for method chaining.
Raises:: PubSubPlusClientError – When unable to configure the publisher.

abstract on_back_pressure_reject(buffer_capacity: int) → PublisherBackPressureConfiguration

Configures the publisher with capacity-bounded, buffered back-pressure; when the application keeps publishing, the publish method raises a solace.messaging.errors.pubsubplus_client_error.PublisherOverflowError if the specified buffer_capacity is exceeded. If the capacity is 0 an exception is thrown when the transport is full. And there is no internal buffer capacity.

Parameters:

buffer_capacity (int) – The maximum number of messages to buffer before raising an exception.

Returns:

An instance of itself for method chaining.

Raises:

IllegalArgumentError – With invalid capacity value. Valid capacity is 0 or greater.
InvalidDataTypeError – With invalid capacity type. Valid capacity is of type int.

abstract on_back_pressure_wait(buffer_capacity: int) → PublisherBackPressureConfiguration

Configures the publisher with capacity bounded buffered back-pressure. If the application application keeps publishing using the publish() method, it blocks and waits for room if the specified buffer_capacity has been exceeded.

Parameters:

buffer_capacity (int) – The maximum number of messages to buffer before raising an error.

Returns:

An instance of itself for method chaining.

Raises:

IllegalArgumentError – With invalid capacity value. Valid capacity is 1 or greater.
InvalidDataTypeError – With invalid capacity type. Valid capacity is of type int.

solace.messaging.builder.persistent_message_receiver_builder module

This module contains a persistent message receiver builder. Applications that need to receive persistent messages must first create a PersistentMessageReceiverBuilder instance using the the MessagingService.create_persistent_message_receiver_builder() method.

The PersistentMessageReceiverBuilder then creates one or more PersistentMessageReceiver instances as necessary.

class solace.messaging.builder.persistent_message_receiver_builder.PersistentMessageReceiverBuilder

Bases: MessageReceiverBuilder, ReceiverActivationPassivationConfiguration, MissingResourcesCreationConfiguration, MessageAcknowledgementConfiguration, MessageReplayConfiguration

A class that configures and creates instances of PersistentMessageReceiverBuilder. The PersistentMessageReceiverBuilder builds the solace.messaging.receiver.persistent_message_receiver.PersistentMessageReceiver instances.

abstract build(endpoint_to_consume_from: Queue) → PersistentMessageReceiver

Creates an instance of solace.messaging.receiver.persistent_message_receiver.PersistentMessageReceiver.

Parameters:: endpoint_to_consume_from (Queue) – The Queue to receive message.
Returns:: A persistent message receiver.
Return type:: PersistentMessageReceiver

abstract from_properties(configuration: dict) → MessageReceiverBuilder

Sets the properties for a message receiver using a dictionary. The dictionary is comprised of property-value pairs.

Parameters:: configuration (dict) – The configuration properties.
Returns:: The message receiver builder instance for method chaining.
Return type:: MessageReceiverBuilder

abstract with_activation_passivation_support(receiver_state_change_listener: ReceiverStateChangeListener) → ReceiverActivationPassivationConfiguration

Enables the receiver to receive event broker notifications about state changes of the specified receiver instance.

Parameters:: receiver_state_change_listener (ReceiverStateChangeListener) – The receiver instance to receive state changes about.

abstract with_message_auto_acknowledgement() → MessageAutoAcknowledgementConfiguration

Enables support for message auto acknowledgement (auto-ack) on all receiver methods, which includes both synchronous and asynchronous methods.

Note

For callback-based methods, auto-ack is performed when the message-processing callback method is finished without an error. This means that if the message-processing callback method processes a message using another thread, the message acknowledgement may be performed before that other thread finishes and any errors raised in the other thread are not considered.
For blocking receive (without callback) methods: auto-ack is performed immediately after the PersistentMessageReceiver.receive_message call returns.
Should the underlying network connectivity fail auto acknowledgement may fail after the message-processing callback method. In this case it is not guaranteed to acknowledge messages automatically.

Returns:: An instance of itself for method chaining.

abstract with_message_client_acknowledgement() → MessageAcknowledgementConfiguration

Enables support for message client-acknowledgement (client-ack) on all receiver methods, which includes both synchronous and asynchronous methods. Client-acknowledgement must be executed by the user-defined application. It is recommended that client-acknowledgement be written in the on_message method of the user defined message handler. This message handler would be of type solace.messaging.receiver.message_receiver.MessageHandler.

Returns:: An instance of itself for method chaining.

abstract with_message_replay(replay_strategy: ReplayStrategy) → MessageReplayConfiguration

ADd a message replay message strategy to a persistent receiver.

Parameters:: replay_strategy (ReplayStrategy) – Specify the message replay strategy.
Returns:: A reference to self for method chaining.
Return type:: MessageReplayConfiguration

abstract with_message_selector(selector_query_expression: str) → PersistentMessageReceiverBuilder

Enables support for message selection based on the message header parameter and message properties values. When a selector is applied, then the receiver only gets messages whose headers and properties match the selector. A message selector cannot select messages on the basis of the content of the message body.

Parameters:: selector_query_expression (str) – The selector query expression
Returns:: An instance of itself for method chaining.

abstract with_missing_resources_creation_strategy(strategy: MissingResourcesCreationStrategy) → MissingResourcesCreationConfiguration

Adds the missing creation strategy that defines what remedial action the API may take.

Parameters:: strategy (MissingResourcesCreationStrategy) – Specify the missing creation strategy.
Returns:: A reference to the creation strategy for method chaining.
Return type:: MissingResourcesCreationConfiguration

abstract with_required_message_outcome_support(*outcomes: Outcome) → MessageAcknowledgementConfiguration

The types of settlements the receiver can use. Any combination of ACCEPTED, FAILED, and REJECTED, the order is irrelevant. Attempting to settle() a message later with an Outcome not listed here may result in an error.

Parameters:: outcomes (*Outcome) – The types of outcomes the settle() method of the consumer will support.
Returns:: An instance of itself for method chaining.

abstract with_subscriptions(subscriptions: List[TopicSubscription]) → MessageReceiverBuilder

Adds a list of subscriptions to be applied to all MessageReceiver that are subsequently created with this builder.

Parameters:: subscriptions (List[TopicSubscription]) – The list of topic subscriptions to be added.
Returns:: The message receiver builder instance for method chaining.
Return type:: MessageReceiverBuilder

solace.messaging.builder.request_reply_message_publisher_builder module

This module contains request reply message publisher builder. Applications that requires request and reply messages must first create a RequestReplyMessagePublisherBuilder using the MessagingService.create_request_reply_message_publisher_builder( )

The RequestReplyMessagePublisherBuilder then creates one or more RequestReplyMessagePublisher as necessary.

class solace.messaging.builder.request_reply_message_publisher_builder.RequestReplyMessagePublisherBuilder

Bases: PropertyBasedConfiguration, ABC

This class is used to configure and create instances of RequestReplyMessagePublisher.

abstract build() → RequestReplyMessagePublisher

Creates an instance of solace.messaging.publisher.request_reply_message_publisher.RequestReplyMessagePublisher.

Returns:: A RequestReply message publisher.
Return type:: RequestReplyMessagePublisher

abstract from_properties(configuration: dict) → PropertyBasedConfiguration

Enables a dictionary based on the configuration.

Parameters:: configuration (dict) – The dictionary containing the properties.
Raises:: IllegalArgumentError – When invalid properties are added.

solace.messaging.builder.request_reply_message_receiver_builder module

This module contains a builder for RequestReply message publishers. Applications that need to publish request reply messages must first create a RequestReplyMessageReceiverBuilder using the solace.messaging.messaging_service.MessagingService.create_request_reply_message_receiver_builder().

The RequestReplyMessageReceiverBuilder then creates one or more RequestReplyMessageReceiver instances as necessary.

class solace.messaging.builder.request_reply_message_receiver_builder.RequestReplyMessageReceiverBuilder

Bases: PropertyBasedConfiguration

This class is used to configure and create instances of RequestReplyMessageReceiver

abstract build(request_topic_subscription: TopicSubscription, share_name: ShareName = None) → RequestReplyMessageReceiver

Parameters:

request_topic_subscription – topic subscription
share_name – share name

Returns:

An instance of RequestReplyMessageReceiver

abstract from_properties(configuration: dict) → PropertyBasedConfiguration

Enables a dictionary based on the configuration.

Parameters:: configuration (dict) – The dictionary containing the properties.
Raises:: IllegalArgumentError – When invalid properties are added.

solace.messaging.builder.transactional_message_publisher_builder module

This module contains a builder for the transactional message publisher. Applications that need to publish messages on a transacted session must first create a TrannsactionalMessagePublisherBuilder using the create_transaction_message_publisher_builder().

The TransactionalMessagePublisherBuilder then creates the TransactionalMessagePublisher

class solace.messaging.builder.transactional_message_publisher_builder.TransactionalMessagePublisherBuilder

Bases: PropertyBasedConfiguration, ABC

A class to configure and create instances of {@link TransactionalMessagePublisher} to publish transactional messages.

build() → TransactionalMessagePublisher

Builds a transactional message publisher. :returns: TransactionalMessagePublisher instance.

Raises:: PubSubPlusClientError – When the publisher can not be created.

abstract from_properties(configuration: dict) → PropertyBasedConfiguration

Enables a dictionary based on the configuration.

Parameters:: configuration (dict) – The dictionary containing the properties.
Raises:: IllegalArgumentError – When invalid properties are added.

solace.messaging.builder.transactional_message_receiver_builder module

This module contains a builder for the transactional message receivers. Applications that need to receive messages on a transacted session must first create a TrannsactionalMessageReceiverBuilder using the solace.messaging.messaging_service.TransactionalMessagingService.create_transactional_receiver_builder().

The TransactionalMessageReceiverBuilder then creates one or more TransactionalMessageReceiver instances as needed.

class solace.messaging.builder.transactional_message_receiver_builder.TransactionalMessageReceiverBuilder

Bases: MessageReceiverBuilder, ReceiverActivationPassivationConfiguration, MissingResourcesCreationConfiguration, MessageReplayConfiguration, ABC

A class to configure and create instances of {@link TransactionalMessageReceiver} to receive transactional messages.

build(endpoint_to_consume_from: Queue) → TransactionalMessageReceiver: Builds a transactional message receiver. :param endpoint_to_consume_from: The Queue to receive message. :type endpoint_to_consume_from: Queue

abstract from_properties(configuration: dict) → MessageReceiverBuilder

Sets the properties for a message receiver using a dictionary. The dictionary is comprised of property-value pairs.

Parameters:: configuration (dict) – The configuration properties.
Returns:: The message receiver builder instance for method chaining.
Return type:: MessageReceiverBuilder

abstract with_activation_passivation_support(receiver_state_change_listener: ReceiverStateChangeListener) → ReceiverActivationPassivationConfiguration

Enables the receiver to receive event broker notifications about state changes of the specified receiver instance.

Parameters:: receiver_state_change_listener (ReceiverStateChangeListener) – The receiver instance to receive state changes about.

abstract with_message_replay(replay_strategy: ReplayStrategy) → MessageReplayConfiguration

ADd a message replay message strategy to a persistent receiver.

Parameters:: replay_strategy (ReplayStrategy) – Specify the message replay strategy.
Returns:: A reference to self for method chaining.
Return type:: MessageReplayConfiguration

with_message_selector(selector_query_expression: str) → TransactionalMessageReceiverBuilder: Enables support for message selection based on message header parameter and message properties values. When selector is applied, then the receiver gets only messages whose headers and properties match the selector. A message selector cannot select messages on the basis of the content of the message body. Args: selector_query_expression(str): The selector query expression :returns: An instance of itself for method chaining.

abstract with_missing_resources_creation_strategy(strategy: MissingResourcesCreationStrategy) → MissingResourcesCreationConfiguration

Adds the missing creation strategy that defines what remedial action the API may take.

Parameters:: strategy (MissingResourcesCreationStrategy) – Specify the missing creation strategy.
Returns:: A reference to the creation strategy for method chaining.
Return type:: MissingResourcesCreationConfiguration

abstract with_subscriptions(subscriptions: List[TopicSubscription]) → MessageReceiverBuilder

Adds a list of subscriptions to be applied to all MessageReceiver that are subsequently created with this builder.

Parameters:: subscriptions (List[TopicSubscription]) – The list of topic subscriptions to be added.
Returns:: The message receiver builder instance for method chaining.
Return type:: MessageReceiverBuilder