1 // pubsubplus-go-client 2 // 3 // Copyright 2021-2024 Solace Corporation. All rights reserved. 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); 6 // you may not use this file except in compliance with the License. 7 // You may obtain a copy of the License at 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 // See the License for the specific language governing permissions and 15 // limitations under the License. 16 17 package solace 18 19 import ( 20 "time" 21 22 "solace.dev/go/messaging/pkg/solace/config" 23 "solace.dev/go/messaging/pkg/solace/message" 24 "solace.dev/go/messaging/pkg/solace/resource" 25 ) 26 27 // The DirectMessagePublisher interface is used to publish direct messages. 28 type DirectMessagePublisher interface { 29 MessagePublisher 30 MessagePublisherHealthCheck 31 32 // StartAsyncCallback starts the DirectMessagePublisher asynchronously. 33 // Calls the specified callback when started with an error if one occurred, otherwise nil 34 // if successful. 35 StartAsyncCallback(callback func(DirectMessagePublisher, error)) 36 37 // SetPublishFailureListener sets the listener to call if the publishing of 38 // a direct message fails. 39 SetPublishFailureListener(listener PublishFailureListener) 40 41 // TerminateAsyncCallback terminates the DirectMessagePublisher asynchronously. 42 // Calls the callback when terminated with nil if successful, or an error if 43 // one occurred. If gracePeriod is less than 0, this function waits indefinitely. 44 TerminateAsyncCallback(gracePeriod time.Duration, callback func(error)) 45 46 // PublishBytes publishes a message of type byte array to the specified destination. 47 // Returns an error if one occurred while attempting to publish, or if the publisher 48 // is not started/terminated. Possible errors include: 49 // - solace/errors.*PubSubPlusClientError - If the message could not be sent and all retry attempts failed. 50 // - solace/errors.*PublisherOverflowError - If messages are published faster than the publisher's I/O 51 // capabilities allow. When publishing can be resumed, the registered 52 // PublisherReadinessListeners are called. 53 PublishBytes(message []byte, destination *resource.Topic) error 54 55 // PublishString publishes a message of type string to the specified destination. 56 // Returns an error if one occurred. Possible errors include: 57 // - solace/errors.*PubSubPlusClientError - If the message could not be sent and all retry attempts failed. 58 // - solace/errors.*PublisherOverflowError - If messages are published faster than the publisher's I/O 59 // capabilities allow. When publishing can be resumed, the registered PublisherReadinessListeners are called. 60 PublishString(message string, destination *resource.Topic) error 61 62 // Publish publishes the specified message of type OutboundMessage built by a 63 // OutboundMessageBuilder to the specified destination. Possible errors include: 64 // - solace/errors.*PubSubPlusClientError - If the message could not be sent and all retry attempts failed. 65 // - solace/errors.*PublisherOverflowError - If messages are published faster than the publisher's I/O 66 // capabilities allow. When publishing can be resumed, the registered PublisherReadinessListeners are called. 67 Publish(message message.OutboundMessage, destination *resource.Topic) error 68 69 // PublishWithProperties publishes the specified message of type OutboundMessage 70 // with the specified properties. These properties override the properties on 71 // the OutboundMessage instance if it is present. Possible errors include: 72 // - solace/errors.*PubSubPlusClientError - If the message could not be sent and all retry attempts failed. 73 // - solace/errors.*PublisherOverflowError - If messages are published faster than the publisher's I/O 74 // capabilities allow. When publishing can be resumed, the registered PublisherReadinessListeners are called. 75 PublishWithProperties(message message.OutboundMessage, destination *resource.Topic, properties config.MessagePropertiesConfigurationProvider) error 76 } 77 78 // PublishFailureListener is a listener that can be registered for publish failure events. 79 type PublishFailureListener func(FailedPublishEvent) 80 81 // FailedPublishEvent represents an event thrown when publishing a direct message fails. 82 type FailedPublishEvent interface { 83 // GetMessage retrieves the message that was not delivered 84 GetMessage() message.OutboundMessage 85 // GetDestination retrieves the destination that the message was published to. 86 GetDestination() resource.Destination 87 // GetTimeStamp retrieves the timestamp of the error. 88 GetTimeStamp() time.Time 89 // GetError retrieves the error that failed the publish attempt. 90 GetError() error 91 } 92 93 // DirectMessagePublisherBuilder allows for configuration of direct message publisher instances. 94 type DirectMessagePublisherBuilder interface { 95 96 // Build creates a new DirectMessagePublisher instance based on the configured properties. 97 // Returns solace/errors.*InvalidConfigurationError if an invalid configuration is provided. 98 Build() (messagePublisher DirectMessagePublisher, err error) 99 100 // OnBackPressureReject sets the publisher back pressure strategy to reject 101 // where publish attempts will be rejected once the bufferSize, in number of messages, is reached. 102 // If bufferSize is 0, an error will be thrown when the transport is full when publishing. 103 // A buffer of the given size will be statically allocated when the publisher is built. 104 // Valid bufferSize is >= 0. 105 OnBackPressureReject(bufferSize uint) DirectMessagePublisherBuilder 106 107 // OnBackPressureWait sets the publisher back pressure strategy to wait where publish 108 // attempts may block until there is space in the buffer of size bufferSize in number of messages. 109 // A buffer of the given size will be statically allocated when the publisher is built. 110 // Valid bufferSize is >= 1. 111 OnBackPressureWait(bufferSize uint) DirectMessagePublisherBuilder 112 113 // FromConfigurationProvider configures the direct publisher with the specified properties. 114 // The built-in PublisherPropertiesConfigurationProvider implementations include: 115 // - PublisherPropertyMap - A map of PublisherProperty keys to values. 116 FromConfigurationProvider(provider config.PublisherPropertiesConfigurationProvider) DirectMessagePublisherBuilder 117 } 118