This tutorial will get you started with Topics in the Message Broker profile (MB profile) of WSO2 Enterprise Integrator (WSO2 EI). This will also introduce the concepts of Hierarchical Topics, and Durable Subscriptions.
Prerequisites
Install WSO2 EI and download JMS clients as explained below.
Download and start the MB profile of WSO2 EI
Follow the steps given below to download and start the MB profile of WSO2 EI.
- Download WSO2 EI from here.
- Extract the ZIP file to a location on your computer. This location will be referred to as
<EI_HOME>
from hereon. - To start the MB profile: Open a terminal, navigate to the
<EI_HOME>/bin
directory where all the startup scripts are stored and run the startup script:- On Windows:
broker.bat
- On Linux:
sh broker.sh
- On Windows:
The URL of the management console will be printed in the terminal as follows: https://localhost/carbon/
Download and set up Apache JMeter
We will be using Apache JMeter for the purpose of simulating how a JMS client sends messages to the MB profile, and how such a client subscribes to topics and queues in the broker. Therefore, let us install and start Apache JMeter by following the steps given below.
Download Apache JMeter from here and install it. The location of your JMeter folder will be referred to as
<JMeter_HOME>
from hereon.Note that JMeter 2.13 version is used for this quick start guide.
- Copy the following JARs from the
<EI_HOME>/wso2/broker/client-lib
directory to the<JMeter_Home>/lib
folder:andes-client-3.2.4.jar
geronimo-jms_1.1_spec-1.1.0.wso2v1.jar
org.wso2.carbon.logging-4.4.26.jar
org.wso2.securevault-1.0.0-wso2v2.jar
In the following steps, we will go through the basics of creating topics in the MB profile by creating a simply hierarchy of topics and then setting up JMS clients as the subscriber and publisher for the topics.
Step 1: Creating the topic hierarchy
Let's start by creating the following hierarchy:
To add the topics and sub topics:
- Log in to the management console using the credentials of the default system administrator: admin/admin.
- In the Main tab, click Topics -> Add. The Add Topic screen will open.
- Enter 'games' as the topic name in the Topic field.
- Click Add Topic and the new topic will be listed in the Topic List page. You can access the Topic List page by clicking Topic -> List in the Main tab of the navigator.
- Click games in the topic list. This will open the following options:
- Click Add Subtopic to open the Add Sub Topic screen.
- Enter 'football' as the subtopic name and click Add Topic.
- Repeat the steps to add the remaining subtopics until you get the complete topics hierarchy.
Step 2: Creating the jnditopics.properties file
Create the following jnditopics.properties
file and save it to a location in your system. The details in this file will establish the connection between your JMeter clients and the required topics in the Message Broker instance.
# register some connection factories # connectionfactory.[jndiname] = [ConnectionURL] connectionfactory.TopicConnectionFactory = amqp://admin:admin@clientID/carbon?brokerlist='tcp://localhost:5675' # register some topics in JNDI using the form # topic.[jndiName] = [physicalName] topic.All_Games = games.# topic.All_Cricket = games.cricket.# topic.All_Football = games.football.# topic.Games_Only = games topic.Cricket_Only = games.cricket topic.Football_Only = games.football topic.Germany_Only = games.football.germany topic.Brazil_Only = games.football.brazil topic.Australia_Only = games.cricket.australia topic.India_Only = games.cricket.india
Note the following:
- We are using
localhost
as the IP address, which is the same IP we used for starting the management console of the MB profile. The physical name of the topics are mapped to jndi names according to the topic hierarchy. The following table describes the mapping:
JNDI Name Physical Name Description All_Games
games.#
Refers to the 'games' topic and all sub topics. All_Cricket
games.cricket.#
Refers to the 'cricket' topic and all sub topics. All_Football
games.football.#
Refers to the 'football' topic and all sub topics. Games_Only
games
Refers only to the 'games' topic. Cricket_Only
games.cricket
Refers only to the 'cricket' topic. Football_Only
games.football
Refers only to the 'football' topic. Germany_Only
games.football.germany
Refers only to the 'germany' topic. Brazil_Only
games.football.brazil
Refers only to the 'brazil' topic. Australia_Only
games.cricket.australia
Refers only to the 'australia' topic. India_Only
games.cricket.india
Refers only to the 'india' topic.
Step 3: Creating a non-durable subscription to topics
What are non-durable subscriptions?
When a subscriber client uses a non-durable subscription, the client can receive messages only when the subscriber-broker connection is active. Read more about durable/non-durable topic subscriptions.
We will now set up Apache JMeter as a JMS subscriber for the topics we created in the previous step. For this tutorial, we will create a subscription for All Topics in the topic hierarchy.
Follow the instructions given below.
- Start a new JMeter instance by executing the following script from the
<JMeter_Home>/bin
folder:- On windows:
jmeter.bat
- On Linux:
sh jmeter.sh
- On windows:
- Go to the JMeter UI and create a JMS subscriber as explained below.
- Create a new thread group: Right-click Test Plan (in the left navigator) and go to Add -> Threads (Users) -> Thread Group.
- The new thread group will now be listed in the left navigator under the Test Plan.
- Right-click on the new thread group and go to Add -> Sampler -> JMS Subscriber.
- Name this subscriber
Games Subscriber
. You will now have a JMS Subscriber node in the left navigator. Select this node and enter the following details:
Initial Context Factory org.wso2.andes.jndi.PropertiesFileInitialContextFactory The connection details you specified in the
jnditopics.properties
file should be entered for the JMS Subscriber as shown below.Provider URL The location where you saved the jnditopics.properties
file.Connection Factory TopicConnectionFactory
.Destination The jndi name given to the topic hierarchy in the jnditopics.properties
file. For example, to subscribe to all the topics in the topic hierarchy, enter 'All_Games'.- Right-click on the new Thread Group and go to Add -> Listener -> View Results in Tree. This will create a listener node in the JMeter navigator for analysing the output of the subscription.
Save the information. You now have a JMS client subscribed to the 'games' topic and all its child topics.
Execute the JMeter client.
Now, go to the management console of the Message Broker profile and go to Main -> Subscriptions -> Topic Subscription List. Your subscription will be listed as a non-durable topic subscription:
Step 4: Creating durable subscriptions to a topic
What are durable subscriptions?
When a subscriber client with a durable subscription connects to the broker, it will receive all messages that were published for the subscription (even while the subscriber-broker connection was inactive). Read more about durable/non-durable topic subscriptions.
Let's take two JMeter clients and create two separate durable subscriptions. For this tutorial, we will create subscriptions for All Topics in the topic hierarchy.
- Open two separate instances of JMeter by executing the following script from the
<JMeter_Home>/bin
folder:- On windows:
jmeter.bat
- On Linux:
sh jmeter.sh
- On windows:
Create JMS subscribers in both JMeter instances. Name them JMS Durable Subscriber 01 and JMS Durable Subscriber 2 respectively. Use the following connection details (same as for the non-durable subscription).
Initial Context Factory org.wso2.andes.jndi.PropertiesFileInitialContextFactory Provider URL This should be the location where you have the jnditopics.properties
file saved.Connection Factory This should be set to TopicConnectionFactory
.Destination This should be the jndi name given to the topic hierarchy in the jnditopics.properties
file. For example, to subscribe to all the topics in the topic hierarchy, enter 'All_Games'.In addition to the above configuations, be sure to add durable subscription IDs for both subscribers. Let's use Sub_1 and Sub_2 to identify the subscriptions.
For JMS Durable Subscriber 01:
Durable Subscription ID Sub_1 For JMS Durable Subscriber 02:
Durable Subscription ID Sub_2
- Right-click on the new test plan and go to Add -> Listener -> View Results in Tree. This will create a listener node in the JMeter navigator for analysing the output of the subscription.
Save the information.
- Execute both the JMeter instances.
- Now, go to the management console of the Message Broker profile and go to Main -> Subscriptions -> Topic Subscription List. The durable subscriptions will be listed as active durable subscriptions:
- Now, open the JMeter instance for JMS Durable Subscriber 02 and close the connection.
- Now, the disconnected durable subscriber will be listed as an inactive durable subscription in the management console as shown below.
Step 5: Publishing messages to topics
We will now set up Apache JMeter as a JMS publisher. Note that, in the previous steps, we created three subscriptions for All Topics in the topic hierarchy. This means all three subscribers should receive the messages published to any one of the topics in the topic hierarchy.
Follow the instructions given below.
Start a new JMeter instance by executing the following script from the
<JMeter_Home>/bin
folder:- On windows:
jmeter.bat
- On Linux:
sh jmeter.sh
- On windows:
Create a new test plan in JMeter: Right-click on Test Plan (in the left navigator) and go to Add -> Threads (Users) -> Thread Group.
- The new thread group will now be listed in the left navigator as a test plan.
- Right-click on the new test plan and go to Add -> Sampler -> JMS Publisher.
- Name this publisher Games Publisher.
You will now have a JMS Publisher node in the left navigator. Select this node and enter the following details:
Initial Context Factory org.wso2.andes.jndi.PropertiesFileInitialContextFactory The connection details you specified in the
jnditopics.properties
file should be entered for the JMS Publisher as shown below.Provider URL This should be the location where you have the jnditopics.properties
file saved.Connection Factory This should be set to TopicConnectionFactory
.Destination This should be the jndi name of the topic to which the message should be published. The jnditopics.properties file specifies the mapping between topic names and jndi names. For example, as specified in the jnditopics.properties file, enter 'Cricket_Only' if you want to publish a message to the cricket topic. Alternatively, you can publish to any of the following destinations: 'Football_Only', 'Germany_Only', 'Brazil_Only', 'India_Only', 'Australia_Only'. Expiration 0 Priority 0 Save the information. You now have a JMS client ready to send messages.
- Execute the JMeter publisher.
- Go back to the management console of the MB profile and go to Subscriptions -> Topic Subscription List in the Main tab. You will observe the following:
Note the following:- The non-durable topic subscription has immediately received the published messaged. You can verify this from the View Results in Tree tab of the respective JMeter client.
- The first durable subscription (Sub_1) has also received the published message. Verify this from the View Results in Tree tab of the respective JMeter client.
- The second durable subscription (Sub_2) has not received the message because the subscription was inactive. However, the unconsumed message is listed as a pending delivery for the subscriber as shown above. This means that as soon as Sub_2 becomes active, the message will be delivered.