This documentation is for WSO2 Enterprise Service Bus version 4.9.0 . View documentation for the latest release.

All docs This doc
||
Skip to end of metadata
Go to start of metadata

A message store temporarily stores messages before they are delivered to their destination by a message processor. WSO2 ESB ships with the following message store implementations:

For more information, see Message Stores.

This section describes how to configure JMS Message stores for different message brokers. Following is a generic JMS message store configuration:

<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 parameters. For some brokers you may have to specify additional parameters. See the following table for the list of configurable parameters:

Parameter NameValueRequired
java.naming.factory.initial Initial Context Factory used to connect to the JMS broker.YES
java.naming.provider.urlUrl of the naming provider to be used by the context factory.YES
store.jms.destinationJNDI 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.factoryJNDI name of the Connection factory, which is used to create jms connections.NO but for some JMS clients this will be needed
store.jms.usernameUser Name that is used to create the connection with the broker.NO
store.jms.passwordPassword that is used to create the connection with the broker.NO
store.jms.JMSSpecVersion1.1 or 1.0 JMS API specification to be used (Default 1.1)NO
store.jms.cache.connectiontrue/false Enable Connection cachingNO

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 in a JMS message store.
  • The message forwarding processor invokes the back-end service, and picks the messages stored in the JMS message store.


Now let's configure the sample scenario.

Configure the broker server

  1. To get started set up a broker server. If you want to use WSO2 Message Broker, see Configure with WSO2 Message Broker. If you want to use ActiveMQ, see Configure with ActiveMQ

    Note

    If you are using ActiveMQ 5.12.2 and above, you need to set the following system property on server start up for WSO2 ESB's JMS message store to work as expected.

    -Dorg.apache.activemq.SERIALIZABLE_PACKAGES=“*"

    With ActiveMQ 5.12.2 and above, you need to set the above property because users are enforced to explicitly whitelist packages that can be exchanged using ObjectMessages, and due to this restriction the message processor fails to read messages from ActiveMQ with the following error:

    ERROR - JmsConsumer [JMS-C-1] cannot receive message from store. Error:Failed to build body from content. Serializable class not available to broker. Reason: java.lang.ClassNotFoundException: Forbidden class org.apache.synapse.message.store.impl.commons.StorableMessage! This class is not trusted to be serialized as ObjectMessage payload.

    Note

    You only need to set up the broker server. You do not need to configure the listeners and senders in the ESB configuration (i.e., you need to follow 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 that you set up in step 1. To create proxy services, sequences, endpoints, message stores, and processors in the ESB, you can either use the management console or copy the XML configuration to the source view. You can find the source view under Manage > Service Bus > Source View on the left navigation pane of the WSO2 ESB management console. Alternatively, you can add an XML file with the required configuration to the <ESB_HOME>/repository/deployment/server/synapse-configs/default/message-stores directory.
  • 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>
  • 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>

Configure the back-end service

  1. 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. For more information on sample back-end services, see  Deploying sample back-end services.
  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. Go 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.

Configure the ESB

  1. Define an endpoint, which can be 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 that stores messages in the message store you created.

    <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

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

  3. Use the following configuration to create a message forwarding processor to consume 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, you can execute the sample.  

Execute the Sample

You can use the sample axis2 client that is shipped with the ESB to invoke the proxy service.

  • Navigate to the <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

    You will see a message similar to the following printed on 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 configure this sample scenario. 

Configure the broker server

  1. To get started set up a broker server. If you want to use WSO2 Message Broker, see Configure with WSO2 Message Broker. If you want to use ActiveMQ, see Configure with ActiveMQ

    Note

    If you are using ActiveMQ 5.12.2 and above, you need to set the following system property on server start up for WSO2 ESB's JMS message store to work as expected.

    -Dorg.apache.activemq.SERIALIZABLE_PACKAGES=“*"

    With ActiveMQ 5.12.2 and above, you need to set the above property because users are enforced to explicitly whitelist packages that can be exchanged using ObjectMessages, and due to this restriction the message processor fails to read messages from ActiveMQ with the following error:

    ERROR - JmsConsumer [JMS-C-1] cannot receive message from store. Error:Failed to build body from content. Serializable class not available to broker. Reason: java.lang.ClassNotFoundException: Forbidden class org.apache.synapse.message.store.impl.commons.StorableMessage! This class is not trusted to be serialized as ObjectMessage payload.

    Note

    You only need to set up the broker server. You do not need to configure the listeners and senders in the ESB configuration (i.e., you need to follow 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 that you set up in step 1. To create proxy services, sequences, endpoints, message stores, and processors in the ESB, you can either use the management console or copy the XML configuration to the source view. You can find the source view under Manage > Service Bus > Source View on the left navigation pane of the WSO2 ESB management console. Alternatively, you can add an XML file with the required configuration to the <ESB_HOME>/repository/deployment/server/synapse-configs/default/message-stores directory. 
  • 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>
  • 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>

Configure the back-end service

  1. 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. For more information on sample back-end services, see  Deploying sample back-end services.
  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. Go 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.

Configure the ESB

  1. Define an endpoint that can be 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 that stores messages in the message store you created.

    <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 you receive from the back-end service.

    <sequence name="replySequence">
      <log level="full">
         <property name="REPLY" value="MESSAGE" />
      </log>
      <drop/>
    </sequence>
  4. Use the following configuration to create a message forwarding processor that consumes the messages stored in the message store. When compared to the message processor in use case scenario 1 , this has an additional parameter message.processor.reply.sequence that points 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, you can execute the sample.    

Execute the Sample

You can use the sample axis2 client that is shipped with the ESB to invoke the proxy service.

  • Navigate to the  <ESB_HOME>/repository/samples/axis2client/ directory, and execute the following command to invoke the proxy service:

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

    You will see how the service is invoked and you will also see a response similar to the following logged by the replySequence:

    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:volumehttps://docs.wso2.com/pages/editpage.action#>
     </ns:return></ns:getsimplequoteresponse></soapenv:body></soapenv:envelope>
  • No labels