Provisioning and Deprovisioning Queues with the PubSub+ Go API

There are two ways that durable queues can be provisioned on a PubSub+ event broker:

An administrator can manually provision a durable queue through the Broker Manager, SEMP, the Solace CLI, or SolAdmin.
In a connected MessagingService, a client can dynamically provision a durable queue through the PubSub+ Go API.

To dynamically provision or deprovision a durable queue, see the following sections:

Provisioning Durable Queues
Deprovisioning Durable Queues

It is also possible to provision durable and non-durable queues using the Missing Resource Creation Strategy. For more information, see Provisioning Durable and Non-Durable Queues with Missing Resource Creation Strategy

Provisioning Durable Queues

The following steps show how to create an API representation of a durable queue and provision it on the event broker:

Set your queue properties using methods from the EndpointProvisioner interface. Properties that you do not configure are set to the event broker defaults.

provisioner := messagingService.EndpointProvisioner().
    WithMaxMessageRedelivery(10).                    // number of times queue messages will be redelivered before moving to the DMQ
    WithDiscardNotification(true).                   // will notify senders about message discards
    WithTTLPolicy(true).                             // respect message TTL on queue
    WithQuotaMB(100).                                // set the queue message quota (in MB)
    WithMaxMessageSize(1000000).                     // set Max message size (in Bytes)
    WithExclusiveAccess(true).                       // provision an Exclusive queue
    WithPermission(config.EndpointPermissionDelete)  // with the delete permission
    // For a complete list of properties, see the EndPointProvisioner interface in the PubSub+ Messaging API for Go reference

You can provision multiple queues with different names on the event broker, but they will all share the same properties set with the EndpointProvisioner instance.

There are three methods you can use to provision a durable queue. All provision methods take a parameter, ignoreExists, which is a boolean that if set to:

true—The method does not return an error if a queue with the same name and properties already exists on the event broker.
false—The method returns an error if a queue with the same name and properties already exists on the event broker.

Synchronous method—Call the Provision() method and pass in the name of your queue. Provision() blocks the execution of your application until the queue is provisioned on the event broker:

var outcome solace.ProvisionOutcome
outcome = provisioner.Provision("queueName", false)

fmt.Println("Queue Provision on the event broker [Status]: ", outcome.GetStatus())
fmt.Println("Queue Provision on the event broker [Error]: ", outcome.GetError())

Asynchronous method with channels—Call the ProvisionAsync() method and pass in the name of your queue. ProvisionAsync() immediately returns a channel which eventually yields the provision outcome:

outcomeChannel := provisioner.ProvisionAsync("queueName", false)
            
outcome := <-outcomeChannel
fmt.Println("Queue Provision Async on the event broker [Status]: ", outcome.GetStatus())
fmt.Println("Queue Provision Async on the event broker [Error]: ", outcome.GetError())

Asynchronous method with a callback handler—Call the ProvisionAsyncWithCallback() method and pass in the name of your queue and callback handler. ProvisionAsyncWithCallback() uses a callback handler instead of a channel to notify your application of the provision outcome:

provisionCallbackHandler := func(outcome solace.ProvisionOutcome) {
    fmt.Println("Queue Provision Async With Callback on the event broker [Status]: ", outcome.GetStatus())
    fmt.Println("Queue Provision Async With Callback on the event broker [Error]: ", outcome.GetError())
}

provisioner.ProvisionAsyncWithCallback("queueName", false, provisionCallbackHandler)

Deprovisioning Durable Queues

There are two ways that durable queues can be deprovisioned from an event broker:

An administrator can remove a durable queue on an event broker through the Broker Manager, Solace CLI, SEMP, or SolAdmin.
A client application can all of the following listed methods with the queue name as a parameter to remove a durable queue that was previously provisioned using the PubSub+ Go API.

A client can only remove a queue if it originally provisioned the queue (that is, if it is the owner of the queue) or if the queue is provisioned with delete permission level, which allows other clients to remove the queue (refer to Defining Endpoint Properties).

Queues created via a management interface (Broker Manager, SolAdmin, CLI or SEMP) can be deprovisioned and deleted only by management. That is, if the queue was created by management, it cannot be deprovisioned by a client using an API, regardless of the configured permission.

The following steps show the three ways to deprovision a durable queue. All deprovision methods contain a parameter, ignoreMissing, which is a boolean that if set to:

true—The method does not return an error if no matching queue is found on the event broker.
false— The method returns an error if no matching queue is found on the event broker.

