2012/01/08
8 Jan, 2012

Configuring JMS Transport in WSO2 Business Process Server (BPS)

  • Thilini Ishaka
  • Associate Technical Lead - WSO2

Applies To

WSO2 BPS 2.1.* 
Active MQ 5.2.0
Apache Qpid 0.9

This article has been curated on 08th January 2012.

Contents

Introduction

A JMS application is composed with;

  • JMS provider : A messaging system that implements the JMS specification.
  • JMS client : A Java application that sends and receives messages.
  • Messages : Objects that are used to communicate information between JMS clients.
  • Administered Objects : Pre-configured JMS objects that are created by an administrator for the use of JMS clients.

This article describes how to enable JMS transport in WSO2 BPS and how to configure it to communicate with JMS providers such as: Active MQ, Apache Qpid.

Further it describes how to send/receive JMS requests/responses using a Java client and finally the SOAP over JMS messaging with WSO2 BPS.

Enable JMS Transport in WSO2 BPS

METHOD 1:

STEP 1: Uncomment  transport receiver section in axis2.xml inside BPS_HOME/repository/conf.

 
         
            org.apache.activemq.jndi.ActiveMQInitialContextFactory 
            tcp://localhost:61616 
            TopicConnectionFactory 
         
         
            org.apache.activemq.jndi.ActiveMQInitialContextFactory 
            tcp://localhost:61616 
            QueueConnectionFactory 
         
         
            org.apache.activemq.jndi.ActiveMQInitialContextFactory 
            tcp://localhost:61616 
            QueueConnectionFactory 
         

STEP 2: Uncomment transport sender section in axis2_client.xml inside BPS_HOME/repository/conf.


METHOD 2: WSO2 BPS provides a simple and easily configurable UI to enable transports. You can enable JMS transport using Transport Management fetaure available under Configure Menu in WSO2 BPS Management Console as shown in Figure 1.

  

 Figure 1

Now you have successfully enabled JMS transport in WSO2 Business Process Server.

Configure to Communicate WSO2 BPS with Active MQ

STEP1: Copy following ActiveMQ jar libraries to BPS_HOME/repository/components/lib directory.

  • activeio-core-3.1-SNAPSHOT.jar (ActiveMQ_HOME\lib\optional)
  • activemq-core-5.0.0.jar (ActiveMQ_HOME\lib\)
  • geronimo-j2ee-management_1.0_spec-1.0.jar (ActiveMQ_HOME\lib\)
  • geronimo-jms_1.1_spec-1.0.jar (ActiveMQ_HOME\lib\)

STEP 2: Start the ActiveMQ server.

  • sh activemq (in linux) or in activemq.bat (in windows)

STEP 3: Download, extract and copy 3 partner services (AdderService.aar, MultiplierService.aar and SquareService.aar) to BPS_HOME/repository/deployment/server/axis2services directory.

STEP4:. Start the WSO2 BPS.

  • sh  wso2server.sh (in linux) or wso2server.bat (in windows)

STEP 5: The Service Dashboard lists the JMS endpoint URL if the connection is successful. (see Figure 2)

 

Figure 2

STEP 6: Deploy the FunctionProcess BPEL process at the BPS server. You need to alter endpoint references of each wsdl inside the BPEL archive. The endpoint URIs are listed in the Service dashboard as well as in the console logs. Then create an instance using the "try-it" wizard as shown in Figure 3.

 

Figure 3  

Configure WSO2 BPS to Communicate with Apache Qpid

The WSO2 BPS is packaged with WSO2 Message Broker which is based on Apache Qpid. The WSO2 MB implements reliable and secure message queuing and publish-and-subscribe event distribution to enable message-driven and event-driven applications. Therefore, any JMS client or an AMQP client can directly talk to the WSO2 BPS. 

STEP 1: Add the following JNDI property configurations to jndi.properties file inside $WSO2_BPS_HOME/repository/conf

connectionfactory.TopicConnectionFactory = amqp://admin:admin@carbon/carbon?brokerlist='tcp://localhost:5672' 
connectionfactory.QueueConnectionFactory = amqp://admin:admin@carbon/carbon?brokerlist='tcp://localhost:5672' 
queue.MyQueue = example.MyQueue 
topic.MyTopic=example.MyTopic

Add the following configurations to axis2.xml file inside $WSO2_BPS_HOME/repository/conf in order to enable JMS transport with Qpid.  

          
           
             org.apache.qpid.jndi.PropertiesFileInitialContextFactory  
             repository/conf/jndi.properties  
             TopicConnectionFactory  
             topic  
           
           
             org.apache.qpid.jndi.PropertiesFileInitialContextFactory  
             repository/conf/jndi.properties  
             QueueConnectionFactory  
             queue  
           
     

Note: Carbon 3.2.* (BPS 2.1.*) is shipped with a single jar file called qpid-client-0.11.0.wso2v1.jar, which fulfills the functionalities of the follwing set of jar libraries.
If you are using an older version to Carbon 3.2.* (BPS 2.1.*), you need to manually copy the set of libraries below to BPS_HOME/lib/core/WEB-INF/lib directory.

  • slf4j-api-1.6.1.jar
  • slf4j-log4j12-1.6.1.jar
  • qpid-client-0.9.jar
  • qpid-common-0.9.jar
  • mina-core-1.0.1.jar

Now you have successfully configured WSO2 BPS to communicate with Apache Qpid. 

Java Client to Send/Receive JMS Requests/Responses with WSO2 BPS

 Step1: Start the ActiveMQ Server. 

  • $apache-activemq-5.2.0/bin$ ./activemq

 

