WSO2 ESB HTTP transport properties tutorial

WSO2 ESB uses the property mediator to change the behavior of the messages flowing through the ESB mediation engine. HTTP transport level properties mentioned below can be used to access and change the http level properties. You can get a general idea about ESB properties from this blog post.

http://soatutorials.blogspot.com/2014/03/wso2-esb-properties-tutorial.html

HTTP Transport properties

POST_TO_URI

This property makes the outgoing URL of the ESB a complete URL. This is important when we talk through a Proxy Server. You can set this property as below.

<property name="POST_TO_URI" scope="axis2" value="true"/>

Here is an example in which we can use this property.

<?xml version="1.0" encoding="UTF-8"?>

<proxy xmlns="http://ws.apache.org/ns/synapse"

       name="SampleProxy"

       transports="https,http"

       statistics="disable"

       trace="disable"

       startOnLoad="true">

   <target>

      <inSequence>

         <log/>

         <property name="POST_TO_URI" value="true" scope="axis2"/>

         <send>

            <endpoint>

               <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>

            </endpoint>

         </send>

      </inSequence>

   </target>

   <description/>

</proxy>

                                

If you do not use the "POST_TO_URI" property, then ESB will send the POST request as below.

POST /services/SimpleStockQuoteService HTTP/1.1

With the above property set, the request change like below.

POST http://localhost:9000/services/SimpleStockQuoteService HTTP/1.1

This property can be used in a scenario where WSO2 ESB is in front of a HTTP proxy server. Then ESB needs to send the request to the full URL.

FORCE_SC_ACCEPTED

When set to true, this property forces a 202 HTTP response to the client so that it stops waiting for a response. You can set this property as below.

<property name="FORCE_SC_ACCEPTED" scope="axis2" value="true"/>

This property can be used in scenarios where client send a message to the ESB and ESB will store the message in a persistent store like a message store. In this scenario, client will wait until the timeout if ESB do not send any response. In this kind of scenario, we can use this property and send a 202 Accepted response to the client. Here is an example configuration where ESB store a message in a message store.

   <sequence name="main">

      <in>

         <log level="full" />

         <property name="FORCE_SC_ACCEPTED" value="true" scope="axis2" />

         <store messageStore="MyStore"/>

      </in>

      <description>The main sequence for the message mediation</description>

   </sequence>

   <messageStore name="MyStore" />

DISABLE_CHUNKING

Disables the HTTP chunking for outgoing messaging. HTTP chunking is a method of transfer encoding which introduces with http 1.1 specification. This encoding method has a number of advantages over the older transfer mechanisms. One of the advantage is that you do not need to know the content length of the message before you send the message. You send the messages as chunks and when the message is finished, it will send a specific empty message to mark the end of the message. But some of the applications may not understand the chunked message. In that kind of scenario, you need to set this property to true like below.

<property name="DISABLE_CHUNKING" value="true" scope="axis2"/>

If the calling BE is expecting the Content-Length of the message, you need to set the below properties as well.

<property name="FORCE_HTTP_CONTENT_LENGTH" scope="axis2" value="true"></property>  

<property name="COPY_CONTENT_LENGTH_FROM_INCOMING" scope="axis2" value="true">

You can refer the below link for more information about chunked encoding.

http://en.wikipedia.org/wiki/Chunked_transfer_encoding

NO_ENTITY_BODY

This property is used to specify the availability of a content body in a HTTP request. In case of GET and DELETE requests this property is set to true. This property should be removed if a user want to generate a response from the ESB to a request without an entity body, for example, GET request. You can set this property as below.

<property name="NO_ENTITY_BODY" action="remove" scope="axis2"/>

Here is an example where you can use this property in a REST API defined in ESB.

<api xmlns="http://ws.apache.org/ns/synapse" name="SampleAPI" context="/sample">

   <resource methods="GET">

      <inSequence>

         <property name="NO_ENTITY_BODY" scope="axis2" action="remove"></property>

         <payloadFactory media-type="xml">

            <format>

               <m:result xmlns:m="http://samples.org">true</m:result>

            </format>

            <args></args>

         </payloadFactory>

         <respond></respond>

      </inSequence>

   </resource>

</api>

You will get the response as below.

<m:result xmlns:m="http://samples.org">true</m:result>

REST_URL_POSTFIX

In the case of GET requests through an address endpoint, this contains the query string. The value of this property will be appended to the target URL when sending messages out in a RESTful manner through an address endpoint. This is useful when you need to append a context to the target URL in case of RESTful invocations. If you are using an HTTP endpoint instead of an address endpoint, specify variables in the format of "uri.var.*" instead of using this property. You can set this property as below.

<property name="REST_URL_POSTFIX" value="/context" scope="axis2"/>

In the example given below, this property is used to append the customer id to the http url.

 <proxy name="CustomerServiceProxy"

          transports="http https"

          startOnLoad="true">

      <target>

         <inSequence>

            <filter xpath="//getCustomer">

               <property name="REST_URL_POSTFIX"

                         expression="//getCustomer/id"

                         scope="axis2"

                         type="STRING"/>

               <property name="HTTP_METHOD" value="GET" scope="axis2" type="STRING"/>

            </filter>

            <header name="Accept" scope="transport" value="application/xml"/>

            <send>

               <endpoint>

                  <address uri="http://localhost:9764/jaxrs_basic/services/customers/customerservice/customers"

                           format="pox"/>

               </endpoint>

            </send>

         </inSequence>

         <outSequence>

            <send/>

         </outSequence>

      </target>

   </proxy>

In the above example, actual request from the ESB will go to the below url

http://localhost:9764/jaxrs_basic/services/customers/customerservice/customers/1234

where 1234 is the customer id.

There might be situations, that you would need to do REST calls using the send mediator of WSO2 ESB. Then, you might have noticed the endpoint url that you specified in the endpoint configuration, gets suffixed by a url fragment.

This happens when ever you do a REST call using the send mediator. In order to get rid of it, please specify the following property before the send mediator.

<property name="REST_URL_POSTFIX" scope="axis2" action="remove"/>