Synchronous method—Call the Deprovision() method, which deprovisions the queue with the given name from the event broker and blocks your application until the method returns:
```
deprovError := messagingService.EndpointProvisioner().Deprovision("queueName", false)
fmt.Println("Queue Deprovision on the event broker [Error]: ", deprovError)
```
Asynchronous method with channels—Call the DeprovisionAsync() method, which deprovisions the queue with the given name from the event broker and immediately returns a channel that will eventually yield the deprovision outcome:
```
errorChannel := messagingService.EndpointProvisioner().DeprovisionAsync("queueName", false)
deprovError := <-errorChannel
fmt.Println("Queue Deprovisioner Aysnc on the event broker [Error]: ", deprovError)		
```

Asynchronous method with a callback handler—Call the DeprovisionAsyncWithCallback() method, which deprovisions the queue with the given name from the event broker and uses a callback handler instead of a channel to notify your application of the deprovision outcome:

deprovisionCallbackHandler := func(deprovError error) {
    fmt.Println("Queue Deprovisioner Aysnc With Callback on the event broker [Error]: ", deprovError)
}
messagingService.EndpointProvisioner().DeprovisionAsyncWithCallback("queueName", false, deprovisionCallbackHandler)

Provisioning Durable and Non-Durable Queues with Missing Resource Creation Strategy

It is possible to provision queues on the Solace event broker using the Missing Resource Creation Strategy. These queues can be durable or non-durable (see our blog post Understanding Solace Endpoints: Durable vs. Non-Durable), and are not provisioned on the event broker until you call Start() on your PersistentMessageReceiver.

Creating a Non-Durable Queue

To create a non-durable queue, pass resource.QueueNonDurableExclusive(queueName) into the parameters of the Build() function when building a PeristentMessageReceiver. The queue is provisioned on the event broker when you call the Start() function on your PersistentMessageReceiver. This non-durable queue is deleted after the client application that created the queue disconnects from the event broker. The following example shows how to create a non-durable queue:

nonDurableExclusiveQueue := resource.QueueNonDurableExclusive("queueName")  // Creates a reference to an exclusive, non-durable queue with the specified name
topic := resource.TopicSubscriptionOf(topicString)                          // Creates a TopicSubscription of the specified topic string

// Creates an instance of PersistentMessageReceiverBuilder, which is used to create PersistentMessageReceivers.               
persistentReceiver, err := messagingService.CreatePersistentMessageReceiverBuilder().
	WithSubscriptions(topic).                                           // Sets a list of TopicSubscriptions to subscribe to when starting the receiver.
	Build(nonDurableExclusiveQueue)	                                    // Returns *IllegalArgumentError if the queue is nil.

If the client disconnects unexpectedly, for example, due to a networking issue, the queue is not deleted until 60 seconds later. This allows auto-reconnect logic to reconnect the client to the queue before it disappears.

Creating a Durable Queue

To create a durable queue, call the WithMissingResourcesCreationStrategy()function when building your PersistentMessageReceiver. MissingResourcesCreationStrategy takes a parameter that has two possible values:

config.MissingResourcesCreationStrategy(config.PersistentReceiverDoNotCreateMissingResources)— The default value, which disables any attempt to create missing resources.
config.MissingResourcesCreationStrategy(config.PersistentReceiverCreateOnStartMissingResources)— Creates the queue provided in the Build() function as long as the client has sufficient permissions (an exception is thrown otherwise).

The queue is provisioned on the event broker when you call the Start() function on your PersistentMessageReceiver.

The following example shows how to create a durable queue using the Missing Resource Creation Strategy:

durableExclusiveQueue := resource.QueueDurableExclusive("queueName")        // Creates an exclusive, durable queue with the specified name
topic := resource.TopicSubscriptionOf(topicString)                          // Creates a TopicSubscription of the specified topic string
strategy := config.MissingResourcesCreationStrategy(config.PersistentReceiverCreateOnStartMissingResources)      // Represents the various missing resource creation strategies available to publishers requiring guaranteed resources

// Creates an instance of PersistentMessageReceiverBuilder, which is used to create PersistentMessageReceivers.               
persistentReceiver, err := messagingService.CreatePersistentMessageReceiverBuilder().
	WithMissingResourcesCreationStrategy(strategy).                     // Defines what actions the API may take when missing resources are detected.
	WithSubscriptions(topic).				            // Sets a list of TopicSubscriptions to subscribe to when starting the receiver.
	Build(durableExclusiveQueue)                                        // Returns *IllegalArgumentError if the queue is nil.

The PubSub+ event broker can be configured with queue templates, that allows you to set custom attributes on queues you create with the Go API. When using the Missing Resource Creation Strategy, queue templates will only override the provided queue attributes if the name of the queue you create matches the template name-filter. For information about queue templates and instructions on how to configure a queue template using the Solace CLI, see Queues and Topic Endpoints and Configuring Endpoint Templates, respectively.

To deprovision queues created with the Missing Resource Creation Strategy, use SEMP, the SolacePubSub+ event broker Command Line Interface (CLI), or one of the deprovision methods listed in Deprovisioning Durable Queues.

Provide feedback