WSO2 Synapse Handlers

I assume you are already familiar with WSO2 products and used it or tested it. WSO2 product used as middleware to interconnect two services together. For that, you may need to do some changes to the request before send it to the target backend. For example think, you have a website that accepts payment orders and you need to send those orders to payment gateway to complete the financial transaction. Before sending it to the payment gateway you may need to do some changes to this incoming message, for this requirement, we can use WSO2 product(Integration server) between the website and the payment gateway to transforming the messages.

WSO2 uses synapse to convert incoming messages into the desired format. Synapse is based on the Apache synapse implementation where it to transformation to message with transformation rules written in Synapse language. Synapse instruction is written in XML format so that humans can also read it.

Handlers are type of a hook that triggers some specific events. For synapse handers there can be three events trigger when a request comes into the Integration server.

• The request comes into the server. This is known as for request inflow.
• Request forward to the backend server. Also, know as request outflow
• The response coming from the backend server. This knows as response inflow.
• Response sent back to the client which is known as response outflow.

You can implement a synapse handler by using the AbstractSynapseHandler abstract class. Here it provides four methods that supposed to override to access each of those events.

public boolean handleRequestInFlow(MessageContext synCtx);

public boolean handleRequestOutFlow(MessageContext synCtx);

public boolean handleResponseInFlow(MessageContext synCtx);

public boolean handleResponseOutFlow(MessageContext synCtx);

For all of these functions, you can access the request’s content by using the MessageContext object. Here it contains all the details about incoming messages, synapse artifacts that required to use it in the handler.

Here below a complete example of code that will print log when each of the phases getting hit.

package org.wso2.sample.synapse.handler;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.synapse.AbstractSynapseHandler;
import org.apache.synapse.MessageContext;
/** 
* This is a sample handler that log for all message flows. 
*/
public class BasicHandler  extends AbstractSynapseHandler{
private static final Log log =            LogFactory.getLog(BasicHandler.class);
// Handle incoming message flow to the EI server    
    public boolean handleRequestInFlow(MessageContext messageContext){        
        log.info("Inside Request Inflow");
        return true;    
    }     
    public boolean handleRequestOutFlow(MessageContext messageContext){
        log.info("Inside Request Outflow");
        return true;
    }     
    public boolean handleResponseInFlow(MessageContext messageContext){
        log.info("Inside Response Inflow");
        return true;    
    }     
    public boolean handleResponseOutFlow(MessageContext messageContext){
        log.info("Inside Response Outflow");
        return true;    
    }
}

You can find out complete code and instruction in https://github.com/madushadhanushka/wso2-artifacts-samples/tree/master/Handlers/1-basic-synapse-handler/BasicHandler

To test this handler, first, you need to compile this code and build the jar files. Then jar files should be placed in <PRODUCT_HOME>/lib directory.

Then you need to register this handler into the system by adding a following line into the handlers tag in <PRODUCT_HOME>/conf/synapse-handlers.xml file.

<handler name = "BasicHandler" class="org.wso2.sample.synapse.handler.BasicHandler"/>

Since you need to print logs on the console add following property into the log4j.properties file located in <PRODUCT_HOME>/conf directory.

log4j.logger.org.wso2.sample.synapse.handler.BasicHandler=INFO

Then you can create a proxy service and evoke it, then you can notice that logs getting printed for each of those phases of the handler.

You can use a synapse handler where you want to do repetitive things that perform on each of the services. For example, if you need to change all message header before it hit the mediation flow, you can easily implement it in the handler and use it.

WSO2 Enterprise Integrator

Micro Integrator

WSO2 Integration Studio

Now you can preorder Cloud-Native Application with Ballerina book on Amazon. Click here to pre-order the book.