Rewriting URLs using urlrewrite Mediator in WSO2 ESB

Introduction

In most cases, we directly send requests to Web services, without going through any intermediate bodies like an Enterprise Service Bus (ESB). But the usage of such an application gives you a loads of advantages and control, when consuming Web services. WSO2 ESB is an Enterprise Service Bus based on Apache Synapse. It is possible to extend the functionality of WSO2 ESB through a set of mediators. URLRewrite is such a mediator, which is able to manipulate URLs and certain message properties based on a set of rules defined by the user. This mediation capability can be used to shape up URLs and headers including SOAPAction, ReplyTo, From, FaultTo, etc. Depending on the positioning and  the sequence at which the mediator is placed, properties of either a request or a response can be modified.

 Applies To

Table of Contents

• How to Attach URLRewrite Mediator to WSO2 ESB 
  • Using the Binary Distribution
  • Building the Source
• Editing the ESB Configuration
  • "urlrewrite" Element
    • "rule" Element
      • "condition" Element
      • "set" Element
• How Does the URLRewrite Mediator Rewrite Message Proprties ?
• Sample - Using URLRewrite Mediator with SimpleStockQuoteService
• Different Rule Elements for Different Services
• Conclusion
• References

How to Attach URLRewrite Mediator to WSO2 ESB

• Using the Binary Distribution

  1. You can download the binary distribution of URLRewrite Mediator from the ESB Community Site. Clicking on the "Download Binary" link will download the urlrewrite-1.0.jar.

  2. Next, add it to your class path. Adding to the directory, <esb - home>/webapp/WEB-INF/lib is sufficient. ( <esb - home>, refers to the directory which contains  the WSO2 ESB  installation. This directory will be referred to as <esb-home> from now on)

  3. Modify the ESB configuration file, which is synapse.xml, that's found at <esb - home>/webapp/WEB-INF/classes/conf, according to your rewriting requirements. More on this is available further down on in this article.

• Building the Source

  1. Ensure you have installed Maven.

  2. Source of the URLRewrite mediator can be downloaded from the ESB Community site.

  3. Extract the zip archive to any location in your file system. This will extract it into a directory named "urlrewrite".

  4. Navigate to the directory, and execute the following command:

     mvn install

  5. A directory called “target” will be created, containing urlrewrite-1.0.jar

  6. Follow the steps 2-3 described under the "Using the Binary Distribution" section.

      

Editing the ESB Configuration

To obtain URL rewriting functionality, it is essential to add certain rules to the ESB configuration file. These rules need to be specified under the root element “urlrewrite”.  The general syntax of the urlrewrite element is given below:

<urlrewrite>
	<rule>
	    <condition property="To|trpurl|SOAPAction|ReplyTo|FaultTo|From" operator="equal|notequal" nextoperator="and|or"/>+
	    <set property="To|trpurl|SOAPAction|ReplyTo|FaultTo|From" [fromvalue]="" value=""/>+
	</rule>+
</urlrewrite>

Listing 1 - General syntax of a urlrewrite element

Following is an example of urlrewrite element with a single rule:

<urlrewrite>
	<rule>
	    <condition property="To" operator="Equal" nextoperator="and">http://localhost:8080/soap/SimpleStockQuoteService</condition>
	    <condition property="trpurl" operator="Equal" nextoperator="and">/test/SimpleStockQuoteService</condition> 
	    <condition property="SOAPAction" operator="equal">[a-z][a-z][a-z]:getFullQuote</condition>
	    <set property="addurl" value="http://127.0.0.1:9000/soap/SimpleStockQuoteService"/>
	    <set property="trpurl" value="/soap/SimpleStockQuoteService"/>
	    <set property="SOAPAction" value="urn:getQuote"/>
	</rule>
</urlrewrite>

Listing 2 - An example of urlrewrite element with a single rule

A detailed description on each of these elements, is given below:

“urlrewrite” Element

 This is the root element and contains one or more “rule” elements. This is qualified with the namespace "http://ws.apache.org/ns/synapse". Users can define several rule elements corresponding to different services. We will discuss more on this, when we talk about “condition” elements. URLRewrite mediator goes through all these "rule" elements for every message that comes into the mediator, processing only those rules that are relevant to the message. There is no particular order when specifying rules under the "urlrewrite" element.

“rule” Element

There can be one or more "rule" elements that are independent of each other. A "rule" element can contain one or more “condition” elements, followed by one or more “set” elements.

“condition” Element

A “condition” element contains three attributes; property, operator and nextoperator. Possible values for these attributes are given below along with a short description for each value.

 Table 1 - Attributes and possible values for condition element

The genaral syntax of the "condition" element looks this:

<condition property="To|trpurl|SOAPAction|ReplyTo|FaultTo|From" operator="equal|notequal" nextoperator="and|or"/>+

A sample "condition" element is given below:

<condition property="To" operator="Equal" nextoperator="and">http://localhost:8080/soap/SimpleStockQuoteService</condition>

The attribute “property” refers to a property of message context. In the above example, the attribute "property" is equal to “addurl”, hence it refers to addressing URL of the message.

The attribute “operator” specifies the operator used for evaluating the condition. This can be either the equal operator or the inequal operator. If the operator is “equal”, then the message property specified by the attribute “property” will be checked for the equality with the condition element content.This evaluation is resulted with either binary true or false.

The other attribute is “nextoperator”. This interconnects the condition elements given within a rule. Possible values are “and” and “or”. These operators behave in the same way as the binary operators “and” and “or”. But the “and” is given higher priority than the “or” operator. It is not necessary to put the "nextoperator" attribute to the last condition element, since it is not used to construct the binary expression. Lets take an example. Look at the three conditions given below:

<condition property="To" operator="Equal" nextoperator="and">http://localhost:8080/soap/SimpleStockQuoteService</condition>

<condition property="trpurl" operator="Equal" nextoperator="and">/test/SimpleStockQuoteService</condition> 

<condition property="SOAPAction" operator="equal">[a-z][a-z][a-z]:getFullQuote</condition>

 Listing 3 - A set of sample conditions

First two conditions are connected using the operator “and”. Second and third conditions are connected using the operator “or”. Following is an abstract view of the above three conditions:

        (condition 1) and (condition 2) or (condition 3)

Since “and” has higher priority than “or”, following statement is equivalent to the above statement:

        ((condition 1) and (condition 2)) or (condition 3)

Binary values resulting the evaluation of condition1 and condition 2, are evaluated with respect to the operator “and”. Its result will then be evaluated with the binary value resulting evaluating condition 3 with respect to the operator “or”.

After evaluating all these conditions, it will end up with a boolean value. If it is boolean true, then the URLRewrite mediator will modify the properties stated in the set elements. Else it will proceed to the next rule.

All of the attribute values are case insensitive. For example “SOAPAction” is a possible value for the attribute “property”. You can use soapaction, SOAPACTION, soapACTION, etc, and the mediator will recognize it as SOAPAction.

As for the content of the condition element, you can use regular expressions. You can find more on Java regular expressions here. See the third condition in the above set of sample conditions. Its element content is specified using a regular expression.

“set” Element

There can be one or more set elements for a rule element. It is necessary to declare a set element for each and every property you need to modify. Modifications denoted by the set elements are applied only if the set of conditions are evaluated true.

A general set element looks like the following:

<set property="To|trpurl|SOAPAction|ReplyTo|FaultTo|From" [fromvalue]="" value=""/>+

A sample set element looks like this:

<set property="addurl" value="http://127.0.0.1:9000/soap/SimpleStockQuoteService"/>

The list of attributes of a set element is listed below along with the possible values.

Table 2 - List of attributes of a set element along with the possible values

The list of properties is same as the property list given for condition element. You can modify these values of properties of a message to any value you wish. These values are also case insensitive as in condition elements.

The attribute “fromvalue” denotes the current value of the specified property. You can check it in a condition element as well. Hence, this attribute is considered optional. If it is specified, it is free to use regular expressions.

The attribute “value” denotes the new value that is going to be assigned to the specified property.

How Does the URLRewrite Mediator Rewrite Message Proprties ?

URLRewrite mediator picks up a rule element from the set of rules defined under the urlrewrite element. It normally picks up rules according to the order they appear in the configuration. Then it evaluates the conditions one by one. Then, it constructs a boolean expression out of the boolean values resulting in evaluating condition elements. These boolean values are interconnected using the “nextoperator” defined in the condition elements. This expression is evaluated and a boolean value is resulted. If it is boolean true, then the mediator will apply the modifications specified in the “set” elements. If the resulting value is boolean false, then then it will neglect the “set” element of that rule. Then the mediator will move to the next rule, and repeat the procedure.

When there are multiple rules, they are evaluated with respect to the original message context. The changes done by a preceding rule, will not be visible to the rules down the line. Every rule is evaluated with respect to the original message context which is passed into the mediator. Therefore, the rules are evaluated independent from each other.

Sample - using URLRewrite Mediator with SimpleStockQuoteService

This is an step by step guide to demonstrate how the URLRewrite mediator can be used. I am using the sample SimpleStockQuoteService, distributed with WSO2 ESB for this demonstration. We are using a standalone Apache Axis2 Web services engine as the server, bundled with WSO2 ESB distribution. Make sure you have Apache Ant, installed on your computer.

1. Add the urlrewrite -1.0.jar to the classpath. More on this can be found here.

2. Edit the ESB configuration as given below. The ESB configuration file named as "synapse.xml" can be found at <esb - home>/webapp/WEB-INF/classes/conf directory.

   <?xml version="1.0" encoding="UTF-8"?>
   <definitions xmlns="http://ws.apache.org/ns/synapse">
   	<in>
   	    <!-- rewrites the specified properties after evaluating the set of conditions -->
   	    <urlrewrite>
   	        <rule>
   	            <condition property="To" operator="Equal" nextoperator="and">http://localhost:8080/soap/SimpleStockQuoteService</condition>
   	            <condition property="trpurl" operator="Equal" nextoperator="and">/test/SimpleStockQuoteService</condition> 
   	            <condition property="SOAPAction" operator="equal">[a-z][a-z][a-z]:getFullQuote</condition>
   	            <set property="addurl" value="http://127.0.0.1:9000/soap/SimpleStockQuoteService"/>
   	            <set property="trpurl" value="/soap/SimpleStockQuoteService"/>
   	            <set property="SOAPAction" value="urn:getQuote"/>
   	       </rule>
   	    </urlrewrite>
   	    <send/>
   	</in>
   	<out>
   	   <send/>
   	</out>
   </definitions>

   Listing 4 - ESB Configuration

   Here we have added the URLRewrite mediator to the "in" sequence.

3. Now, start the ESB. If you have followed the above steps, the ESB will have started without any complains. 

4. Now, the service needs to be deployed. If you have already deployed this before, then skip this step and move on with the next. Otherwise, move to the directory <esb- home>/samples/axis2Server/src/SimpleStockQuoteService and run "ant". It will deploy the SimpleStockQuoteService in the simple Axis server.

5. Now, start the sample axis2 server. For that, move to the directory,

   <esb - home>/ samples/axis2Server. Then run the axis2server.sh or axis2server.bat depending on the operating system you are using. Then the sample Axis server will be started on port 9000.

6. Now, lets invoke the service. Go to the directory <esb - home>/samples/axis2Client . Then execute the following command.

   ant stockquote -Daddurl=http://localhost:8080/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/test/SimpleStockQuoteService -Dmode=fullquote -Dsymbol=IBM

7. Then you will get the following response:

   buddhika@buddhika-desktop:~/wso2esb-1.6/samples/axis2Client$ ant stockquote -Daddurl=http://localhost:8080/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/test/SimpleStockQuoteService -Dmode=fullquote -Dsymbol=MSFT
   Buildfile: build.xml
   init:
   compile:
   stockquote:
   [java] Full :: Average price = $159.54100076493154
   BUILD SUCCESSFUL
   Total time: 2 seconds

   Figure 1 - Response

Following is a screen shot of the request sent, after executing the command stated in step 6:

Figure 2 : Original request

This request has some properties, that are different from the request that should send to the service. Following table demonstrates these properties:

Table 3 - Values of the properties for a real request and the current request 

Before invoking the SimpleStockQuote service, it is essential to modify the properties mentioned above. How can that be done? Well, the WSO2 ESB and URLRewrite mediator does it for you. These requests are sent through URLRewrite mediator which is added to the "in" sequence of WSO2 ESB. Then URLRewrite mediator changes the properties to their correct values. Then ESB will send the request to the service.

Lets have a quick look at how the URLRewrite mediator changes property values according to the configuration:

<condition property="addurl" operator="Equal" nextoperator="and">http://localhost:8080/soap/SimpleStockQuoteService</condition>
<condition property="trpurl" operator="Equal" nextoperator="and">/test/SimpleStockQuoteService</condition> 
<condition property="SOAPAction" operator="Equal">[a-z][a-z][a-z]:getFullQuote</condition>

There are three conditions. They are checking for addurl (addressing URL), trpurl ( transport URL) and SOAPAction. It is obvious that all these conditions are resulting in boolean true values. (check these values with the values appear in the table, under the column “value  of the current request” ) First two condition elements have “and” as their next operator. So this set of conditions ends up with the following boolean expression, which will result in a boolean true value.

            (true) and (true) and (true)

Then the mediator will apply the changes as stated in the “set” elements.:

<set property="addurl" value="http://127.0.0.1:9000/soap/SimpleStockQuoteService"/>

<set property="trpurl" value="/soap/SimpleStockQuoteService"/>

<set property="SOAPAction" value="urn:getQuote"/>

Now the message properties are set to their proper values, hence the service is invoked successfully.

Different Rule Elements for Different Services

It is not necessary to edit the configuration file for each and every service you are going to consume. You can define a set of rules applicable for different services. Only requirement is to add a condition to each and every rule, which checks for an unique service name.

Conclusion 

We looked at the elements used to configure the URLRewrite mediator and how this mediator can be used with the WSO2 ESB.  Finally, the functionality of this mediator was demonstrated using a SImpleStockQuote service.

References

• WSO2 ESB documentation
• Writing a mediator in WSO2 ESB

Author

Thilina Buddhika, Trainee Software Engineer, WSO2 Inc. buddhikat@wso2.com