Solace Bindings
This document defines how to describe Solace-specific information with AsyncAPI.
Version
Current version is 0.4.0.
Server Binding Object
| Field Name | Type | Description |
|---|---|---|
bindingVersion | String | The current version is 0.4.0 |
msgVpn | String | The Virtual Private Network name on the Solace broker. |
clientName | String | A unique client name to use to register to the appliance. If specified, it must be a valid Topic name, and a maximum of 160 bytes in length when encoded as UTF-8. |
Channel Binding Object
This object MUST NOT contain any properties. Its name is reserved for future use.
Operation Binding Object
We need the ability to support several bindings for each operation, see the Example section below for details.
| Field Name | Type | Description |
|---|---|---|
bindingVersion | String | The current version is 0.4.0 |
destinations | List of Destination Objects | Destination Objects are described next. |
timeToLive | Integer | Schema Object | Reference Object | Interval in milliseconds or a Schema Object containing the definition of the lifetime of the message. |
priority | Integer | Schema Object | Reference Object | The valid priority value range is 0-255 with 0 as the lowest priority and 255 as the highest or a Schema Object containing the definition of the priority. |
dmqEligible | Boolean | Set the message to be eligible to be moved to a Dead Message Queue. The default value is false. |
Destination Object
Each destination has the following structure:
| Field Name | Type | Description |
|---|---|---|
bindingVersion | String | The current version is 0.4.0 |
destinationType | Enum | 'queue' or 'topic'. If the type is queue, then the subscriber can bind to the queue, which in turn will subscribe to the topic as represented by the channel name or to the provided topicSubscriptions. |
deliveryMode | Enum | 'direct' or 'persistent'. This determines the quality of service for publishing messages as documented here. Default is 'persistent'. |
queue.name | String | The name of the queue, only applicable when destinationType is 'queue'. |
queue.topicSubscriptions | List of String | A list of topics that the queue subscribes to, only applicable when destinationType is 'queue'. If none is given, the queue subscribes to the topic as represented by the channel name. |
queue.accessType | Enum | 'exclusive' or 'nonexclusive'. This is documented here. Only applicable when destinationType is 'queue'. |
queue.maxMsgSpoolSize | String | The maximum amount of message spool that the given queue may use. This is documented here. Only applicable when destinationType is 'queue'. |
queue.maxTtl | String | The maximum TTL to apply to messages to be spooled. This is documented here. Only applicable when destinationType is 'queue'. |
topic.topicSubscriptions | List of String | A list of topics that the client subscribes to, only applicable when destinationType is 'topic'. If none is given, the client subscribes to the topic as represented by the channel name. |
Message Binding Object
This object MUST NOT contain any properties. Its name is reserved for future use.
Example with two destinations
Here is an example of when we could need two Solace destinations.
Imagine a system where there is a schema called Person, and there are topics:
person/{personId}/created
and
person/{personId}/updated
and you have one application that receives both events. We also want each to be on its own queue. The AsyncAPI file could look like this:
1components:
2 schemas:
3 Person:
4 type: string
5 messages:
6 PersonEvent:
7 payload:
8 $ref: '#/components/schemas/Person'
9 schemaFormat: application/vnd.aai.asyncapi+json;version=2.0.0
10 contentType: application/json
11operations:
12 addPerson:
13 action: send
14 channel:
15 $ref: '#/channels/address'
16 messages:
17 - $ref: '#/channels/address/messages/personEvent'
18 bindings:
19 solace:
20 bindingVersion: 0.4.0
21 destinations:
22 - destinationType: queue
23 queue:
24 name: CreatedHREvents
25 topicSubscriptions:
26 - person/*/created
27 - destinationType: queue
28 queue:
29 name: UpdatedHREvents
30 topicSubscriptions:
31 - person/*/updated
32 timeToLive: 5000
33 priority: 120
34 dmqEligible: true
35
36channels:
37 person:
38 address: person/{personId}/{eventType}
39 parameters:
40 personId:
41 schema:
42 type: string
43 eventType:
44 schema:
45 type: string
46 messages:
47 personEvent:
48 $ref: '#/components/messages/PersonEvent'
49asyncapi: 3.0.0
50info:
51 title: HRApp
52 version: 0.0.1The expected behavior would be that the application binds to both queues, and each queue has its own topic subscription, one to create and one to updated events.
Example with a wildcard subscription
This example shows how a client could receive all the topics under person/ using a wildcard subscription:
1components:
2 schemas:
3 Person:
4 type: string
5 messages:
6 PersonEvent:
7 payload:
8 schemaFormat: application/vnd.aai.asyncapi+json;version=3.0.0
9 schema:
10 $ref: '#/components/schemas/Person'
11 contentType: application/json
12operations:
13 addPerson:
14 action: send
15 channel:
16 $ref: '#/channels/person'
17 messages:
18 - $ref: '#/channels/person/messages/personEvent'
19 bindings:
20 solace:
21 bindingVersion: 0.4.0
22 destinations:
23 - destinationType: queue
24 queue:
25 name: CreatedHREvents
26 topicSubscriptions:
27 - person/*/created
28 - destinationType: queue
29 queue:
30 name: UpdatedHREvents
31 topicSubscriptions:
32 - person/*/updated
33 timeToLive: 5000
34 priority: 120
35 dmqEligible: true
36
37channels:
38 person:
39 address: person/{personId}/{eventType}
40 parameters:
41 personId:
42 description: The machine readable id of the person
43 eventType:
44 enum:
45 - create
46 - delete
47 messages:
48 personEvent:
49 $ref: '#/components/messages/PersonEvent'
50asyncapi: 3.0.0
51info:
52 title: HRApp
53 version: 0.0.1