Versions Compared

Old Version 1

changes.mady.by.user Former user

Saved on

compared with

New Version 2

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Before you begin

Install WSO2 MB and Apache JMeter download JMS clients as explained below.

Download and start WSO2 MB

Follow the steps given below to download and start your producta WSO2 MB instance.

  1. Download WSO2 Message Broker from here.
  2. Extract the zip ZIP file to a location in on 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:

    Code Block
    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.

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

    Image Removed

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

    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.
    Image Removed

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.

...

Download sample JMS clients
WSO2 Message Broker is used for brokering messages between JMS clients. We will use the following sample JMS clients in this quick start guide to see how this process works.
  1. Click this link to download the QuickStartClients.zip file, which contains the following sample clients.
    • JMS queue publisher
    • JMS queue subscriber
    • JMS topic publisher
    • JMS topic subscriber
    • JMS durable topic subscriber
  2. Extract this file to a location on your computer. We will call this <JMS_CLIENTS_HOME> from hereon.
You will need Apache Ant to execute the above JMS clients. Download Apache Ant using homebrew.
...
Working with Queues
Let's try out a simple scenario of brokering messages using a queue in WSO2 MB.
Step 1: Create a queue in WSO2 MB
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 'MyFirstQueuetestQueue' as the name in the Queue Name field as shown below.
    Image RemovedImage Added
  4. Click Add Queue and the new queue will be listed in the Queue List page as shown below.
    Image Added
    Image RemovedYou can access the Queue List page by clicking Queues -> List in the Main tab of the navigator.
Step 2: 
...
Publish 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.
     Code Block
    # 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
    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.
       Expand
      titleClick here to view these details in JMeter
      Image Removed
  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.
    Image Removed
  5. Click Browse to view details of the message that has been published:
    Image Removed
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.
    Image Removed
  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.
    Image RemovedThe 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:
Image Removed
To add the topics and sub topics:
...
You can use the queue publisher JMS client to publish messages to this queue. Follow the steps given below.
  1. Open a command prompt and navigate to the <JMS_CLIENTS_HOME> directory on your computer.
  2. Execute the following command, which will publish 10 messages to the queue:
     Code Block
    ant queuePublisher
  3. Go to the management console.
  4. In the Main tab, click TopicsQueues -> Add. The Add Topic screen will open.
  5. Enter 'Games' as the topic name in the Topic field.
    Image Removed
  6. Click Add Topic and the new topic will be listed in the Topic List page as shown below.
    Image RemovedYou can access the Topic List page by clicking Topic -> List in the Main tab of the navigator.
  7. Click Games in the topic list. This will open the following options:
    Image Removed
  8. Click Add Subtopic to open the Add Sub Topic screen. 
  9. Enter 'Football' as the subtopic name and click Add Topic. You will now have the following topic structure:
    Image Removed
  10. 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.
     Code Block
    # 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
    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).
       Expand
      titleClick here to view these details in JMeter
      Image Removed
  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:
    Image Removed
  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.
    Image Removed
  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:
    Image Removed
  2. For the purpose of this demonstration, let's use Java Metrics for monitoring: Click Messaging Metrics to open the View Metrics screen.
     Note
    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.
       Expand
      titlePublish and subscribe
      Image Removed
    • The following graph displays how the number of messages received by the MB server and the number of acknowledgements from subscriber clients have varied with time.
       Expand
      titleReceived messages and acknowledgements
      Image Removed
    • The following graph shows how much time the MB server has taken to read data from the database.
       Expand
      titleDatabase read time
      Image Removed
    • The following graph shows the rate (reads per second) at which the MB server reads data from the database.
       Expand
      titleDatabase read rate
      Image Removed
    • The following graph shows how much time the MB server has taken to write data to the database.
       Expand
      titleDatabase write time
      Image Removed
    • The following graph shows the rate (writes per second) at which the MB server writes data to the database.
       Expand
      titleDatabase write rate
      Image Removed
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.
...
  1. . You can see that 10 messages have been published to the queue as shown below.
    Image Added
  2. Click Browse to see details of the messages received.
Step 3: Subscribe to the queue and consume messages
The queue subscriber JMS client will be used for this purpose. Follow the steps given below.
  1. Open a command prompt and navigate to the location of your JMS clients.
  2. Execute the following command, which will subscribe to the queue and consume the available messages.
     Code Block
    ant queueSubscriber
  3. Go to the management console. 
  4. In the Main tab, click Queues -> List. You can see that the 10 messages that were stored in the queue have been successfully consumed by the subscriber.
  5. You can verify this from the terminal log.
    Image Added