This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Pub-Sub Messaging using Topics

Owned by Former user (Deleted)
Last updated: Jul 09, 2018
7 min read

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.

  1. Download WSO2 EI from here.
  2. Extract the ZIP file to a location on your computer. This location will be referred to as <EI_HOME> from hereon.
  3. 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

  4. 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.

  1. 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.

  2. 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:

  1. Log in to the management console using the credentials of the default system administrator: admin/admin.
  2. In the Main tab, click Topics -> Add. The Add Topic screen will open.
  3. Enter 'games' as the topic name in the Topic field.
  4. 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.
  5. Click games in the topic list. This will open the following options:
  6. Click Add Subtopic to open the Add Sub Topic screen. 
  7. Enter 'football' as the subtopic name and click Add Topic.
  8. 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 NamePhysical NameDescription
    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_Onlygames.cricketRefers only to the 'cricket' topic.
    Football_Onlygames.footballRefers only to the 'football' topic.
    Germany_Onlygames.football.germanyRefers only to the 'germany' topic.
    Brazil_Onlygames.football.brazilRefers only to the 'brazil' topic.
    Australia_Onlygames.cricket.australiaRefers only to the 'australia' topic.
    India_Onlygames.cricket.indiaRefers 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.

  1. 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
  2.  Go to the JMeter UI and create a JMS subscriber as explained below.
    1. Create a new thread group: Right-click Test Plan (in the left navigator) and go to Add -> Threads (Users) -> Thread Group.
    2. The new thread group will now be listed in the left navigator under the Test Plan.
    3. Right-click on the new thread group and go to Add -> Sampler -> JMS Subscriber.
    4. Name this subscriber Games Subscriber.

    5. You will now have a JMS Subscriber node in the left navigator. Select this node and enter the following details:

      Initial Context Factoryorg.wso2.andes.jndi.PropertiesFileInitialContextFactory

    6. The connection details you specified in the jnditopics.properties file should be entered for the JMS Subscriber as shown below.

      Provider URLThe location where you saved the jnditopics.properties file.
      Connection FactoryTopicConnectionFactory.
      DestinationThe 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'.
    7. Right-click on the new Thread Group and go to Add -> Listener -> View Results Tree. This will create a listener node in the JMeter navigator for analysing the output of the subscription.

    8. Save the information. You now have a JMS client subscribed to the 'games' topic and all its child topics.

  3. Execute the JMeter client.

  4. 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. 

  1. 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

  2. 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 Factoryorg.wso2.andes.jndi.PropertiesFileInitialContextFactory
    Provider URLThis should be the location where you have the jnditopics.properties file saved.
    Connection FactoryThis should be set to TopicConnectionFactory.
    DestinationThis 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'.

  3. 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.

    1. For JMS Durable Subscriber 01:

      Durable Subscription IDSub_1

    2. For JMS Durable Subscriber 02:

      Durable Subscription IDSub_2
  4. Right-click on the new Thread Group and go to Add -> Listener -> View Results Tree. This will create a listener node in the JMeter navigator for analysing the output of the subscription.

  5. Save the information.

  6. Execute both the JMeter instances. 
  7. 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:
  8. Now, open the JMeter instance for JMS Durable Subscriber 02 and stop the execution. 
  9. 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.

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.

  1. 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

  2. Create a new Thread Group in JMeter: Right-click on Test Plan (in the left navigator) and go to Add -> Threads (Users) -> Thread Group.

  3. The new thread group will now be listed in the left navigator under the Test Plan.
  4. Right-click on the new Thread Group and go to Add -> Sampler -> JMS Publisher.
  5. Name this publisher Games Publisher.

  6. You will now have a JMS Publisher node in the left navigator. Select this node and enter the following details:

    Initial Context Factoryorg.wso2.andes.jndi.PropertiesFileInitialContextFactory

  7. The connection details you specified in the jnditopics.properties file should be entered for the JMS Publisher as shown below.

    Provider URLThe location where you saved the jnditopics.properties file.
    Connection FactoryTopicConnectionFactory.
    DestinationThe 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'.
    Expiration0
    Priority0

  8. Save the information. You now have a JMS client ready to send messages.

  9. Execute the JMeter publisher.

  10. 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:

    1. 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.
    2. 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.
    3. 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.