Wednesday, March 11, 2015

Camel CXFRS Improvements

Camel CXFRS is one of the oldest Camel components which was created by Willem Jiang, my former colleague back from IONA Technology days, and maintained by Willem since its early days.

Camel is known to be a very democratic project with respect to supporting all sort of components, and it has many components that can deal with HTTP invocations. CXFRS is indeed just one of them but as you can guess from its name it is dedicated to supporting HTTP endpoints and clients written on top of Apache CXF JAX-RS implementation.

I think that over the years CXFRS has got a bit of the mixed reception from the community,  may be because it was not deemed that ideal for supporting some styles of routing for which other lighter Camel HTTP aware components were good at.

However CXFRS has been used by some developers and it has been significantly improved recently with respect to its usability. I'd like though to touch on the very last few updates which can be of interest.

The main CXFRS feature which appears to be quite confusing initially is that a CXFRS endpoint (Camel Consumer)  does not actually invoke on the provided JAX-RS implementation. This appears to be rather strange but this is what actually helps to integrate CXF JAXRS into Camel. The JAX-RS runtime is only used to prepare all the data according to JAX-RS Service method signatures but not invoke the actual service but make all the data needed available to custom Camel processors which extract these data from Camel exchanges and make some next routing decisions.

The side-effect of it that in some cases once can not actually just take an existing JAX-RS service implementation and plug it into a Camel route. Unless one use a CXFRS Bean component that can route from Jetty endpoints to CXF JAX-RS service implementation. This approach works but requires another Camel (Jetty only) component with an absolute HTTP address and has a few limitations of its own.

So the first improvement is that starting from Camel 2.15.0 one can configure a CXFRS consumer with a 'performInvocation=true' option and it will actually invoke on the service implementation, set a JAX-RS response on the Camel  exchange and will route to the next custom processor as usual, except that in this case the custom processor will have all the input parameters as before but also a response ready - the processors now can customize the response or do whatever else they need to do. It also makes it much simpler to convert the existing CXF Spring/Blueprint JAX-RS declarations  with the service implementations into Camel CXFRS endpoints if needed.

Note that in a default case one typically provides a no-op CXFRS service implementation (recall, CXFRS does not invoke on the service by default, only needs the method signatures/JAX-RS metadata). Providing interfaces only makes it more logical given that the invocation is not done by default, in fact it is possible for URI-only CXFRS consumer style which is rather limited in what it can do. So the other minor improvement is that starting from Camel 2.15.0 one can just prepare a JAX-RS interface and use it with CXFRS Consumer unless a new 'performInvocation' option is set in which case a complete implementation is needed.

The next one is the new "propagateContexts" configuration option. What it does is that it allows CXFRS developers write their custom processors against JAX-RS Context API, i.e, they can extract one of JAX-RS Contexts such as UriInfo, SecurityContext, HttpHeaders as a typed Camel exchange property and work with these contexts to figure out what needs to be done next. This should be a useful option indeed as JAX-RS Context API is very useful indeed.

Finally, a CXF No Annotations Feature is now supported too, CXFRS users can link to a CXF Model document and use it to JAX-RS enable a given Java interface without JAX-RS annotations. In fact, starting from Camel 2.15.0 it is sufficient to have a model-only CXFRS Consumer without a specific JAX-RS service interface or implementation - in this case custom processors will get the same request data as usual, with the model serving as the source binding the request URI to a set of request parameters.

We hope to build upon this latest feature going forward with other descriptions supported, to have a model-only CXFRS consumer more capable.

Enjoy !

No comments: