WSO2 Micro Integrator 4.5.0 integreren met Solace PubSub+ Event Broker

Het integreren van applicaties met event brokers is een veelvoorkomende vereiste binnen moderne integratieprojecten. In dit artikel laten we zien hoe je WSO2 Micro Integrator 4.5.0 koppelt aan Solace PubSub+ Event Broker en berichten uitwisselt via JMS 2.0.

Het doel is om te laten zien hoe WSO2 Micro Integrator berichten kan publiceren naar Solace en berichten daaruit kan consumeren. We bekijken ook wat er achter de schermen gebeurt wanneer een bericht vanuit WSO2 MI naar de Solace broker wordt verzonden.

Op hoofdlijnen communiceert WSO2 Micro Integrator via de JMS 2.0 API. De Solace JMS-provider implementeert deze API en gebruikt intern JCSMP, de native Java API van Solace. JCSMP zet het bericht vervolgens om naar SMF, het wire protocol van Solace, voordat de broker het bericht ontvangt, verwerkt en routeert.

Deze gids is praktisch en gericht op implementatie. We starten met een lokale Solace broker voor development, waarna we zowel Solace als WSO2 Micro Integrator configureren voor het publiceren en consumeren van berichten.

In dit artikel behandelen we: 

1. Het opzetten van Solace PubSub+ Event Broker voor development. 
2. De message flow van WSO2 Micro Integrator naar Solace. 
3. Het configureren van Solace PubSub+ via de management console. 
4. Het instellen van WSO2 Micro Integrator als message publisher. 
5. Het instellen van WSO2 Micro Integrator als message consumer. 

Voordat we naar de use cases gaan, starten we eerst een Solace broker-instance en configureren we deze voor development. Zo hebben we een werkende omgeving die we in de rest van het artikel kunnen gebruiken.

1. De Solace Broker opzetten 

De eenvoudigste manier om een Solace-instance voor development te starten, is met behulp van de Docker-image. Voer simpelweg het onderstaande commando uit om een instance te starten. In dit artikel gebruiken we de Mac-versie.

docker run -d \ 
  --name=solace \ 
  -p 8080:8080 \     # PubSub+ Console (Web UI) 
  -p 55554:55555 \   # SMF (Solace Message Format) 
  -p 55443:55443 \   # SMFs (SMF over TLS) 
  -p 8008:8008 \     # REST 
  -p 1883:1883 \     # MQTT 
  -p 5672:5672 \     # AMQP 
  -p 9000:9000 \     # REST (Web Transport) 
  -p 2222:2222 \     # CLI (SSH) 
  --shm-size=2g \    # Shared memory for message spool 
  --env username_admin_globalaccesslevel=admin \ 
  --env username_admin_password=admin \ 
  --restart=unless-stopped \ 
  solace/solace-pubsub-standard:latest 
docker run -d --name=solace -p 8080:8080 -p 55554:55555 -p 55443:55443 -p 8008:8008 -p 1883:1883 -p 5672:5672 -p 9000:9000 -p 2223:2222 --shm-size=2g --env username_admin_globalaccesslevel=admin --env username_admin_password=admin --restart=unless-stopped solace/solace-pubsub-standard:latest 

Wanneer de container succesvol is gestart, kun je de status bekijken via Docker Desktop. 

Figuur 1: Docker Desktop Container Status 

Meer informatie over de poorten is te vinden in de Solace-documentatie. Onderstaande informatie is afkomstig uit de officiële documentatie voor de Software Broker. Voor andere typen brokers kunnen de poorten verschillen. Zie: Default Port Numbers

Via http://localhost:8080/ kun je inloggen op de Solace Console met gebruikersnaam admin en wachtwoord admin.

Figuur 2: Solace Console

2. Hoe de message flow in de Solace Broker werkt

Voordat we met de implementatie beginnen, is het belangrijk om te begrijpen hoe de message flow tussen WSO2 Micro Integrator en Solace werkt. Dit helpt om de configuratie correct op te zetten.

Figuur 2.1: Message Flow

6. De flow wordt gestart via de Axis2 JMS Transport in WSO2 Micro Integrator.
7. WSO2 Micro Integrator wordt beschikbaar gesteld via de standaard Java JMS 2.0-interface.
8. Solace JMS implementeert de javax.jms-interfaces met Solace-specifieke logica en vertaalt JMS-operaties naar JCSMP-calls.
9. Solace JCSMP verzorgt de onderliggende netwerkcommunicatie. Denk hierbij aan het beheren van TCP-verbindingen, het gebruik van het SMF-protocol, reconnect-mechanismen, flow control en het coderen en decoderen van berichten.
10. Zodra het bericht de Solace Broker bereikt, vindt eerst TLS-terminatie plaats bij de SMF Listener.
11. Na de TLS-terminatie wordt het bericht gerouteerd op basis van de Message VPN die is meegegeven via de gebruikersnaam, bijvoorbeeld console-vp-username@console-vpn, of via een aparte parameter vanuit JMS.

parameter.Solace_JMS_VPN = "console-vpn" 

12. Authenticatie wordt uitgevoerd op basis van de geconfigureerde methode, zoals Basic Authentication, Client Certificate, OAuth 2.0 of Kerberos.
13. Na succesvolle authenticatie wordt het Client Profile toegepast dat aan de gebruiker is gekoppeld. Dit bepaalt welke acties zijn toegestaan, zoals het verzenden of ontvangen van berichten.
14. Vervolgens wordt het ACL Profile gebruikt om te bepalen tot welke topics of queues de client toegang heeft.
15. Omdat we gebruikmaken van JMS JNDI, moeten daarnaast de benodigde JNDI-objecten worden aangemaakt. Hiermee kunnen clients lookups uitvoeren en verbinding maken met de juiste topics of queues.

3. Solace configureren via de Console

3.1 Een Message VPN aanmaken

1. Log in op http://localhost:8080 met admin/admin.
2. Klik in de linkernavigatie op Message VPNs.
3. Klik op + Create Message VPN.

Figuur 3: Create Message VPN

Op het volgende scherm zie je de standaard gebruikersconfiguratie. Wanneer een Message VPN in Solace wordt aangemaakt, bevat deze automatisch een ingebouwde client username met de naam default binnen die VPN. Tijdens het aanmaken vraagt de console om een wachtwoord voor deze gebruiker in te stellen. Als een client verbinding maakt met de VPN via een gebruikersnaam die niet overeenkomt met een expliciet geconfigureerde client username, valt Solace automatisch terug op deze default-gebruiker.

Figuur 4: Create Default User Configuration

Figuur 5: Weergave na succesvolle aanmaak van de Message VPN

3.2 Het Client Profile aanmaken

Het Client Profile bepaalt wat de client mag doen, zoals verzenden, ontvangen en guaranteed messaging gebruiken.

Navigeer naar console-vpn -> Access Control -> Client Profiles.

Klik op + Create Client Profile.

Figuur 6: Creating the Client Profile

Figuur 7: Enabling needed Configurations

Figuur 8: Successful Creation

3.3 Het ACL Profile aanmaken

Het ACL Profile bepaalt waar de client mag publiceren en subscriben, bijvoorbeeld op topic- of queue-niveau.

Figuur 9: Create ACL Profile

Figuur 10: Allow ACL Profiles

Standaard staat de actie ingesteld op Disallow. In een productieomgeving houd je deze instelling meestal op Disallow en voeg je expliciete uitzonderingen toe om specifieke toegang toe te staan. Voor deze gids laten we de configuratie echter open.

Dubbelklik op de optie Disallow. Hierdoor wordt de dropdown actief en kun je deze wijzigen naar Allow.

In dit voorbeeld staan we het volgende toe:

• Client Connect.
• Publish Topic.
• Subscribe Topic.

3.4 De Client Username aanmaken met Basic Authentication

Figuur 11: Client Username toevoegen

Figuur 12: Client Username toevoegen

Figuur 13: Client Username toevoegen

3.5 De Queue voor Guaranteed Messaging aanmaken en koppelen aan een topic subscription

Figuur 14: Queue aanmaken voor Guaranteed Delivery

Figuur 15: Aangemaakte Queue

Nu moeten we de topic subscription toevoegen.

Figuur 16: Topic Subscription toevoegen

Figuur 17: Toegevoegde Subscription

3.6 JNDI-objecten aanmaken

Hoewel we de Solace-libraries gebruiken voor het opzetten van de verbinding, gebeurt onder de motorkap het volgende:

WSO2 -> JMS 2.0 API -> Solace JMS Implementation -> Solace JCSMP Implementation -> Solace Broker.

Omdat WSO2 de JMS API gebruikt en de JMS API ConnectionFactory- en Destination-objecten via JNDI-lookups ophaalt, moeten de JNDI-objecten op de broker bestaan.

3.6.1 JNDI inschakelen op de Message VPN

• Navigeer naar console-vpn -> Settings.
• Schakel onder JNDI de optie JNDI Enabled in.
• Klik op Apply.

