Store and Forward Using JMS Message Stores

A message store is a storage in WSO2 Enterprise Integrator (WSO2 EI) for messages. WSO2 EI comes with two types of message store implementations such as In Memory Message Store and JMS Message Store . Users also have the option to create a Custom Message Store with their own message store implementation. For more information, refer to section Message Stores.

This section specifically describes how to configure JMS Message stores for different message brokers. Given below is the generic configuration for a JMS message store.

<messageStore xmlns="http://ws.apache.org/ns/synapse"
             class="org.apache.synapse.message.store.impl.jms.JmsStore"
             name="JMSMS">   
  <parameter name="java.naming.factory.initial">INITIAL_CONTEXT_FACTORY_NAME_HERE</parameter>
  <parameter name="java.naming.provider.url">URL_OF_THE_NAMING_PROVIDER</parameter>
</messageStore>

The configuration above only includes the mandatory elements. But, for some brokers you may have to specify extra parameters. Following table shows the list of configurable parameters.

Parameter Name	Value	Required
java.naming.factory.initial	Initial Context Factory used to connect to the JMS broker.	YES
java.naming.provider.url	Url of the naming provider to be used by the context factory.	YES
store.jms.destination	JNDI Name of the Queue Name that the message store is connecting to.	NO but for some JMS clients this will be needed
store.jms.connection.factory	JNDI name of the Connection factory, which is used to create jms connections.	NO but for some JMS clients this will be needed
store.jms.username	User Name that is used to create the connection with the broker.	NO
store.jms.password	Password that is used to create the connection with the broker.	NO
store.jms.JMSSpecVersion	1.1 or 1.0 JMS API specification to be used (Default 1.1)	NO
store.jms.cache.connection	true/false Enable Connection caching	NO

Next, let's see a few real-life business use cases of JMS message stores.

Use Case Scenario 1

In this sample:

The client sends requests to a proxy service.
The proxy service stores the messages to a JMS message store.
The back-end service is invoked by a message forwarding processor, which picks stored messages in the JMS message store.

Let's proceed to configuring this sample scenario.

Configure the Broker Server

1. Refer to Configuring with the Broker Profile or Configure with ActiveMQ for details on setting up a broker server for this sample. Note that you only need to set up the broker server itself and do not need to configure the listeners and senders in WSO2 EI configuration (i.e., just perform steps 1 through 4 in the Message Broker instructions or 1 through 3 in the ActiveMQ instructions).

2. Create a JMS message store for the broker set up in step 1. To create proxy services, sequences, endpoints, message stores, processors etc. in WSO2 EI, you can either use the management console or copy the XML configuration to the source view. You can find the source view under menu Manage > Service Bus > Source View in the left navigation pane of the WSO2 EI management console. Alternatively, you can add an XML file to <EI_HOME>/repository/deployment/server/synapse-configs/default/message-stores.

For example,

If you use ActiveMQ, the sample message store configuration is as follows:

Set the value of the the < java.naming.provider.url> property to point to the provider URL.

<messageStore xmlns="http://ws.apache.org/ns/synapse"
             class="org.apache.synapse.message.store.impl.jms.JmsStore"
             name="JMSMS">
  <parameter name="java.naming.factory.initial">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
  <parameter name="java.naming.provider.url">tcp://localhost:61616</parameter>
</messageStore>

If you use the Brokering profile of WSO2 EI as the broker server, the sample message store configuration is as follows:

Set the value of the the < java.naming.provider.url> property to point to the jndi.properties file. In this case, <store.jms.destination> is a mandatory parameter. If you are using the Broker profile of WSO2 EI, you need to create a queue named 'JMSMS' using the Broker profile (i.e., the value you specify for the store.jms.destination parameter). For instructions on creating the queue, see Managing Queues.
```
<messageStore name="JMSMS" class="org.apache.synapse.message.store.impl.jms.JmsStore" xmlns="http://ws.apache.org/ns/synapse">   
  <parameter name="java.naming.factory.initial">org.wso2.andes.jndi.PropertiesFileInitialContextFactory</parameter>   
  <parameter name="java.naming.provider.url">repository/conf/jndi.properties</parameter>
  <parameter name="store.jms.destination">JMSMS</parameter>
</messageStore>
```

Configuring Back-end Service

1. Set up the prerequisites given in the Prerequisites section in Setting Up the Service Bus Samples. Then, deploy the SimpleStockQuoteService client by navigating to < ESB_HOME>/samples/axis2Server/src/SimpleStockQuoteService, and running the ant command in the command prompt or shell script. This will build the sample and deploy the service for you.

