2014/04/08
8 Apr, 2014

Development and Deployment of C-App Based Artifacts on Multiple Environments

  • Sohani Weerasinghe
  • Senior Software Engineer - WSO2

Applies to

WSO2 Developer Studio Version 3.6
WSO2 Enterprise Service Bus Version 4.8
WSO2 Governance Registry Version 4.6
WSO2 Application Server Version 5.2.1
MySQL Server Version 5.5
ActiveMQ Version 5.9

Table of contents

  • Introduction
  • Use case
  • The procedure
  • Prerequisites for implementation
  • Implementing the scenario
    • How to Implement the student registration service
    • How to develop registry resources
    • How to implement the student registration process
  • Deploying the integrated solution
  • Testing the solution
  • Conclusion

Introduction

Artifacts should generally be changed based on the environment where the application is deployed. Therefore, when deploying a composite application on Dev, QA and Production environments, the endpoint becomes the main reference to the backend service.

This article primarily concentrates on managing these endpoints in an appropriate manner.

In the following example, WSO2 Enterprise Service Bus (ESB) will be the mediation engine, while WSO2 Application Server (AS) has been used to host backend services and WSO2 Governance Registry (GREG) has been used to store dynamic resources, such as endpoints. WSO2 Developer Studio has been used to develop artifacts.

When considering a deployment setup there are several options available. There can be one embedded registry per environment as shown in Figure (1), where all references can be saved in the same registry branch. The second option is sharing a registry instance among the environments as shown in Figure (2), where references should be stored in separate registry branches. The third option is having a standalone registry per environment, as shown in Figure (3); in this article we will mainly focus on the third option. A sample use case has been used to explain the scenario more comprehensively.

Figure 1: One embedded registry per environment

Figure 2: Shared registry instance across multiple environments

Figure 3: One standalone registry per environment

Use case

A student registration service needs to be enforced at a foreign university and the IT department of the university has given the contract to an application development company to enforce the scheme. Mainly, there are three types of groups in the application development company; Developers, QA engineers, and DevOps.

Developers develop the system to accept student registration details and send it to the backend service. They use the Dev environment to develop and deploy the artifacts, but they do not have permission to access QA and Production. DevOps basically need to update the endpoints accordingly in order to deploy the application created by developers to QA and production environments. QA engineers then test the application in a QA environment.

The procedure

Prerequisites for implementation

It is a prerequisite to install WSO2 Developer Studio, to do this please refer the Installation Guide. Prior to implementing this process you need to install and configure WSO2 products and third party tools mentioned in the ‘Applies To’ section. Moreover, you will require the software libraries and drivers listed below.

Required software libraries and drivers:

  • ActiveMQ
    • activemq-broker-5.9.0.jar
    • activemq-client-5.9.0.jar
    • geronimo-j2ee-management_1.1_spec-1.0.1.jar
    • geronimo-jms_1.1_spec-1.1.1.jar
  • MySQL JDBC Driver
    • mysql-connector-java-5.1.22-bin.jar

Install and configure MySQL, Apache ActiveMQ and WSO2 Servers

  • MySQL

Follow the default instructions provided by MySQL.com to install the MySQL server. Create a database within MySQL called GregDB.You can populate the database either by running the MySQL script in the command line as shown below or at the GREG server startup.

Source GREG_HOME/dbscripts/mysql.sql;

  • Apache ActiveMQ

Follow the default instructions provided by Apache to install ActiveMQ server.

  • WSO2 servers

To install WSO2 servers, first unpack the downloaded archive. As a reference point, the following logical directory names have been used for each server.

  • WSO2 ESB - ESB_HOME
  • WSO2 Governance Registry - GREG_HOME
  • WSO2 Application Server - AS_HOME

In order to avoid port conflicts, and since all WSO2 products listen on ports 9763 (HTTP) and 9443 (HTTPS) by default, change the “offset” parameter in the servers' main configuration ‘carbon.xml’ found in $CARBON_HOME/repository/conf.

eg: 1

  • WSO2 ESB - 0 (ESB will now listen on 9763 and 9443)
  • WSO2 GREG - 1 (GREG will now listen on 9764 and 9444)
  • WSO2 App Serve - 2 (Data Services Server will now listen on 9765 and 9445)

Configure WSO2 ESB

  • Leave the offset parameter as it is to ‘0’.
  • Enable ESB to talk over a message queue by copying the ActiveMQ libraries (activemq-broker-5.9.0.jar,activemq-client-5.9.0.jar,geronimo-j2ee-management_1.1_spec-1.0.1.jar,geronimo-jms_1.1_spec-1.1.1.jar) to the $ESB_HOME/repository/components/lib.
  • Enable the JMS transport on the ESB by uncommenting the [transportReceiver name="jms"] and [transportSender name="jms"] in $ESB_HOME/repository/conf/axis2/axis2.xml.

/transportReceiver>

