Retry Configuration for Error Handling in Endpoint

“retryConfig” element in WSO2 ESB facilitates developer to retry the endpoint on failure of known error codes. “retryConfig” has two different extreme flavours known as “disabledErrorCodes”  and “enabledErrorCodes” to enhance user to manage known error codes on endpoint failures.

Lets take an Example based on WSO2 ESB sample 52 [1]

Above image is illustrating a simple use case of demonstrate simple load balancing among a set of endpoints use.

Given Synapse Configuration below meet above mentioned objective.

	<definitions xmlns="http://ws.apache.org/ns/synapse">
	<sequence name="main" onError="errorHandler">
	<in>
	<send>
	<endpoint>
	<loadbalance>
	<endpoint>
	<address uri="http://localhost:9001/services/LBService1">
	<enableAddressing/>
	<suspendDurationOnFailure>60</suspendDurationOnFailure>
	</address>
	</endpoint>
	<endpoint>
	<address uri="http://localhost:9002/services/LBService1">
	<enableAddressing/>
	<suspendDurationOnFailure>60</suspendDurationOnFailure>
	</address>
	</endpoint>
	<endpoint>
	<address uri="http://localhost:9003/services/LBService1">
	<enableAddressing/>
	<suspendDurationOnFailure>60</suspendDurationOnFailure>
	</address>
	</endpoint>
	</loadbalance>
	</endpoint>
	</send>
	<drop/>
	</in>
	<out>
	<!-- Send the messages where they have been sent (i.e. implicit To EPR) -->
	<send/>
	</out>
	</sequence>
	<sequence name="errorHandler">
	<makefault response="true">
	<code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
	<reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
	</makefault>
	<send/>
	</sequence>
	</definitions>

view raw SynaspeRetry1.xml hosted with ❤ by GitHub

Nevertheless, system admin or developer might already know about the Error Codes [2] that occurs during the endpoint failure, In order to avoid above circumstance it is possible to use “retryConfig”.

In known Error occurring situation, “disabledErrorCodes” disables the retry only for defined error codes within the configuration. Whereas, “enabledErrorCodes” will enable the retry only for defined error codes. Furthermore, it is not possible to have both keywords at the same time for given endpoint.By default, WSO2 ESB accepts only  the “disabledErrorCodes” keyword in above mentioned situation.

	<?xml version="1.0" encoding="UTF-8"?>
	<definitions xmlns="http://ws.apache.org/ns/synapse">
	<sequence name="errorHandler">
	<log level="custom">
	<property name="MESSAGE" value="Executing default &#34;fault&#34; sequence"/>
	<property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
	<property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>
	</log>
	<makefault response="true">
	<code xmlns:tns="http://www.w3.org/2003/05/soap-envelope" value="tns:Receiver"/>
	<reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
	</makefault>
	<send/>
	</sequence>
	<sequence name="fault">
	<log level="full">
	<property name="MESSAGE" value="Executing default &#34;fault&#34; sequence"/>
	<property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
	<property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>
	</log>
	<drop/>
	</sequence>
	<sequence name="main" onError="errorHandler">
	<in>
	<send>
	<endpoint>
	<loadbalance algorithm="org.apache.synapse.endpoints.algorithms.RoundRobin">
	<endpoint>
	<address uri="http://localhost:9001/services/LBService1">
	<retryConfig>
	<disabledErrorCodes>101503</disabledErrorCodes>
	</retryConfig>
	</address>
	</endpoint>
	<endpoint>
	<address uri="http://localhost:9002/services/LBService1">
	<retryConfig>
	<enabledErrorCodes>101503</enabledErrorCodes>
	</retryConfig>
	</address>
	</endpoint>
	<endpoint>
	<address uri="http://localhost:9003/services/LBService1">
	<enableAddressing/>
	<suspendOnFailure>
	<initialDuration>60000</initialDuration>
	<progressionFactor>1.0</progressionFactor>
	</suspendOnFailure>
	</address>
	</endpoint>
	</loadbalance>
	</endpoint>
	</send>
	<drop/>
	</in>
	<out>
	<send/>
	</out>
	</sequence>
	</definitions>

view raw SynapseRetry2.xml hosted with ❤ by GitHub

Above Synapse configuration demonstrate the basic usage of “retryConfig”.

