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

Quick Start Guide

Owned by Former user (Deleted)
Last updated: May 09, 2018
11 min read

The purpose of this guide is to get you started on the main features of WSO2 Message Broker (MB) as quickly as possible. We will create a few queues and topics and see how a JMS client can be configured to operate as a publisher and subscriber.

Key concepts and features

Explained below are some of the key elements and features in WSO2 MB.

Queues

Queues in WSO2 MB are essentially message stores, which can store messages from external JMS clients (publishers) and maintain them in an intermediate state until they are consumed by other JMS clients (subscribers).

Topics

Topics in WSO2 MB are used for realtime message brokering. As depicted by the following diagram, you can maintain a hierarchy of topics or subjects in MB for which messages can be published by external JMS clients (publishers). Other JMS clients (subscribers) can subscribe to the topics of interest and receive the messages published to the topic.
 

Subscribers and Publishers

A JMS client that is configured to send messages to a queue or topic is known as a publisher. A JMS client that is configured to receive messages published to a particular queue or topic is known as a subscriber.

Role-based permissions

The possibility to work with queues and topics in WSO2 MB is strictly secured by role-based permissions. That is, users created in WSO2 MB should be granted the required permissions in order to publish messages to queues/topics and to consume the messages that are published. External clients will then be able to use the credentials of these authorized users in order to send messages and consume messages.

Metrics monitoring

You can effectively monitor the performance and statistics of your WSO2 MB server using Java Metrics.

Management Console

The management console of WSO2 MB is the user interface of the product, which can be used to conveniently create topics and queues and to manage subscriptions. External clients can then connect to WSO2 MB for publishing messages and consuming already published messages.

Before you begin

Install WSO2 MB and Apache JMeter as explained below.

Download and start WSO2 MB

Follow the steps given below to download and start your product.

  1. Download WSO2 Message Broker from here.
  2. Extract the zip file to a location in your computer. This location will be referred to as <MB_HOME> from hereon.
  3. To start the product: Open a terminal and navigate to the <MB_HOME>/bin directory where all the startup scripts are stored and run the startup script:
    • On Windows: wso2server.bat
    • On Linux: sh wso2server.sh

  4. The URL of the management console will be printed in the terminal as follows:

    INFO {org.wso2.carbon.ui.internal.CarbonUIServiceComponent} -  Mgt Console URL  : https://10.100.5.65:9443/carbon/

  5. Copy this URL to your browser to open the management console. Note the IP address used in the URL, which is '10.100.5.65' in the above scenario. You will need this IP address later when you connect to the MB node from an external client. Therefore, lets change it to localhost to make this quick start process simpler.

    INFO {org.wso2.carbon.ui.internal.CarbonUIServiceComponent} -  Mgt Console URL  : https://localhost:9443/carbon/

Download and start Apache JMeter

In this quick start guide, we will be using Apache JMeter for the purpose of simulating how a JMS client sends messages to WSO2 MB and how such a client subscribes to topics and queues in WSO2 MB. 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 <MB_HOME>/client-lib directory to the <JMeter_Home>/lib folder:
    • andes-client-3.1.1.jar
    • geronimo-jms_1.1_spec-1.1.0.wso2v1.jar
    • org.wso2.carbon.logging-4.4.1.jar
    • org.wso2.securevault-1.0.0-wso2v2.jar
  3. Start the JMeter by executing the following script from the <JMeter_Home>/bin folder: 
    • On windows: jmeter.bat
    • On Linux: sh jmeter.sh
    The JMeter UI will open.

Working with queues

In the following steps, we will go through the basics of creating a queue in WSO2 MB and setting up a JMS client as a subscriber and publisher.

Step 1: Creating queues

We will now create a queue in WSO2 MB, using the product's management console. Follow the instructions given below. 

  1. Log in to the management console using the credentials of the default system administrator: admin/admin.
    You will now be logging into the super tenant domain. 
  2. In the Main tab, click Queues -> Add. The Add Queue screen will open.
  3. Enter 'MyFirstQueue' as the name in the Queue Name field as shown below.
  4. Click Add Queue and the new queue will be listed in the Queue List page as shown below.
    You can access the Queue List page by clicking Queues -> List in the Main tab of the navigator.

Step 2: Publishing messages to the queue