Figuur 18: JNDI inschakelen

3.6.2 Een JNDI Connection Factory aanmaken

• Navigeer naar console-vpn -> JNDI -> Connection Factories.
• Klik op + Create Connection Factory.
• Gebruik de volgende instellingen:
• Name: /jndi/cf/console-connection-factory
• Messaging Properties:
• Publisher Messages Delivery Mode: Persistent voor guaranteed messaging, of Non-Persistent voor direct messaging.
• Transport: SMF.
• Klik op Create.

Figuur 19: JNDI Connection Factory toevoegen

Figuur 20: JNDI Connection Factory toevoegen

3.6.3 Een JNDI Queue Object aanmaken

• Navigeer naar console-vpn -> JNDI -> Queues.
• Klik op + Create Queue.
• Gebruik de volgende instellingen:
• JNDI Name: /jndi/queue/console-queue
• Physical Name: console-queue
• Klik op Create.

Figuur 21: JNDI Queue toevoegen

Figuur 22: JNDI Queue toevoegen

Figuur 23: JNDI Queue toevoegen

3.6.4 Een JNDI-object voor een Physical Topic aanmaken

Figuur 24: Physical Topic

Figuur 25: Physical Topic

De configuratie die we tot nu toe hebben uitgevoerd, wordt samengevat in het onderstaande flowdiagram.

Figuur 26: Implementation Summary

4. WSO2 Micro Integrator instellen als message publisher

Nu kunnen we WSO2 Micro Integrator instellen om naar een topic te publiceren en berichten vanuit de queue te consumeren.

4.1 Benodigde JAR-bestanden downloaden

Download de onderstaande JAR-bestanden en plaats deze in MI_HOME/lib:

• sol-jcsmp-10.22.0.jar
• sol-jms-10.22.0.jar

Let op: versies vanaf 10.23 werken niet met WSO2 vanwege Netty-dependencies. Daarom gebruiken we hier de nieuwste versie die WSO2 MI 4.5.0 ondersteunt.

4.2 deployment.toml configureren voor de sender

[[transport.jms.sender]]

name = "solaceTopicSender"

parameter.initial_naming_factory = "com.solacesystems.jndi.SolJNDIInitialContextFactory"

parameter.provider_url = "smf://console-vpn-username:batticaloa@localhost:55554"

parameter.connection_factory_name = "/jndi/cf/console-connection-factory"

parameter.connection_factory_type = "topic"

parameter.Solace_JMS_VPN = "console-vpn"

4.3 CAR-file met API aanmaken

Maak vervolgens een CAR-file met een API zoals hieronder, waarmee berichten naar het topic worden gepubliceerd.

<?xml version="1.0" encoding="UTF-8"?> 
<api xmlns="http://ws.apache.org/ns/synapse" name="SolacePublisherAPI" context="/solace"> 
    <resource methods="POST" uri-template="/publish"> 
        <inSequence> 
            <!-- 1. Message Received at API --> 
            <log level="full"> 
                <property name="MESSAGE" value="Received request to publish to Solace"/> 
            </log> 
            <!-- 2. Set the properties out only and force sc accpeted to send back 202 --> 
            <property name="FORCE_SC_ACCEPTED" value="true" scope="axis2"/> 
            <property name="OUT_ONLY" value="true"/> 
            <!-- 3. Send to Solace topic via JMS --> 
            <send> 
                <endpoint> 
                    <address uri="jms:/console-vpn-sub/messages/order?transport.jms.ConnectionFactory=solaceTopicSender&transport.jms.DestinationType=topic"/> 
                </endpoint> 
            </send> 
        </inSequence> 
    </resource> 
</api>

4.4 API-call versturen

curl --request POST \

--url http://localhost:8290/solace/publish \

--header 'Content-Type: application/json' \

--data '{"Name":"Test 3"}'

4.5 Berichten controleren in Solace

Controleer de berichten in de Solace Broker Console.

Figuur 27: Bericht in de queue

Daarmee is de sender-implementatie afgerond. Nu kunnen we doorgaan met de consumer-implementatie.

5. Consumer-implementatie

5.1 deployment.toml configureren voor de consumer

[[transport.jms.listener]]

name = "solaceQueueListener"

parameter.initial_naming_factory = "com.solacesystems.jndi.SolJNDIInitialContextFactory"

parameter.provider_url = "smf://console-vpn-username:batticaloa@localhost:55554"

parameter.connection_factory_name = "/jndi/cf/console-connection-factory"