Follow the WSO2 ESB sample 52 [1] and configure the axis2servers, As per given Synapse configuration, load balancer won't retry on “server 1”s connection failure and print “COULDN'T SEND THE MESSAGE TO THE SERVER” on client side. Whereas, if “server 2”s connection failure only it will retry the other end points.

[1] http://docs.wso2.org/wiki/display/ESB470/Sample+52%3A+Sessionless+Load+Balancing+Between+3+Endpoints

[2]http://docs.wso2.org/wiki/display/ESB470/Error+Handling+and+Error+Codes

JSON to XML conversion using WSO2 ESB

I am using WSO2 ESB 4.6.0 version to demonstrate this sample, simple yet powerful.

You do not need to write your own code or relay on other library to convert json to xml. Simple WSO2 esb proxy can do the conversion for you, so we will try that. 

Lets set the requirement is to use a parameter to the methods to control whether to return JSON or XML. 

Given synapse configuration below has the very basic configuration to solve this requirement.

	<?xml version="1.0" encoding="UTF-8"?>
	<definitions xmlns="http://ws.apache.org/ns/synapse">
	<registry provider="org.wso2.carbon.mediation.registry.WSO2Registry">
	<parameter name="cachableDuration">15000</parameter>
	</registry>
	<sequence name="fault">
	<log level="full">
	<property name="MESSAGE" value="Executing default 'fault' sequence"/>
	<property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
	<property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>
	</log>
	<drop/>
	</sequence>
	<sequence name="main">
	<in>
	<log level="full"/>
	<filter source="get-property('To')" regex="http://localhost:9000.*">
	<send/>
	</filter>
	</in>
	<out>
	<send/>
	</out>
	<description>The main sequence for the message mediation</description>
	</sequence>
	<api name="JsonToXmlApi" context="/Test">
	<resource methods="POST" uri-template="/xml/">
	<inSequence>
	<property name="messageType" value="text/xml" scope="axis2"/>
	<header name="To" action="remove"/>
	<property name="RESPONSE" value="true" scope="default" type="STRING"/>
	<send/>
	</inSequence>
	</resource>
	<resource methods="POST" uri-template="/json/">
	<inSequence>
	<property name="messageType" value="application/json" scope="axis2"/>
	<header name="To" action="remove"/>
	<property name="RESPONSE" value="true" scope="default" type="STRING"/>
	<send/>
	</inSequence>
	</resource>
	</api>
	</definitions>

view raw synaspeJsontoXmlAPI.xml hosted with ❤ by GitHub

"JsonToXmlApi" rest api has two resource in the "Test" context. "/xml/" resource will covert the incoming json payload into xml format and send that back to client. whereas,  "/json/" resource without converting which will echo back to the client.

You can test this using curl commands that have given below,

	curl -i -H "Content-Type: application/json" -X POST -d '{
	"peoples": {
	"people": [
	{
	"class": "Person",
	"name": "vanjikumaran",
	"birthday": "today",
	"nickname": "Oracle of Omaha",
	"phonNumbers": {
	"phonNumber": [
	{
	"class": "Phone",
	"name": "cell",
	"number": "555-123-4567"
	},
	{
	"class": "Phone",
	"name": "home",
	"number": "555-987-6543"
	},
	{
	"class": "Phone",
	"name": "work",
	"number": "555-678-3542"
	}
	]
	}
	},
	{
	"class": "Person",
	"name": "Steven Jobs",
	"birthday": "Yesterday",
	"nickname": "Steve",
	"phonNumbers": {
	"phonNumber": [
	{
	"class": "Phone",
	"name": "cell",
	"number": "555-123-4567"
	},
	{
	"class": "Phone",
	"name": "home",
	"number": "555-987-6543"
	},
	{
	"class": "Phone",
	"name": "work",
	"number": "555-678-3542"
	}
	]
	}
	}
	]
	}
	}' http://localhost:8280/Test/json/