We will now set up Apache JMeter as a JMS publisher to the queue we created in the previous step. Follow the instructions given below.

  1. Create the following jndiqueues.properties file and save it to a location in your system. The details in this file will establish the connection between your JMS publisher and the MB node you installed.

    # register some connection factories
# connectionfactory.[jndiname] = [ConnectionURL]
connectionfactory.QueueConnectionFactory = amqp://admin:admin@clientID/carbon?brokerlist='tcp://localhost:5672'

# register some queues in JNDI using the form
# queue.[jndiName] = [physicalName]
queue.MyFirstQueue = MyFirstQueue

    Note that we are using localhost as the IP address, which is the same IP we used for starting the management console of WSO2 MB.

  2. Go to the JMeter UI and create a JMS publisher as explained below.
    1. Create a new test plan in JMeter: Right-click on 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 as a test plan.
    3. Right-click on the new test plan and go to Add -> Sampler -> JMS Publisher.
    4. Name the publisher as 'JMS Queue Publisher'.
    5. You will now have a JMS Publisher node in the left navigator. Select this node and enter the following details:
      1. In the Initial Context Factory field, enter org.wso2.andes.jndi.PropertiesFileInitialContextFactory.
      2. The connection details you specified in the jndiqueues.properties file should be entered for the JMS Publisher as shown below.
        • Provider URL: This should be the location where you have the jndiqueues.properties file saved.
        • Connection Factory: This should be set to QueueConnectionFactory.
        • Destination: MyFirstQueue.
      1. Enter the values in the Expiration and Priority fields to zero (0).
    6. Enter the message that you want to publish to the queue in the relevant field.

    7. Save the information. You now have a JMS client ready to send messages to the 'MyFirstQueue' queue in your MB server.

       Click here to view these details in JMeter

  3. Execute the JMeter publisher.
  4. Go back to the management console of WSO2 MB and go to the Queue List page from the navigator. See that that the MyFirstQueue queue has received one message.
  5. Click Browse to view details of the message that has been published:

Step 3: Subscribing to queues

We will now set up Apache JMeter as a JMS subscriber for the queue we created in the previous step. Follow the instructions given below.

  1. Go to the JMeter UI and create a JMS subscriber as explained below.
    1. Create a new test plan: Right-click on 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 as a test plan.
    3. Right-click on the new test plan and go to Add -> Sampler -> JMS Subscriber.
    4. Name the subscriber 'JMS Queue Subscriber'.
    5. You will now have a JMS Queue Subscriber node in the left navigator. Select this node and enter the following details:
      1. In the Initial Context Factory field, enter org.wso2.andes.jndi.PropertiesFileInitialContextFactory.
      2. The connection details you specified in the jndiqueues.properties file should be entered for the JMS Subscriber as shown below.
        • Provider URL: This should be the location where you have the jndiqueues.properties file saved.
        • Connection Factory: This should be set to QueueConnectionFactory.
        • Destination: MyFirstQueue.
    6. Right-click on the new test plan and go to Add -> Listener -> View Results in Tree. This will create a listener node in the the JMeter navigator for analysing the output of the subscription.
    7. Save the information. You now have a JMS client subscribed to the 'MyFirstQueue' queue in your MB server.

  2. Execute the JMeter script. This will create a subscription to the MyFirstQueue queue in your MB server, and the message that was already published to that queue will be immediately consumed.

  3. Select the View Results in Tree node in the JMeter navigator and go to the Response data tab. You can now see that the message from the MyFirstQueue queue has been received by the subscriber.

  4. Go back to the management console of WSO2 MB and view the Queue List. See that the number of messages published to the MyFirstQueue has reverted to zero. 

Managing unconsumed subscriptions

In the above example, we saw that the subscriber immediately consumes the message that is published to WSO2 MB. The following illustrates how subscriptions can be managed if a published message is not available to be consumed.

  1. Lets us create another subscription to the same queue (MyFirstQueue) in WSO2 MB by simply repeating step 3 given above. 
  2. Go to the management console of WSO2 MB and go to Subscriptions -> Queue Subscription List in the Main tab. See that the subscription is listed as shown below.
    The Queue Subscription List page shows all the subscriptions that are waiting for published messages.

Working with topics

In the following steps, we will go through the basics of creating topics in WSO2 MB 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

