Point-to-Point Messaging

This tutorial will get you started with Point-to-Point messaging using Queues in the Message Broker profile (MB profile) of WSO2 Enterprise Integrator (WSO2 EI).

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.

Download WSO2 EI from here.
Extract the ZIP file to a location on your computer. This location will be referred to as <EI_HOME> from hereon.
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
The URL of the management console will be printed in the terminal as follows: https://localhost/carbon/

Download and start 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.

Download Apache JMeter from here and install it. The location of your JMeter folder will be referred to as <JMeter_HOME> from hereon.

This guide is tested with JMeter version 2.13.
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
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.

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

Step 1: Creating queues

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

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.
In the Main tab, click Queues -> Add. The Add Queue screen will open.
Enter 'myfirstqueue' as the name in the Queue Name field.
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.

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:5675'

# register some queues in JNDI using the form
# queue.[jndiName] = [physicalName]
queue.FirstQueue = myfirstqueue 
```
Note that we are using localhost as the IP address, which is the same IP we used for starting the management console of the MB profile.

Go to the JMeter UI and create a JMS publisher as explained below.

Create a new test plan in JMeter: Right-click on Test Plan (in the left navigator) and go to Add -> Threads (Users) -> Thread Group.
The new thread group will now be listed in the left navigator as a test plan.
Right-click on the new thread group and go to Add -> Sampler -> JMS Publisher.
Name the publisher as 'JMS Queue Publisher'.
You will now have a JMS Publisher node in the left navigator. Select this node and enter the following details:

Initial Context Factory org.wso2.andes.jndi.PropertiesFileInitialContextFactory

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

Provider URL	The location where you have the `jndiqueues.properties` file saved.
Connection Factory	`QueueConnectionFactory`
Destination	`FirstQueue` (i.e., the JNDI name given for the queue in the `jndiqueues.properties` file)
Expiration	0
Priority	0

Enter the message that you want to publish to the queue in the relevant field. For example, follow the below steps to send a text message:
- Select Text Message as the Message Type. field.
- Enter the following message in the Text Message or Object Message serialized to XML by XStream field: This is a test text message.
Save the information. You now have a JMS client ready to send messages to the 'myfirstqueue' queue in your MB server.

Execute the JMeter publisher.
Go back to the management console of the broker and go to the Queue List page from the navigator. See that the myfirstqueue queue has received one message.

You can access the Queue List page by clicking Queues -> List in the Main tab of the navigator.
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.

Go to the JMeter UI and create a JMS subscriber as explained below.

Create a new test plan: Right-click on Test Plan (in the left navigator) and go to Add -> Threads (Users) -> Thread Group.
The new thread group will now be listed in the left navigator as a test plan.
Right-click on the new test plan and go to Add -> Sampler -> JMS Subscriber.
Name the subscriber 'JMS Queue Subscriber'.
You will now have a JMS Queue Subscriber node in the left navigator. Select this node and enter the following details:

Initial Context Factory org.wso2.andes.jndi.PropertiesFileInitialContextFactory

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

Provider URL	The location where you have the `jndiqueues.properties` file saved.
Connection Factory	`QueueConnectionFactory`.
Destination	`FirstQueue` (i.e., the JNDI name given for the queue in the `jndiqueues.properties` file)

Right-click on the new thread group and go to Add -> Listener -> View Results Tree. This will create a listener node in the the JMeter navigator for analysing the output of the subscription.
Save the information. You now have a JMS client subscribed to the 'myfirstqueue' queue in your MB server.

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.
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.
Go back to the management console of the MB profile and view the Queue List. See that the number of messages published to the myfirstqueue has reverted to zero.

You can access the Queue List page by clicking Queues -> List in the Main tab of the navigator.

Step 4: Managing unconsumed subscriptions

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

Repeat Step 3: Subscribing to queues given above to create another subscription to the same queue (myfirstqueue) in the broker.
Go to the management console of the Message Broker and go to Subscriptions -> Queue Subscription List in the Main tab. The Queue Subscription List page shows all the subscriptions that are waiting for published messages.