view raw curlRequestjson hosted with ❤ by GitHub

	curl -i -H "Content-Type: application/json" -X POST -d '{
	"peoples": {
	"people": [
	{
	"class": "Person",
	"name": "vanjikumaran",
	"birthday": "today",
	"nickname": "Oracle of Omaha",
	"phonNumbers": {
	"phonNumber": [
	{
	"class": "Phone",
	"name": "cell",
	"number": "555-123-4567"
	},
	{
	"class": "Phone",
	"name": "home",
	"number": "555-987-6543"
	},
	{
	"class": "Phone",
	"name": "work",
	"number": "555-678-3542"
	}
	]
	}
	},
	{
	"class": "Person",
	"name": "Steven Jobs",
	"birthday": "Yesterday",
	"nickname": "Steve",
	"phonNumbers": {
	"phonNumber": [
	{
	"class": "Phone",
	"name": "cell",
	"number": "555-123-4567"
	},
	{
	"class": "Phone",
	"name": "home",
	"number": "555-987-6543"
	},
	{
	"class": "Phone",
	"name": "work",
	"number": "555-678-3542"
	}
	]
	}
	}
	]
	}
	}' http://localhost:8280/Test/xml/

view raw curlRequestxml hosted with ❤ by GitHub

Hello JAX-RS

In my last post i have given a brief  introduction to JAX-RS. Before look into this further It would be great if we do a hands on session to understand the usage and development procedure.

For the change, I will start with “Hello JAX-RS” instant of “Hello World”!!!!

In order to do this i am using maven as a builder, Tomcat Server as application server and Idea intellij as IDE. Most importantly I am using jersey 1.17.1 as the JAX-RS implementation.

First of all we have to create a web application project. This task can be achieved by maven.

mvn archetype:generate -DgroupId=com.area51.rest -DartifactId=RESTfulExample -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false

After project created by maven, the folder structure looks like. If you see carefully "java" folder is not there in the folder structure.

Folder Structure

Thu i have manually added a folder under src/main/java and ran mvn idea:idea (if you are using eclipse use mvn idea:idea)

I have share the complete project here 

	<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.area51.rest</groupId>
	<artifactId>RESTfulExample</artifactId>
	<packaging>war</packaging>
	<version>1.0-SNAPSHOT</version>
	<name>RESTfulExample Maven Webapp</name>
	<url>http://maven.apache.org</url>
	<dependencies>
	<dependency>
	<groupId>junit</groupId>
	<artifactId>junit</artifactId>
	<version>3.8.1</version>
	<scope>test</scope>
	</dependency>
	<dependency>
	<groupId>com.sun.jersey</groupId>
	<artifactId>jersey-bundle</artifactId>
	<version>1.8</version>
	</dependency>
	<dependency>
	<groupId>asm</groupId>
	<artifactId>asm</artifactId>
	<version>3.3.1</version>
	</dependency>
	</dependencies>
	<build>
	<finalName>RESTfulExample</finalName>
	<plugins>
	<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-compiler-plugin</artifactId>
	<version>3.1</version>
	<configuration>
	<source>1.6</source>
	<target>1.6</target>
	</configuration>
	</plugin>
	</plugins>
	</build>
	<repositories>
	<repository>
	<id>maven2-repository.java.net</id>
	<name>Java.net Repository for Maven</name>
	<url>http://download.java.net/maven/2/</url>
	<layout>default</layout>
	</repository>
	</repositories>
	</project>

view raw RESTfulExample_pom.xml hosted with ❤ by GitHub

	/**
	* Created with IntelliJ IDEA.
	* User: vanji
	* Date: 7/12/13
	* Time: 1:37 PM
	* To change this template use File | Settings | File Templates.
	*/
	package com.area51.rest;
	import javax.ws.rs.GET;
	import javax.ws.rs.Path;
	import javax.ws.rs.PathParam;
	import javax.ws.rs.core.Response;
	@Path("/hello")
	public class HelloJaxRsService {
	@GET
	@Path("world/{param}")
	public Response getMsg(@PathParam("param") String msg) {
	String output = "JAX-RS say Hello to: " + msg;
	return Response.status(200).entity(output).build();
	}
	@GET
	@Path("home/{param}")
	public Response getHomeMsg(@PathParam("param") String msg) {
	String output = "JAX-RS say Hello to: " + msg +" from home";
	return Response.status(200).entity(output).build();
	}
	}

view raw RESTfulExample_src_main_java_com_area51_rest_HelloJaxRsService.java hosted with ❤ by GitHub

	<html>
	<body>
	<h1>Hello World from JAX-RS</h1>
	<br/>
	<h2>Sample JAX RS With 1G</h2>
	</body>
	</html>