We will now create the topics and sub topics, so that you have 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 in MB: 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 as shown below.
    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. You will now have the following topic structure:
  8. Repeat the steps to add the remaining subtopics until you get the complete topics hierarchy.

Step 2: Subscribing to topics

We will now set up Apache JMeter as a JMS subscriber for the topics we created in the previous step. Follow the instructions given below.

  1. 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 JMS subscriber and the MB node.

    # register some connection factories
# connectionfactory.[jndiname] = [ConnectionURL]
connectionfactory.TopicConnectionFactory = amqp://admin:admin@clientID/carbon?brokerlist='tcp://localhost:5672'

# register some topics in JNDI using the form
# topic.[jndiName] = [physicalName]
topic.Games = Games

    Note that we are using localhost as the IP address, which is the same IP we used for starting the management console of WSO2 MB.

  2. 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
  3.  Go to the JMeter UI and create a JMS subscriber as explained below.
    1. Create a new test plan: 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 as a test plan.
    3. Right-click on the new test plan 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:
      1. In the Initial Context Factory field, enter org.wso2.andes.jndi.PropertiesFileInitialContextFactory.
      2. The connection details you specified in the jnditopics.properties file should be entered for the JMS Subscriber as shown below.
        • Provider URL: This should be the location where you have the jndi.properties file saved.
        • Connection Factory: This should be set to TopicConnectionFactory.
        • Destination: Games
    6. 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.

    7. Save the information. You now have a JMS client subscribed to the 'Games' topic or any of its child topics (Football, Germany or Brazil).

       Click here to view these details in JMeter

  4. Execute the JMeter script.
    Now, go to the management console of WSO2 MB and go to Main -> Subscriptions -> Topic Subscription List. Your subscription will be listed as a temporary topic subscription:

  5. In the next section, let's look at how this subscription will be served when a message is published to the 'Games' topic.

Step 3: Publishing messages to topics

We will now set up Apache JMeter as a JMS publisher to the 'Games' topic that we created in the previous step. 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 test plan 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 as a test plan.
  4. Right-click on the new test plan and go to Add -> Sampler -> JMS Publisher.
  5. Name this publisher Games Publisher. We will be using this publisher to publish messages relevant to the 'Games' topic.
  6. You will now have a Games Publisher node in the left navigator. Select this node and enter the following details:
    1. In the Initial Context Factory field, enter org.wso2.andes.jndi.PropertiesFileInitialContextFactory.
    2. 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: Games
      • Enter the values in the Expiration and Priority fields to zero (0).
    3. Enter the message that you want to publish to the topic in the relevant field.
  7. Save the information. You now have a JMS client ready to send messages.
  8. Execute the JMeter publisher.
  9. Go back to the management console of WSO2 MB and go to Subscriptions -> Topic Subscription List in the Main tab. See that the temporary topic subscription is now removed, because the subscription has now been served by a message.

Monitoring statistics

WSO2 MB consists of many capabilities that can be used for monitoring and analysis. Follow the steps given below for a quick demonstration on how to analyse the statistics corresponding to the work you did with your MB server in the previous sections of this quick start guide.

  1. In the management console of WSO2 MB, go to the Monitor tab. The following monitoring options will be available to you:

  2. For the purpose of this demonstration, let's use Java Metrics for monitoring: Click Messaging Metrics to open the View Metrics screen.

    Note that all of the options for viewing statistics are selected in the metric dashboard.

  3. Shown below are some of these statistics.   

    • The following graph shows how the number of queue subscriptions and topic subscriptions have varied during the time that you worked with you MB server.

       Publish and subscribe

    • The following graph displays how the number of messages received by the MB server and the number of acknowledgments from subscriber clients have varied with time.

       Received messages and acknowledgements

    • The following graph shows how much time the MB server has taken to read data from the database.

       Database read time

    • The following graph shows the rate (reads per second) at which the MB server reads data from the database.

       Database read rate

    • The following graph shows how much time the MB server has taken to write data to the database.

       Database write time

    • The following graph shows the rate (writes per second) at which the MB server writes data to the database.

       Database write rate

Shown above are only some of the monitoring capabilities available in WSO2 MB. See the documentation on monitoring and statistics for more information on how to use the other capabilities.

This concludes the quick start guide for WSO2 Message Broker. Go to the user guide for more information on functionalities in WSO2 MB and advanced use cases.