And

  • Enable database access by copying the MySQL driver library (mysql-connector-java-5.1.13-bin.jar) to $ESB_HOME/repository/components/lib.
  • To mount WSO2 ESB to WSO2 GREG follow the following steps;
    • Add a new datasource configuration to master-datasources.xml in $ESB_HOME/repository/conf/datasources
  

            WSO2_CARBON_DB_GREG
            The datasource used for registry and user manager
            
                jdbc/WSO2CarbonDB_GREG
            
            
                
                    jdbc:mysql://localhost:3306/GregDB
                    root
                    root
                    com.mysql.jdbc.Driver
                    50
                    60000
                    true
                    SELECT 1
                    30000
                
            
        

Add a new db config to registry.xml in $ESB_HOME/repository/conf/ in order to refer the newly added data source

  

        jdbc/WSO2CarbonDB_GREG

  • Add a remote governance registry instance in registry.xml
  •   
    
            instanceid
            mounted_registry
            false
            true
            /
            root@jdbc:mysql://localhost:3306/GregDB
    
    
  • Add mount configurations to registry.xml
  •   
    
            instanceid
            /_system/nodes
        
    
    
            instanceid
            /_system/governance
        
    
  • Enable clustering in axis2.xml in $ESB_HOME/repository/conf/axis2 to send cache invalidation messages across the GREG and ESB.
  •   
    
    

    Configuring WSO2 GREG

    • Set offset parameter to ‘1’
    • Update the datasource configuration in master-datasources.xml in $GREG_HOME/repository/conf/datasources
      
     
                WSO2_CARBON_DB
                The datasource used for registry and user manager
                
                    jdbc/WSO2CarbonDB
                
                
                    
                        jdbc:mysql://localhost:3306/GregDB
                        root
                        root
                        com.mysql.jdbc.Driver
                        50
                        60000
                        true
                        SELECT 1
                        30000
                    
                
            
    
  • Enable clustering in axis2.xml in $GREG_HOME/repository/conf/axis2 to send cache invalidation messages across WSO2 GREG and WSO2 ESB.
  •   
    
    

    Configuring WSO2 Application Server

    • Set offset parameter to ‘2’.
    • To enable WSO2 Application Server to talk over a message queue follow the same step as WSO2 ESB, which was done previously.
    • To enable the JMS transport on WSO2 Application Server follow the same step as WSO2 ESB.

    Implementing the scenario

    1. How to implement the student registration service
    2. How to develop registry resources
    3. How to implement the student registration process
    1. How to implement the student registration service
    • Go to File -> New -> Project.
    • In the New Project wizard, expand WSO2 -> Maven Project and click Maven Multi Module Project and then click Next.
    • In “Maven information settings” dialog box, provide necessary information as shown below and click “Finish”.
    • Next, right click on the created ‘StudentRegistrationProject’ and select New -> Axis2 Service Project. Thereafter, select option to - Create New Axis2 Service and click “Next”.
    • Then create a class called ‘StudentRegistration’ and click “Finish”.
    • The configuration of ‘StudentRegistration’ is available at Student Registration
    • Then right click on the created Axis2 Project and select New-> Axis2 Service Class; then create a new Axis2 Class name ‘RegistrationService’
    • For the final configuration of the ‘RegistrationService’ click here
    • This service will be communicated via JMS transport, so the below code should be added to services.xml under /src.main.resources/META-INF to enable JMS transport.
    • jms

    • Final configuration of the services.xml is available at final configuration
  • How to develop registry resources
    • Select ‘StudentRegistrationProject’ and go to the WSO2 Developer Studio Dashboard and then select “Registry Resources Project” under the Governance Registry.
    • Then give a name to the project and click on “Finish”.
    • Right click on the created Governance Registry Project and select New -> Folder and create three folders as DEV, QA and PROD as shown below.
    • Then right click on the DEV folder and select New-> Registry Resource.
    • From the wizard select the option ‘from existing template’ and click “Next”.
    • In the wizard fill the fields as shown below and click “Finish”.
    • Thereafter, create registry resources as same as the above for QA and PROD. The resource name should be ‘RegistrationEP' for both QA and PROD. The artifact name should be ‘RegistrationEP-qa’ for QA and ‘RegistrationEP-prod’ for PROD. Template, “Registry” and registry path should be the same as in DEV.
    • Then click on the created registry resources and go to the properties window. The URI of the above three resources should be different to each other as shown below, since the service endpoints are different in each environment. For DEV, the backend service is available at the localhost and for QA and PROD the URIs are different based on the backend services.
      
    "jms:/RegistrationService?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"
    

      
    "jms:/RegistrationService?transport.jms.DestinationType=queue&transport.jms.ContentTypeProperty=Content-Type&java.naming.provider.url=tcp://activemq-server.qa.wso2.com:61616&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory"
    

      
     "jms:/RegistrationService?transport.jms.DestinationType=queue&transport.jms.ContentTypeProperty=Content-Type&java.naming.provider.url=tcp://activemq-server.prod.wso2.com:61616&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory"
    

    In this scenario, there is one standalone registry per environment. After mounting ESB to GREG the /_system/governance/endpoints of the ESB Server in the DEV or QA or Production refers the Endpoint configurations stored in /_system/governance/endpoints registry location of the GREG Server since Governance registry partition of the ESB Server is mounted to the /_system/governance/ in the Governance Registry. Deployment path for ESB Servers in DEV, QA and Production will be the same since in REST API (which will be described under the section Implement the Student Registration Process) configuration the endpoint key is gov:endpoints/RegistrationEP.xml. Therefore, DevOps does not need to change the artifacts implemented from developer studio when deploying in QA and Production.

    • Final configuration of the RegistrationEP.xml for DEV is available at RegistrationEP
  • How to implement the student registration process
    • Right click on the ‘StudentRegistrationProject’ and select New -> ESB Config Project and create a new project.
    • Then right click on the created ESB project and select “New” -> REST API and select the option ‘ Create a new API Artifact’
    • Then fill the fields as shown below and click “Finish”.

    This API has been defined with the context = “/student”; therefore, the URL of the request should contain “/student”. The fault sequence defined as ‘fault’ is used to handle any error that might occur while sending messages to the backend service, and if an error occurs, the fault sequence will respond with an error message.

    • Final configuration of the StudentAPI is available at Student APIs.
    • Then right click on the ESB project and select New -> Sequence and create a sequence named ‘RegistrationSequence’.

    When registering operations taking place in the system, the student inputs come as JSON message to the ‘RegistrationSequence’. Mainly property mediators have been used to extract student inputs from the REST CLIENT request, and log mediators can be used to verify that the values have been properly extracted. After extracting the required values the payload factory mediator has been used to give the required payload with the arguments to the student inputs provided.

    • At the end of the message flow drag and drop a send mediator from the tool palette and include a “Named Endpoint”. Then click on the Named Endpoint and then go to the property window and select the value for the “Property Static Reference key”. Then a dialog window will popup.
    • Thereafter, click on the workspace and browse the endpoint path of the artifact name RegistrationEP-dev.
    • For the final configuration of the ‘RegistrationSequence’ click here.
    • Then right click on the ESB project again and select New -> Sequence and create a sequence name; ‘fault’.
    • For the final configuration of the fault sequence click here.
    • The design of the RegistrationSequence is as follows.

    Deploying the integrated solution

    The REST API and sequences need to include a single CApp to be deployed in ESBs and three resources have to be packed in three separate CApps to be used in Dev, QA and Prod.

    • Right click on the ‘StudentRegistrationProject’ and select New -> Composite Application Project’.
    • Then give ‘ProjectCApp’ as the project name and select following dependencies as shown below.
    • Open the pom.xml and define server roles as shown below
    • Then create a CApp named DEVCApp and insert the registry resource with the Artifact name RegistrationEP-dev as dependencies. Afterwards, create two CApps with the name QACApp and PRODCApp and include RegistrationEP-qa and RegistrationEP-prod, respectively.
    • Right click on the ‘StudentRegistrationProject’ and select Generate POM and then from the wizard select all projects and click ‘Finish.’
    • Subsequently, go to the StudentRegistrationProject’s location in the command line and run the following command - mvn clean install.
    • Now you can see in each CApp that there is a target folder, and inside the target folder, a .car file has been created.

    Testing the solution

    1. Start apache activeMQ, if it has not already started.
    2. Start the WSO2 GREG server if it has not already started with -Dsetup (if you did not manually run the MySQL script).
    3. Start WSO2 App Server if it has not already started.
    4. Start WSO2 ESB.

    To open WSO2 servers, go to $CARBON_HOME/bin and run the command wso2server.sh (Linux) or wso2server.bat (Windows). Once all the servers are initiated, the servers will run on following ports.

    • WSO2 ESB - 9443
    • WSO2 GREG - 9444
    • WSO2 Application Server - 9445

    First, deploy the CAR file created from DEVCApp to WSO2 GREG and then deploy the CAR file created from ‘ProjectCApp’ to WSO2 Application Server then to the WSO2 ESB.

    Go to the management console of each server and navigate to Manage -> Carbon Applications -> Add and browse to the CAR and upload it to the server.

    Send below REST CLIENT requests to test the service.

    • Testing in the Dev Environment
      
    curl -i -H "Content-Type: application/json" -X POST -d '{"register" : {"title":{"studentID":"1", "name":"sohani", "address": "Colombo", "contact":"0113334444"}}}' https://10.100.5.22:8280/student/register/json
    

    You can view the logs in the console and if an error message does not appear, the message has been successfully sent to the backend service. When testing in QA and production environments, the DevOps needs to deploy the CAR files created from QACApp and PRODCApp to QA and PROD Governance Registries, respectively. DevOps can use the same CAR file created from ‘ProjectCApp’ project in QA and PROD environments to deploy it in ESB and AS.

    Conclusion

    As discussed in this article, the developed application would generally have to go through multiple stages (i.e. Dev, QA, and production) and the dynamic artifacts (endpoints) have to be updated accordingly. Here, we propose a methodology that separates these artifacts, thereby enabling the user to update dynamic artifacts separately without changing the rest of the application while deploying the application in another environment.

     

    About Author

    • Sohani Weerasinghe
    • Senior Software Engineer
    • WSO2