view raw RESTfulExample_src_main_webapp_index.jsp hosted with ❤ by GitHub

	<!DOCTYPE web-app PUBLIC
	"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
	"http://java.sun.com/dtd/web-app_2_3.dtd" >
	<web-app id="WebApp_ID" version="2.4"
	xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
	http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
	<display-name>Restful Web Application</display-name>
	<servlet>
	<servlet-name>jersey-serlvet</servlet-name>
	<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
	<init-param>
	<param-name>com.sun.jersey.config.property.packages</param-name>
	<param-value>com.area51.rest</param-value>
	</init-param>
	<load-on-startup>1</load-on-startup>
	</servlet>
	<servlet-mapping>
	<servlet-name>jersey-serlvet</servlet-name>
	<url-pattern>/rest/*</url-pattern>
	</servlet-mapping>
	</web-app>

view raw RESTfulExample_src_main_webapp_WEB-INF_web.xml hosted with ❤ by GitHub

Given pom.xml I have added the  dependency for  jersy and set the source as java 1.6.
HelloJaxRsService.java is the implementation for "Hello JAX - RS"demonstration.

If you carefully study into the code that i have given, you can understand that "@Path("/hello")" annotation indicate the context of the class "HelloJaxRsService.java". "@GET" indicate the methods classify the methods as GET request method (HTTP vocabulary of request operation).  @Path("world/{param}") annotation is a resource in the "hello" context with the parameter.


Okay, Lets up and run this code.

First of all! compile the code using maven!,  get the "war" file! and configure the apache tomacat server with it.

In this example, web request from “projectURL/rest/hello/” will match to “HelloJaxRsService“, via @Path("/hello").

http://localhost:9000/RESTfulExample/rest/hello/world/human request hits the hello context and world resource.

http://localhost:9000/RESTfulExample/rest/hello/home/Vanjikumaran request hits the hello context and home resource.

Java API for RESTful Services

Java API for RESTful Services (JAX-RS)

JAX-RS: Java API for RESTful Web Services is a Java API that provides support in creating web services according to the Representational State Transfer (REST) architectural pattern. Furthermore JAX-RS uses annotations to simplify the development and deployment of web service clients and endpoints.

To Understand further about JAX-RS refer the document provided by oracle[1] which contain compressible information about JAX-RS.


You can find various implementation that are available in industry and well known implementation are

1) Apache CXF - an open source Web service framework provided by Apache Software Foundation.
2) Jersey - an implementation from Oracle.
3) ESTeasy - an implementation from JBoss.
4) Apache Wink, Apache Software Foundation Incubator project, the server module implements JAX-RS.


I will provide a sample implementation for REST Web Service using JAX-RS in near future blog.
Until that please keep on reading :)


[1] http://docs.oracle.com/javaee/6/tutorial/doc/giepu.html
[2] http://en.wikipedia.org/wiki/Java_API_for_RESTful_Web_Services

Debugging techniques In Idea intellij :- IDEA 1

Recently I was in the situation to debug couple of components that is not in the same pom.xml and It is not possible to open up different windows and debug!! 

After view minutes of search in google, i found out couple of cool techniques, that allow us to debug different component in the same place. Lets go though it, step by step (here i will refer Idea intellij as IDE).

Step 1

You can see the "Project Structure" button that appear in right hand side (Circled) of your current opened project.

Step 2

You can see a "Modules" in left hand side in project structure. once you clicked that, you can see there is a "Sources" tab under the Name of the project.

Once you get into there, you can see a button named with "Add Content Root"

Step 3

Then you have to select content root directory that you want to add into current project structure.

Step 4

Finally you can see, you have add a content in to your project structure. If you want to add more content, repeat the Step 2 and Step 3.

Click Ok, you can see the changes in project structure with new content in it!

Now you can do you normal way of debugging your projects!! 

Mount WSO2 Governance Registry to WSO2 ESB with Read only Mode

As most of you all know, we have a product called WSO2 Governance Registry which is known as GReg to facilitate and cater the right level of structure straight out of the box to support SOA Governance, configuration governance, development process governance, design and run-time governance, life-cycle management, and team collaboration.

So in this example I am going to use our GReg as registry for WSO2 ESB's resources.

Furthermore, the main intention of this demonstration is to showcase "how to configure WSO2 ESB in Read Only/Read Write mode for WSO2 GReg. Following illustration shows the conceptual deployment architecture. Where we have two WSO2 ESB, First is on READ and WRITE mode(Offset 1) and the latter one is with READ only mode(offset 2).

Before dirt our hands!! we have to do some prerequisite tasks!! Yes first of all download the products from wso2 product site.

Well it is not enough, we have to setup underlying storage for WSO2 Greg to Demonstrate this sample. Thus, we will use MYSQL as a database.

So lets take a step ahead and do the work,

Step 1

Create a Database in mysql (Lets say database name as “gregMount”)

CREATE DATABASE gregMount;

Step 2

Grant the permission to the created database.

GRANT ALL ON gregMount.* TO regadmin@localhost IDENTIFIED BY "regadmin"

Alright, We have just finished the very basic step of this example!

Step 3

Well ESB and GReg need the MySql libraries to understand the MySql API. Thus put the MySQL driver into <home>/repository/components/lib/

Step 4

We will step into the Greg configuration Changes! Open up
<home>/repository/conf/datasources/master-datasources.xml

Add a data source that look like following configuration

      <datasource>
            <name>WSO2_CARBON_DB</name>
            <description>The datasource used for registry and user manager</description>
            <jndiConfig>
                <name>jdbc/WSO2CarbonDB</name>
            </jndiConfig>
            <definition type="RDBMS">
                <configuration>
    <url>jdbc:mysql://localhost:3306/gregMount</url>
                    <username>regadmin</username>
                    <password>regadmin</password>
                    <driverClassName>com.mysql.jdbc.Driver</driverClassName>
                    <maxActive>50</maxActive>
                    <maxWait>60000</maxWait>
                    <testOnBorrow>true</testOnBorrow>
                    <validationQuery>SELECT 1</validationQuery>
                    <validationInterval>30000</validationInterval>
                </configuration>
            </definition>
        </datasource>

Step 5

Start the GReg first time with  <home>/bin sh wso2server.sh -Dsetup

Lets step into the WSO2 ESB and do the Read and Write mode configuration!

Step 6

Since we have used WSO2 GReg with default offset, we have to change the offset of the ESB (ReadWrite mode ESB) to <Offset>1</Offset>

In order to do this you have to change the default value of  Offset of  <home>/repository/conf/carbon.xml

Step 7

As mentioned bellow,add DataSource configuration into ESB's <home>/repository/conf/datasources/master-datasources.xml

     <datasource>
            <name>WSO2_CARBON_DB_GREG</name>
            <description>The datasource used for registry and user manager</description>
            <jndiConfig>
                <name>jdbc/WSO2CarbonDB_GREG</name>
            </jndiConfig>
            <definition type="RDBMS">
                <configuration>
                   <url>jdbc:mysql://localhost:3306/gregMount</url>
                    <username>regadmin</username>
                    <password>regadmin</password>
                    <driverClassName>com.mysql.jdbc.Driver</driverClassName>
                    <maxActive>50</maxActive>
                    <maxWait>60000</maxWait>
                    <testOnBorrow>true</testOnBorrow>
                    <validationQuery>SELECT 1</validationQuery>
                    <validationInterval>30000</validationInterval>
                </configuration>
            </definition>
        </datasource>

Step 8

You need to do the following changes in the registry.xml that could be find in <home>/repository/conf/registry.xml.

Adding database configuration.

<dbConfig name="wso2registryRemort"> <dataSource>jdbc/WSO2CarbonDB_GREG</dataSource> </dbConfig>

add remote instance that point to Wso2 Greg

  <remoteInstance url="https://localhost:9443/registry">

        <id>instanceid</id>
        <dbConfig>wso2registryRemort</dbConfig>
        <readOnly>false</readOnly>
        <enableCache>true</enableCache>
        <registryRoot>/</registryRoot>
    </remoteInstance>

Mount the config and governance


  <mount path="/_system/config" overwrite="true">
        <instanceId>instanceid</instanceId>
        <targetPath>/_system/nodes</targetPath>
    </mount>
   <mount path="/_system/governance" overwrite="true">
        <instanceId>instanceid</instanceId>
        <targetPath>/_system/governance</targetPath>
 </mount>

If you notice the remoteInstance configuration carefully, we have configured this ESB as readOnly false mode, it means we can Read and Write to the GReg.

Perfect!!! now we have completed almost everything that is needed for this demonstration. Lets see how to configure the Read only mode ESB in this demonstration.

Step 9

follow the above steps 6 to 8 to the second instance of ESB but make the Offset as <Offset>1</Offset> and Read only mode as True

Now you have the GReg and two ESB to test the Read only Mode

Test cases :- Try to add endpoint using ReadOnly ESB to registry.