Working with Non XML formats in CXF Interceptors
Sunday, July 1st, 2007Most web service frameworks provide some way for you to intercept and work with the raw messages that it receives. In JAX-WS this comes in the form of Handlers. Through these handlers you can either work with the raw protocol message (i.e. the XML DOM) or the logicial message (i.e. the databound objects).
In CXF, this comes in the form of Interceptors. Nearly all CXF functionality is built on interceptors. When a transport receives a message, it does as little work as possible, creates a Message object, and then sends that Message off through an InterceptorChain.
One of the things that I think is unique about CXF’s Interceptor support is its ability to make working with low level I/O streams and non XML formats easy for the developer. I want to explore that momentarily and show how you can easily create a GZip Interceptor.
An Interceptor in it’s rawest form is simply a handleMessage() method. There are some other support methods, but we can focus on just the important stuff by extending AbstractPhaseInterceptor:
public class MyInterceptor extends AbstractInterceptor {
public MyInterceptor() {
super(Phase.USER_STREAM);
}
public void handleMessage(Message message) throws Fault {
System.out.println("Hello World!");
}
}
When an endpoint receives a message, this interceptor will run in the USER_STREAM phase and print out “Hello World.” Now how do we work with the low level InputStream?
InputStream stream = message.getContent(InputStream.class);
GZIPInputStream gzip = new GZIPInputStream(stream);
message.setContent(InputStream.class, gzip);
The CXF Message stores multiple content formats which you can easily access via the “T getContent(Class<T> type)” API. An InputStream is one. XMLStreamReader, List
<Object>, SAAJMessage.class, etc are all other possibilities at well. Its perfectly valid for their to be multiple valid formats at once. For instance, we can have both an XML document and a List of databound objects at late points in the chain.
In the final line of the above example, we can replace the InputStream that was set by the transport with our new GZIPInputStream. Its all pretty simple. So whats the big deal?
Well most web service frameworks (including XFire), only provide an XML document to their message processing engine. In CXF, ALL the binding specific details, including transport level details like recognizing attachments and finding the most appropriate data format, are handled in Interceptors. This ultimately makes the transports much cleaner and more flexible. You don’t need a SOAP specific HTTP transport or a RESTful HTTP specific transport. You just have an HTTP transport and all the protocol details get handled by the Interceptors supplied by the bindings.
It also makes several things possible which weren’t before with XFire. One of these things is working with non-XML data. Another important use case is message routing. Since CXF is just a generic message handling framework, you can route based on some criteria (i.e. SOAP or HTTP headers) and copy the message to its destination without parsing the whole thing.
P.S. CXF 2.0 final is being voted on now… Hopefully we’ll have an announcement soon!