2. WSO2 ESB comes with a default Axis2 server, which you can use as the back-end service for this sample. To start the Axis2 server, navigate to <ESB_HOME>/samples/axis2server and run axis2Server.sh (on Linux) or axis2Server.bat (on Windows).

3. Point your browser to http://localhost:9000/services/SimpleStockQuoteService?wsdl and verify that the service is running.

You now have a JMS message store configured in the ESB. Next, configure the ESB for the specific message broker you use.

Configuring the ESB

1. Define an endpoint which is used to send the message to the back-end service.

<endpoint name="SimpleStockQuoteService">
  <address uri="http://127.0.0.1:9000/services/SimpleStockQuoteService"/>
</endpoint>

2. Create a proxy service which stores messages to the created Message Store.

<proxy name="Proxy1" transports="https http" startOnLoad="true" trace="disable">   
  <target>
     <inSequence>
        <property name="FORCE_SC_ACCEPTED" value="true" scope="axis2"/>
        <property name="OUT_ONLY" value="true"/>
        <log level="full"/>
        <store messageStore="JMSMS"/>
     </inSequence>
  </target>
</proxy>

Note the following in the configuration:

We use the property FORCE_SC_ACCEPTED in the message flow to send an Http 202 status to the client after ESB accepts a message. If this property is not specified, the the client which sends the request to the proxy service will timeout since it is not getting any response back from the proxy.

3. Create a message forwarding processor using the below configuration. Message forwarding processor consumes the messages stored in the message store.

<messageProcessor class="org.apache.synapse.message.processor.impl.forwarder.ScheduledMessageForwardingProcessor" name="Processor1" targetEndpoint="SimpleStockQuoteService" messageStore="JMSMS">
   <parameter name="max.delivery.attempts">4</parameter>
   <parameter name="interval">4000</parameter>
   <parameter name="is.active">true</parameter>
</messageProcessor>

Once the back-end service and the ESB are configured, proceed to invoking the sample as follows.

Executing the Sample

1. To invoke the proxy service, we use the sample axis2 client shipped with the ESB. Navigate to <ESB_HOME>/repository/samples/axis2client/ directory, and execute the following command to invoke the proxy service.

ant stockquote -Daddurl=http://localhost:8280/services/Proxy1 -Dmode=placeorder

2. Note a message similar to the following example printed in the Axis2 Server console.

SimpleStockQuoteService :: Accepted order for : 7482 stocks of IBM at $ 169.27205579038733

Use Case Scenario 2

In the sample, when the message forwarding processor receives a response from the back-end service, it forwards it to a replySequence to process the response message.

Let's proceed to configuring this sample scenario.

Configure the Broker Server

1. Refer to Configuring with the Broker Profile or Configure with ActiveMQ for details on setting up a broker server for this sample. Note that you only need to set up the broker server itself and do not need to configure the listeners and senders in the ESB configuration (i.e., just perform steps 1 through 4 in the Message Broker instructions or 1 through 3 in the ActiveMQ instructions).

2. Create a JMS message store for the broker set up in step 1. To create proxy services, sequences, endpoints, message stores, processors etc. in ESB, you can either use the management console or copy the XML configuration to the source view. You can find the source view under menu Manage > Service Bus > Source View in the left navigation pane of the WSO2 ESB management console. Alternatively, you can add an XML file to <ESB_HOME>/repository/deployment/server/synapse-configs/default/message-stores.

For example,

If you use ActiveMQ, the sample message store configuration is as follows:

Set the value of the the < java.naming.provider.url> property to point to the provider URL.

<messageStore xmlns="http://ws.apache.org/ns/synapse"
             class="org.apache.synapse.message.store.impl.jms.JmsStore"
             name="JMSMS">
  <parameter name="java.naming.factory.initial">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
  <parameter name="java.naming.provider.url">tcp://localhost:61616</parameter>
</messageStore>

If you use WSO2 Message Broker as the broker server, the sample message store configuration is as follows:

Set the value of the the < java.naming.provider.url> property to point to the jndi.properties file. In this case, <store.jms.destination> is a mandatory parameter.

<messageStore name="JMSMS" class="org.apache.synapse.message.store.impl.jms.JmsStore" xmlns="http://ws.apache.org/ns/synapse">   
  <parameter name="java.naming.factory.initial">org.wso2.andes.jndi.PropertiesFileInitialContextFactory</parameter>   
  <parameter name="java.naming.provider.url">repository/conf/jndi.properties</parameter>
  <parameter name="store.jms.destination">JMSMS</parameter>
</messageStore>

