diff --git a/en/docs/develop/integration-artifacts/event/solace.md b/en/docs/develop/integration-artifacts/event/solace.md index 33bc87bc9ec..8217c903170 100644 --- a/en/docs/develop/integration-artifacts/event/solace.md +++ b/en/docs/develop/integration-artifacts/event/solace.md @@ -27,28 +27,9 @@ Solace event integrations consume messages from a Solace PubSub+ queue or topic | **Message VPN** | The message VPN to connect to. | `default` | | **Destination** | Whether to consume from a **Queue** or a **Topic**. | `Queue` | - **When Destination is Queue:** - - | Field | Description | Default | - |---|---|---| - | **Queue Name** | Queue to listen for incoming messages. | `test-queue` | - | **Session Acknowledgment Mode** | How received messages are acknowledged. Options: `AUTO_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE`, `DUPS_OK_ACKNOWLEDGE`, `SESSION_TRANSACTED`. | `AUTO_ACKNOWLEDGE` | - - **When Destination is Topic:** - - | Field | Description | Default | - |---|---|---| - | **Topic Name** | Topic to listen for incoming messages. | `test/topic` | - | **Subscriber Name** | Name to use for the subscription. | `default` | - | **Durable Subscriber** | When enabled, persists the subscription when the client disconnects. | — | - | **Session Acknowledgment Mode** | How received messages are acknowledged. Options: `AUTO_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE`, `DUPS_OK_ACKNOWLEDGE`, `SESSION_TRANSACTED`. | `AUTO_ACKNOWLEDGE` | - - Expand **Advanced Configurations** to set the listener name and authentication method. + + - | Field | Description | Default | - |---|---|---| - | **Listener Name** | Identifier for the listener created with this service. | `solaceListener` | - | **Authentication method** | How to authenticate with the Solace broker. Select **Basic Authentication**, **Kerberos Authentication**, or **OAuth 2.0 Authentication**. | `Basic Authentication` | **Basic Authentication fields:** @@ -58,6 +39,8 @@ Solace event integrations consume messages from a Solace PubSub+ queue or topic | **Password** | Password for broker authentication. | | **Secure Socket** | SSL/TLS configuration for a secure connection. | + + **Kerberos Authentication fields:** | Field | Description | Default | @@ -65,18 +48,56 @@ Solace event integrations consume messages from a Solace PubSub+ queue or topic | **Service Name** | Kerberos service name. | `solace` | | **JAAS Login Context** | JAAS login context name. | `SolaceGSS` | | **Mutual Authentication** | Enable Kerberos mutual authentication. | Enabled | - | **JAAS Config Reload** | Enable automatic JAAS configuration reload. | — | - | **Secure Socket** | SSL/TLS configuration for a secure connection. | — | + | **JAAS Config Reload** | Enable automatic JAAS configuration reload. | - | + | **Secure Socket** | SSL/TLS configuration for a secure connection. | - | + + + **OAuth 2.0 Authentication fields:** | Field | Description | Default | |---|---|---| | **Issuer** | OAuth 2.0 issuer identifier URI. | `https://auth.example.com` | - | **Access Token** | OAuth 2.0 access token for authentication. | — | - | **OIDC Token** | OpenID Connect ID token for authentication. | — | - | **Secure Socket** | SSL/TLS configuration for a secure connection. | — | + | **Access Token** | OAuth 2.0 access token for authentication. | - | + | **OIDC Token** | OpenID Connect ID token for authentication. | - | + | **Secure Socket** | SSL/TLS configuration for a secure connection. | - | + + + + + + + + **When Destination is Queue:** + + | Field | Description | Default | + |---|---|---| + | **Queue Name** | Queue to listen for incoming messages. | `test-queue` | + | **Session Acknowledgment Mode** | How received messages are acknowledged. Options: `AUTO_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE`, `DUPS_OK_ACKNOWLEDGE`, `SESSION_TRANSACTED`. | `AUTO_ACKNOWLEDGE` | + + + + **When Destination is Topic:** + + | Field | Description | Default | + |---|---|---| + | **Topic Name** | Topic to listen for incoming messages. | `test/topic` | + | **Subscriber Name** | Name to use for the subscription. | `default` | + | **Durable Subscriber** | When enabled, persists the subscription when the client disconnects. | - | + | **Session Acknowledgment Mode** | How received messages are acknowledged. Options: `AUTO_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE`, `DUPS_OK_ACKNOWLEDGE`, `SESSION_TRANSACTED`. | `AUTO_ACKNOWLEDGE` | + + + + Expand **Advanced Configurations** to set the listener name and authentication method. + + | Field | Description | Default | + |---|---|---| + | **Listener Name** | Identifier for the listener created with this service. | `solaceListener` | + | **Authentication method** | How to authenticate with the Solace broker. Select **Basic Authentication**, **Kerberos Authentication**, or **OAuth 2.0 Authentication**. | `Basic Authentication` | + + 4. Click **Create**. 5. WSO2 Integrator opens the service in the **Service Designer**. The canvas shows the attached listener pill, the destination name pill, and an empty **Event Handlers** section. @@ -88,6 +109,8 @@ Solace event integrations consume messages from a Solace PubSub+ queue or topic +Define a Solace listener and attach a service with the `@solace:ServiceConfig` annotation to consume messages: + ```ballerina import ballerinax/solace; import ballerina/log; @@ -132,7 +155,7 @@ In the **Service Designer**, click the **Configure** icon in the header to open -![Solace Event Integration Configuration panel — service config and listener URL](/img/develop/integration-artifacts/event/solace/step-service-config.png) +![Solace Event Integration Configuration panel - service config and listener URL](/img/develop/integration-artifacts/event/solace/step-service-config.png) The **Service Configuration** field accepts a record expression that sets the destination and message handling options. @@ -155,6 +178,8 @@ The **Service Configuration** field accepts a record expression that sets the de +Set the destination and message-handling options in the `@solace:ServiceConfig` annotation. Use `queueName` for a queue or `topicName` for a topic: + ```ballerina // Queue subscription @solace:ServiceConfig { @@ -183,12 +208,6 @@ In the **Solace Event Integration Configuration** panel, select **solaceListener - - - | Field | Description | Default | |---|---|---| | **Name** | Identifier for the listener. | `solaceListener` | @@ -196,14 +215,14 @@ In the **Solace Event Integration Configuration** panel, select **solaceListener | **Message VPN** | The name of the message VPN to connect to. | `default` | | **Auth** | Authentication configuration. Supports basic authentication, Kerberos, and OAuth 2.0. For client certificate authentication, configure the `secureSocket.keyStore` field. | `{username: "default"}` | | **Secure Socket** | SSL/TLS configuration for secure connections. | `{}` | -| **Transacted** | Enables transacted messaging. When `true`, messages are sent and received within a transaction context requiring explicit commit or rollback. Must be `false` for XA transactions. | — | -| **Client Id** | Client identifier. If not specified, a unique client ID is auto-generated. | — | -| **Client Description** | Human-readable description of the client connection. | — | -| **Allow Duplicate Client Id** | Whether to allow the same client ID across multiple connections. | — | -| **Enable Dynamic Durables** | Enables automatic creation of durable queues and topic endpoints on the broker. | — | -| **Direct Transport** | When `true`, uses direct (at-most-once) delivery. When `false`, uses guaranteed (persistent) delivery. Must be `false` for transacted sessions. | — | -| **Direct Optimized** | Optimizes message delivery in direct transport mode by reducing protocol overhead. Only applicable when **Direct Transport** is `true`. | — | -| **Localhost** | Local interface IP address to bind for outbound connections. | — | +| **Transacted** | Enables transacted messaging. When `true`, messages are sent and received within a transaction context requiring explicit commit or rollback. Must be `false` for XA transactions. | - | +| **Client Id** | Client identifier. If not specified, a unique client ID is auto-generated. | - | +| **Client Description** | Human-readable description of the client connection. | - | +| **Allow Duplicate Client Id** | Whether to allow the same client ID across multiple connections. | - | +| **Enable Dynamic Durables** | Enables automatic creation of durable queues and topic endpoints on the broker. | - | +| **Direct Transport** | When `true`, uses direct (at-most-once) delivery. When `false`, uses guaranteed (persistent) delivery. Must be `false` for transacted sessions. | - | +| **Direct Optimized** | Optimizes message delivery in direct transport mode by reducing protocol overhead. Only applicable when **Direct Transport** is `true`. | - | +| **Localhost** | Local interface IP address to bind for outbound connections. | - | | **Connect Timeout** | Maximum time in seconds permitted for a JNDI connection attempt. Set to `0` to wait indefinitely. | `0.0` | | **Read Timeout** | Maximum time in seconds permitted for reading a JNDI lookup reply from the host. | `0.0` | | **Compression Level** | ZLIB compression level. Valid range is 0–9, where `0` disables compression. Higher values improve compression at the cost of throughput. | `0` | @@ -217,6 +236,8 @@ Click **Save Changes** to apply updates. +Configure the listener by passing fields to the `solace:Listener` constructor: + ```ballerina listener solace:Listener solaceListener = check new ( url = "smf://localhost:55554", @@ -238,20 +259,20 @@ listener solace:Listener solaceListener = check new ( |---|---|---|---| | **url** | `string` | Required | Solace broker URL | | **messageVpn** | `string` | `"default"` | Message VPN name | -| **auth** | `solace:BasicAuthConfig\|solace:KerberosConfig\|solace:OAuth2Config` | — | Authentication configuration | -| **secureSocket** | `solace:SecureSocket?` | — | SSL/TLS configuration | -| **transacted** | `boolean?` | — | Enable transacted messaging | -| **clientId** | `string?` | — | Client identifier | -| **clientDescription** | `string?` | — | Client description | -| **allowDuplicateClientId** | `boolean?` | — | Allow duplicate client IDs | -| **enableDynamicDurables** | `boolean?` | — | Auto-create durable endpoints | -| **directTransport** | `boolean?` | — | Use direct (at-most-once) delivery | -| **directOptimized** | `boolean?` | — | Optimize direct transport delivery | -| **localhost** | `string?` | — | Local interface IP address | +| **auth** | `solace:BasicAuthConfig\|solace:KerberosConfig\|solace:OAuth2Config` | - | Authentication configuration | +| **secureSocket** | `solace:SecureSocket?` | - | SSL/TLS configuration | +| **transacted** | `boolean?` | - | Enable transacted messaging | +| **clientId** | `string?` | - | Client identifier | +| **clientDescription** | `string?` | - | Client description | +| **allowDuplicateClientId** | `boolean?` | - | Allow duplicate client IDs | +| **enableDynamicDurables** | `boolean?` | - | Auto-create durable endpoints | +| **directTransport** | `boolean?` | - | Use direct (at-most-once) delivery | +| **directOptimized** | `boolean?` | - | Optimize direct transport delivery | +| **localhost** | `string?` | - | Local interface IP address | | **connectTimeout** | `decimal` | `30.0` | Connection timeout in seconds | | **readTimeout** | `decimal` | `10.0` | Read timeout in seconds | | **compressionLevel** | `int` | `0` | ZLIB compression level (0–9) | -| **retryConfig** | `solace:RetryConfig?` | — | Retry configuration | +| **retryConfig** | `solace:RetryConfig?` | - | Retry configuration | @@ -265,22 +286,22 @@ listener solace:Listener solaceListener = check new ( In the **Service Designer**, click **+ Add Handler**. The **Select Handler to Add** panel lists `onMessage` and `onError`. -**onMessage** — opens a configuration panel before saving: - -![onMessage handler configuration panel](/img/develop/integration-artifacts/event/solace/step-add-handler.png) +**onMessage** - opens a configuration panel before saving: + ![Service Designer showing the Solace Event Integration canvas](/img/develop/integration-artifacts/event/solace/adding-event-handler.png) + | Option | Description | |---|---| | **+ Define Payload** | Define the expected content type of the incoming message (e.g., a typed record). | Click **Save** to add the handler. -**onError** — added directly without additional configuration. +**onError** - added directly without additional configuration. -**onMessage handler** — called for each message received: +**onMessage handler** - called for each message received: ```ballerina type TradeEvent record {| @@ -306,7 +327,7 @@ service on solaceListener { } ``` -**onError handler** — called when message retrieval or processing fails: +**onError handler** - called when message retrieval or processing fails: ```ballerina service on solaceListener { @@ -329,6 +350,6 @@ service on solaceListener { ## What's next -- [Kafka](kafka.md) — consume messages from Apache Kafka topics -- [RabbitMQ](rabbitmq.md) — consume messages from RabbitMQ queues -- [Connections](../supporting/connections.md) — reuse Solace connection credentials across services +- [Kafka](kafka.md) - consume messages from Apache Kafka topics +- [RabbitMQ](rabbitmq.md) - consume messages from RabbitMQ queues +- [Connections](../supporting/connections.md) - reuse Solace connection credentials across services diff --git a/en/static/img/develop/integration-artifacts/event/solace/adding-event-handler.png b/en/static/img/develop/integration-artifacts/event/solace/adding-event-handler.png new file mode 100644 index 00000000000..453431af7dc Binary files /dev/null and b/en/static/img/develop/integration-artifacts/event/solace/adding-event-handler.png differ diff --git a/en/static/img/develop/integration-artifacts/event/solace/step-creation-form.png b/en/static/img/develop/integration-artifacts/event/solace/step-creation-form.png index 714812d8b1a..a744fdf25a7 100644 Binary files a/en/static/img/develop/integration-artifacts/event/solace/step-creation-form.png and b/en/static/img/develop/integration-artifacts/event/solace/step-creation-form.png differ diff --git a/en/static/img/develop/integration-artifacts/event/solace/step-service-config.png b/en/static/img/develop/integration-artifacts/event/solace/step-service-config.png index 2f00cdd4a2d..5448dba2b66 100644 Binary files a/en/static/img/develop/integration-artifacts/event/solace/step-service-config.png and b/en/static/img/develop/integration-artifacts/event/solace/step-service-config.png differ diff --git a/en/static/img/develop/integration-artifacts/event/solace/step-service-designer.png b/en/static/img/develop/integration-artifacts/event/solace/step-service-designer.png index b73546f9c07..9310b4ce37d 100644 Binary files a/en/static/img/develop/integration-artifacts/event/solace/step-service-designer.png and b/en/static/img/develop/integration-artifacts/event/solace/step-service-designer.png differ