This documentation is for WSO2 Enterprise Integrator version 6.3.0 . View documentation for the latest release.
Pub-Sub Messaging using Topics - Enterprise Integrator Documentation - WSO2 Documentation

All docs This doc
||
Skip to end of metadata
Go to start of metadata

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 the product installer from here, and run the installer.
    Let's call the installation location of your product the <EI_HOME> directory.

    Note that if you used the product installer to install your product, the <EI_HOME> is located in a place specific to your OS as shown below:

    OSHome directory
    Mac OS/Library/WSO2/EnterpriseIntegrator/6.3.0
    WindowsC:\Program Files\WSO2\EnterpriseIntegrator\6.3.0\
    Ubuntu/usr/lib/wso2/EnterpriseIntegrator/6.3.0
    CentOS/usr/lib64/EnterpriseIntegrator/6.3.0
  2. Start the Message Broker profile:

    Open a terminal and execute the following command:

    wso2ei-6.3.0-broker
    Go to Start Menu -> Programs -> WSO2 -> Enterprise Integrator 6.3.0 Broker. This will open a terminal and start the Message Broker profile.
  3. The URL of the management console will be printed in the terminal as follows: https://localhost:9446/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 tutorial.

  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 simple 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 subtopics:

  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 jnditopics.properties file shown below 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 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 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 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 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 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.
    Destination

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

    Note that the publishing destination has to be a specific topic in the topic hierarchy. For example, the 'Football_Only' jndi name corresponds to the 'football' topic only. This means, you cannot publish messages to multiple topics at the same time. For example, you cannot specify 'All_Games' as the destination because the 'All_Games' jndi name corresponds to multiple topics (that is, the 'games' topic and its child topics).

    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.
  • No labels