CXF Transform Feature and Redirection

The Transform feature is proving to be useful to CXF users, given that dynamically changing or dropping the incoming or outbound namespace(s) as well as updating the element names is often required when the changes have not been propagated across or are not even possible. The fact that all the modifications are done at the STAX level is critical as far as the performance is concerned.

The feature has been enhanced recently thanks to Aki Yoshida. The incoming payloads can get new elements added in a number of ways which can be very useful when the services validating the data using the close content schemas are in operation. Multiple updates (example, adding some elements, dropping another one, changing the name and or namespace of yet another one - all on the same payload) are better supported too.

There will be more enhancements coming in in time but I've been actually planning to highlight one of the lesser known tricks which one can use with the Transform feature, something that we demonstrate in our Talend distributions.

Consider the case where you have an endpoint deployed with hundreds or many thousands of clients consuming in. Those could be some long-running clients executing the code, possibly embedded in browsers, and that code is aware of the way this endpoint can be consumed. The time has come to deploy an updated endpoint. The more open the environment is - the fewer options are there to get the clients updated at the same time when the old endpoint goes down and the new one gets deployed.

This is not a new problem per se, but Transform Feature, in combination with the servlet redirection, offers its own simple way to tackle the cost of upgrading all the clients:

Keep the servlet serving the endpoint which is now down around but only have it redirecting all the requests from the old clients to the new servlet serving the new updated endpoint. This will keep the old clients happy for a while and the process of upgrading them can become less 'stressful'.

So now we will have a new endpoint serving the new clients but it will also get the requests redirected to it from the older clients. How will the new endpoint figure out how to handle a given request without resorting to a low-level XML or JSON manipulation ?

Yes, you are right - Transform Feature will help - it will ensure the old requests are recognized by the new endpoint and the responses from this new endpoint are recognized by the old clients still unaware of the fact they are talking to the new endpoint.

Here is how the relevant part of web.xml may look like:

<!-- Old Servlet -->
<servlet>
 <servlet-name>CXFServletV1</servlet-name>
 <display-name>CXFServletV1</display-name>
 <servlet-class>
   org.apache.cxf.transport.servlet.CXFServlet
 </servlet-class>
 <init-param>
  <param-name>redirect-servlet-path</param-name>
  <param-value>/v2</param-value>
 </init-param>
</servlet>

<!-- New Servlet -->
<servlet>
 <servlet-name>CXFServletV2</servlet-name>
 <display-name>CXFServletV2</display-name>
 <servlet-class>
   org.apache.cxf.transport.servlet.CXFServlet
 </servlet-class>
</servlet>

<servlet-mapping>
 <servlet-name>CXFServletV1</servlet-name>
 <url-pattern>/v1/*</url-pattern>
</servlet-mapping>

<servlet-mapping>
 <servlet-name>CXFServletV2</servlet-name>
 <url-pattern>/v2/*</url-pattern>
</servlet-mapping>

CXFServletV1 will redirect all the requests to the servlet listening on /v2 which is CXFServletV2.

Next we configure the Transform feature like this:

 
<bean id="transform" 
 class="org.apache.cxf.feature.StaxTransformFeature">
 <property name="contextPropertyName" 
              value="http.service.redirection"/>
 <!-- the rest of the feature config -->     
</bean>

The feature is configured to do the transformations only if a boolean property identified by the "contextPropertyName" is set on the current message. In this case, if the request has been redirected then the message will have an "http.service.redirection" set to true. It won't be the case for the requests coming from the new clients and thus the feature won't affect them.