Figure 4

STEP 2: Add the following configurations to axis2.xml file to enable JMS transport in WSO2 BPS. 

 
         
            org.apache.activemq.jndi.ActiveMQInitialContextFactory 
            tcp://localhost:61616 
            TopicConnectionFactory 
         

         
            org.apache.activemq.jndi.ActiveMQInitialContextFactory 
            tcp://localhost:61616 
            QueueConnectionFactory 
         

         
            org.apache.activemq.jndi.ActiveMQInitialContextFactory 
            tcp://localhost:61616 
            QueueConnectionFactory 
         

Enable transport configurations in axis2.xml file and axis2_client.xml file. As we are going to invoke the BPEL process using a client program, we need to enable transportSender configuration in axis2_client.xml file.


STEP 3: Copy following ActiveMQ jar libraries to BPS_HOME/repository/components/lib directory.

  • activeio-core-3.1.0.jar    (ActiveMQ_HOME\lib\optional)
  • activemq-core-5.0.0.jar   (ActiveMQ_HOME\lib\)
  • geronimo-j2ee-management_1.0_spec-1.0.jar   (ActiveMQ_HOME\lib\)
  • geronimo-jms_1.1_spec-1.0.jar   (ActiveMQ_HOME\lib\) 

STEP 4: Start the BPS Server.

$wso2bps_HOME/bin$ ./wso2server.sh 

STEP 5: Download, extract and copy 3 partner services (AdderService.aar, MultiplierService.aar and SquareService.aar) to BPS_HOME/repository/deployment/server/axis2services directory. Then deploy FunctionProcess BPEL process. Goto Service Dashboard and find that the FunctionProcessService is exposed over JMS as shown in Figure 5.

 

 Figure 5

Notice the endpoint URI: 

jms:/FunctionProcessServiceService?transport.jms.DestinationType=queue&transport.jms.ContentTypeProperty=Content-Type&java.naming.provider.url=tcp://localhost:61616&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory 

STEP6: Let's see how can we send a JMS request to the BPS Server and receive a response over JMS.

Generate the stub from the FunctionProcessServiceService.wsdl using wsdl2java tool and get the generated java code to a directory called "out". 

$AXIS2HOME/bin$ sh wsdl2java.sh -uri https://<IP>:<PORT>/services/FunctionProcessServiceService?wsdl -o out -uw

A Java client to invoke, FunctionProcessServiceServiceStub#functionProcessServiceOperation is given below.

import org.apache.axis2.AxisFault;
import org.apache.axis2.context.ConfigurationContext;
import org.apache.axis2.context.ConfigurationContextFactory;
import wsdl.functionprocessservice.FunctionProcessServiceServiceStub;
import java.rmi.RemoteException;

public class Client {

     public static void main(String[] args) throws AxisFault {
          ConfigurationContext cc = ConfigurationContextFactory.createConfigurationContextFromFileSystem("/home/thilini/wso2bps-2.1.2/repository/deployment/client", "/home/thilini/wso2bps-2.1.2/repository/conf/axis2_client.xml");

          String url = "jms:/FunctionProcessServiceService?transport.jms.DestinationType=queue&transport.jms.ContentTypeProperty=Content-Type&java.naming.provider.url=tcp://localhost:61616&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory";
          FunctionProcessServiceServiceStub stub = new FunctionProcessServiceServiceStub(cc, url);

                    try {
                         System.out.println("******* Response: " + stub.functionProcessServiceOperation(2, 4));
                    } catch (RemoteException e) {
                         e.printStackTrace();
                    } catch (Exception e) {
                         e.printStackTrace();
                    }
               }
        }

You need to add the following set of jars to the classpath.

  • activemq-core-5.2.0.jar   (ActiveMQ_HOME\lib)
  • geronimo-jms_1.1_spec-1.1.1.jar   (ActiveMQ_HOME\lib)
  • geronimo-j2ee-management_1.0_spec-1.0.jar   (ActiveMQ_HOME\lib)
  • axis2-transport-jms-1.1.0-wso2v5.jar   (WSO2BPS_HOME/repository/components/plugins)
  • commons-io-2.0.0.wso2v1.jar   (WSO2BPS_HOME/repository/components/plugins)
  • jettison-1.1.wso2v1.jar   (WSO2BPS_HOME/repository/components/plugins)

When you run the client, it sends a JMS request to the BPS Server and creates an instance of the FunctionProcess. Notice that the total instance count of the FunctionProcess is increased. (see Figure 6) 

 Figure 6

 Then the server sends a response back to the client and you will see the response message on the client console. (see Figure 7). Maven built, client program is available here

 Figure 7 

SOAP over JMS with WSO2 BPS

Figure 8

Here, I have deployed a BPEL process in the WSO2 BPS. It has a http endpoint and hosted 3 partner services (i.e: Adder Service, Square Service and Multiple Service) in WSO2 Application Server which has JMS endpoints.

The deployment and the communication architecture diagram are shown in Figure 8.

The JMS sender (i.e: Apache Active MQ) delivers the SOAP request message coming through the BPS Server to the destination queue and receives the SOAP response message.

  • To talk to JMS sender by the SOAP engine (BPS server), you need to enable transport sender configurations for JMS in axis2.xml
  • To talk to WSO2 Application Server by the JMS sender, you need to enable transport receiver configurations for JMS in axis2.xml

 

 

Author

Thilini Ishaka
Software Engineer, WSO2 Inc.
[email protected]

 

 

About Author

  • Thilini Ishaka
  • Associate Technical Lead
  • WSO2