Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.
This documentation is for WSO2 Message Broker version 3.2.0. For the latest documentation, see the documentation for WSO2 Enterprise Integrator.
Skip to end of metadata
Go to start of metadata

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 queues and topics on WSO2 MB and then see how JMS clients can send messages to these queues/topics and receive messages from them.

Key concepts

Explained below are some of the key concepts in message brokering.


Queues in WSO2 MB are essentially message stores that 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 in WSO2 MB are used for realtime message brokering. You can maintain a hierarchy of topics or subjects in WSO2 MB for which JMS clients (subscribers) can subscribe. Other JMS clients (publishers) can then publish messages to these topics, which will immediately be consumed by the subscribers.

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.

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 download JMS clients as explained below.

Download and start WSO2 MB

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

  1. Download WSO2 Message Broker from here.
  2. Extract the ZIP file to a location on your computer. This location will be referred to as <MB_HOME> from hereon.
  3. To start the product: Open a terminal, 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  :

Download sample JMS clients

We will use sample JMS clients in this quick start guide to simulate how messages are published to WSO2 MB and how the published messages are consumed. First, you need to download and set up these clients as follows:

  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 'testQueue' 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: Publish messages to the queue

You can now use the sample JMS Queue Publisher 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 named 'testQueue':

    ant queuePublisher
  3. Go to the management console.
  4. In the Main tab, click Queues -> List. You can see that 10 messages have been published to the queue as shown below.
  5. Click Browse to see details of the messages received.

Step 3: Subscribe to the queue and consume messages

Now, you need a JMS client to subscribe to the 'testQueue' queue and consume the messages. The sample JMS Queue Subscriber JMS client will be used for this purpose. 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, to create a subscription to the 'testQueue' queue.

    ant queueSubscriber
  3. The 10 messages in the queue have been successfully consumed by the subscriber. You can verify this from the terminal log:
  4. Go to the management console and click Queues -> List in the Main tab. You can see that the 10 messages that were stored in the queue are no longer there.
  • No labels