parameter.connection_factory_type = "queue"

parameter.Solace_JMS_VPN = "console-vpn"

parameter.session_transaction = true

Omdat we sessietransacties hebben ingeschakeld, moeten we direct transport uitschakelen.

Figuur 28: Direct Transport uitschakelen

5.2 JMS Proxy aanmaken

Maak vervolgens een JMS Proxy zoals hieronder. Let op: dit is een voorbeeldconfiguratie. Afhankelijk van de requirements kun je aanvullende properties of parameters toevoegen aan de listener.

<?xml version="1.0" encoding="UTF-8"?> 
<proxy xmlns="http://ws.apache.org/ns/synapse" name="SolaceQueueListener" transports="jms" startOnLoad="true">

    <target> 
        <inSequence> 
            <log level="full"> 
                <property name="SolaceQueueListener" value="Received message from Solace queue"/> 
            </log> 
        </inSequence> 
        <faultSequence> 
            <property name="SET_ROLLBACK_ONLY" value="true" scope="axis2"/> 
            <log level="custom"> 
                <property name="SolaceQueueListener" value="Transaction Rollbacked"/> 
            </log> 
        </faultSequence> 
    </target> 

    <parameter name="transport.jms.ContentType"> 
        <rules> 
            <jmsProperty>contentType</jmsProperty> 
            <default>application/json</default> 
        </rules> 
    </parameter> 

    <parameter name="transport.jms.Destination">/jndi/queue/console-queue</parameter> 
    <parameter name="transport.jms.ConnectionFactory">solaceQueueListener</parameter> 
</proxy>

5.3 Logs controleren

Aan de hand van de logs kun je zien dat de listener is gestart en het bericht succesvol heeft geconsumeerd.

INFO {LogMediator} - {api:SolacePublisherAPI} To: /solace/publish, MessageID: urn:uuid:1ad6f8ba-93a8-4d17-bd6a-3e56664622e6, correlation_id: 1ad6f8ba-93a8-4d17-bd6a-3e56664622e6, Direction: request, MESSAGE = Received request to publish to Solace, Payload: {"Name":"Test 8"} 
INFO {TcpClientChannel} - Client-10: Connecting to host 'orig=tcp://localhost:55554, scheme=tcp://, host=localhost, port=55554' (host 1 of 1, smfclient 10, attempt 1 of 1, this_host_attempt: 1 of 1) 
INFO {JCSMPBasicSession} - Client-10: AdCtrl version changes: 2->4 
INFO {TcpClientChannel} - Client-10: Connected to host 'orig=tcp://localhost:55554, scheme=tcp://, host=localhost, port=55554' (smfclient 10) 
INFO {TcpClientChannel} - Client-10: Channel Closed (smfclient 10) 
[2026-04-07 16:01:54,987]  INFO {TcpClientChannel} - Client-11: Connecting to host 'orig=tcp://localhost:55554, scheme=tcp://, host=localhost, port=55554' (host 1 of 1, smfclient 11, attempt 1 of 1, this_host_attempt: 1 of 1) 
INFO {JCSMPBasicSession} - Client-11: AdCtrl version changes: 2->4 
INFO {TcpClientChannel} - Client-11: Connected to host 'orig=tcp://localhost:55554, scheme=tcp://, host=localhost, port=55554' (smfclient 11) 
INFO {LogMediator} - {proxy:SolaceQueueListener} To: , WSAction: urn:mediate, SOAPAction: urn:mediate, MessageID: ID:192.168.2.16e59119d683fc4cb0:1, Direction: request, SolaceQueueListener = Received message from Solace queue, Payload: {"Name":"Test 8"}

6. Conclusie

Hiermee zijn we aan het einde gekomen van deze gids over het integreren van WSO2 Micro Integrator 4.5.0 met Solace PubSub+ Event Broker.

We hebben bekeken hoe berichten tussen WSO2 Micro Integrator en Solace stromen, inclusief de rol van JMS 2.0, de Solace JMS-provider, JCSMP en het SMF-protocol. Daarnaast hebben we stap voor stap Solace geconfigureerd, WSO2 Micro Integrator als publisher ingesteld en berichten geconsumeerd via WSO2 Micro Integrator API’s en een Proxy Service.

Met deze setup heb je een praktische basis om event-driven integraties te bouwen tussen WSO2 Micro Integrator en Solace PubSub+. Van hieruit kun je het voorbeeld verder uitbreiden met geavanceerdere routing, foutafhandeling, message persistence en realistische integratiescenario’s.

FAQ