Configuring Back-end Service

1. Set up the prerequisites given in the Prerequisites section in Setting Up the Service Bus Samples. Then, deploy the SimpleStockQuoteService client by navigating to < ESB_HOME>/samples/axis2Server/src/SimpleStockQuoteService, and running the ant command in the command prompt or shell script. This will build the sample and deploy the service for you.

2. WSO2 ESB comes with a default Axis2 server, which you can use as the back-end service for this sample. To start the Axis2 server, navigate to <ESB_HOME>/samples/axis2server and run axis2Server.sh (on Linux) or axis2Server.bat (on Windows).

3. Point your browser to http://localhost:9000/services/SimpleStockQuoteService?wsdl and verify that the service is running.

You now have a JMS message store configured in the ESB. Next, configure the ESB for the specific message broker you use.

Configuring the ESB

1. Define an endpoint, which is used to send the message to the back-end service.

<endpoint name="SimpleStockQuoteService">
   <address uri="http://127.0.0.1:9000/services/SimpleStockQuoteService"/>
</endpoint>

2. Create a proxy service which stores messages to the created Message Store.

<proxy name="Proxy2" transports="https,http"
       statistics="disable" trace="disable" startOnLoad="true">
   <target>
      <inSequence>
         <property name="FORCE_SC_ACCEPTED" value="true" scope="axis2" />
         <log level="full" />
         <store messageStore="JMSMS" />
      </inSequence>
   </target>
</proxy>

3. Create a sequence to handle the response received from the back-end service.

<sequence name="replySequence">
  <log level="full">
     <property name="REPLY" value="MESSAGE" />
  </log>
  <drop/>
</sequence>

4. Create a message forwarding processor using the below configuration. Message forwarding processor consumes the messages stored in the message store. Compared to the message processor in sample 1 , this has an additional parameter message.processor.reply.sequence to point to a sequence to handle the response message.

<messageProcessor name="Processor2" class="org.apache.synapse.message.processor.impl.forwarder.ScheduledMessageForwardingProcessor" targetEndpoint="SimpleStockQuoteService" messageStore="JMSMS" xmlns="http://ws.apache.org/ns/synapse">
   <parameter name="interval">1000</parameter>
   <parameter name="client.retry.interval">1000</parameter>
   <parameter name="max.delivery.attempts">4</parameter>
   <parameter name="message.processor.reply.sequence">replySequence</parameter>
   <parameter name="is.active">true</parameter>
   <parameter name="max.delivery.drop">Disabled</parameter>
   <parameter name="member.count">1</parameter>
</messageProcessor>

Once the back-end service and the ESB are configured, proceed to invoking the sample as follows.

Executing the Sample

1. To invoke the proxy service, we use the sample axis2 client shipped with the ESB. Navigate to <ESB_HOME>/repository/samples/axis2client/ directory, and execute the following command to invoke the proxy service.

ant stockquote -Daddurl=http://localhost:8280/services/Proxy2

2. Note the service being invoked and then the response being logged from the replySequence. For example,

INFO - LogMediator To: /services/InOutProxy, WSAction: urn:getSimpleQuote, SOAPAction: urn:getSimpleQuote,
 MessageID: urn:uuid:dec12d9c-5289-476c-9d9a-b7bb7ebc7be4, Direction: request, REPLY = MESSAGE,
 Envelope:
 <?xml version='1.0' encoding='utf-8'?>
 <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
 <soapenv:body><ns:getsimplequoteresponse xmlns:ns="http://services.samples">
 <ns:return xmlns:ax21="http://services.samples/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax21:GetQuoteResponse">
 <ax21:change>-2.3141856129298564</ax21:change><ax21:earnings>12.877155014054368</ax21:earnings>
 <ax21:high>172.73334579339183</ax21:high><ax21:last>165.31090559096748</ax21:last>
 <ax21:lasttradetimestamp>Thu Dec 29 07:48:42 IST 2011</ax21:lasttradetimestamp>
 <ax21:low>-164.80767926468306</ax21:low><ax21:marketcap>9451314.231029626</ax21:marketcap>
 <ax21:name>IBM Company</ax21:name><ax21:open>-161.41234152690964</ax21:open>
 
<ax21:peratio>25.74977555860659</ax21:peratio><ax21:percentagechange>-1.2214036358135663</ax21:percentagechange>

<ax21:prevclose>189.46935681818218</ax21:prevclose><ax21:symbol>IBM</ax21:symbol><ax21:volume>8611</ax21:volume>
 </ns:return></ns:getsimplequoteresponse></soapenv:body></soapenv:envelope>