Musings about web services

OAuth without the end user explained

2012-01-30T09:13:00.000-08:00

One is the most confusing things in OAuth is a so-called 2-leg OAuth flow where an explicit authorization step involving the end user pressing an Allow or Deny button is not taken.

There are many resources on the web explaining what is an OAuth 2-leg flow. Most of those explanations are effectively describing the process where the 3rd party consumer accesses its own space on the resource server, possibly with the end user itself 'hiding' behind such a consumer.

But the classical OAuth is about the 3rd party consumer being able to access one way or another the resources of the end user. How does a 2-leg flow gets into the picture ?

Please read this blog entry. This is the best explanation I've seen so far and it was so good I had to stop doing my current task immediately and quickly update the CXF OAuth 1.0 code to be able to handle all the variations of the 2-leg flows better.

I think this 'pure' 2-leg flow described by Andrew is really close to a client credentials flow in OAuth 2.0. Without a pre-authorized access token (authorization code) the options are limited for a 2-leg flow.

Please see the updated documentation for more information on how CXF supports OAuth and its 2-leg flows in particular.

Make your Application Server CXF JAX-RS friendly

2012-01-26T04:06:00.000-08:00

Now and then I'm seeing users reporting issues on the forums to do with deploying web applications with CXF JAX-RS libraries into some of the popular Java EE application servers.

So I thought, while investigating a problem reported on the CXF users list to do with using a CXF Redirection feature in WebLogic, that it was also worth giving it a try and experimenting with deploying a complete OAuth demo web application packaged as a war archive that we are working upon into several popular application servers.

Initially I focused on testing Glassfish, JBoss and WebLogic and you can see the notes on how to overcome various deployment issues here.

It was a rather interesting exercise and I had few observations at a time.

WebLogic was the simplest to work with, as far as deploying the application was concerned without having to tweak anything at the container level. The management console of WebLogic is quite sophisticated and seems like this application server is still very capable. I only had to tweak the servlet configuration to get a CXFServlet using a wildcard URI pattern redirecting to WebLogic specific JSP engine properly as advised by the user who reported the issue.

Glassfish is OSGI-enabled and it was interesting to see Apache Felix serving as the default OSGI framework, which is a good news for the OSGI community at large, as it should drive the fixes back to this Apache project.

I had hard time though getting past the Jersey filter trying to deal with this application - it was failing eventually due to it not able to inject a CXF-specific JAX-RS Context instance. I only managed to get it work after removing one of Jersey jars from the available libs - one would only have to do it or may be something simpler :-) if the war has JAX-RS Application implementations and the OAuth demo has 5.

JBoss 7 was easy enough to deploy to. RestEasy also tries to load Applications but it was much easier to deal with it in JBoss. As a side note I thought the way JBoss 7 managed to move away from having to dump all the libs into common folders was very impressive. It is somewhat similar to the Apache Karaf's features mechanism, with Karaf having the repository of libraries and features linking those libraries together. In JBoss the repository itself has some additional metadata.

One thing I thought about after finishing this exercise was that the fact that the deployed applications are eagerly scanned for JAX-RS interfaces exposes a possible issue with these scanners. And the issue is that these scanners need to check if a deployed war contains a /META-INF/services/javax.ws.rs.ext.RuntimeDelegate resource or not and if it points to some alternative implementation then just leave this web application alone.

It would make it simpler not only for CXF JAX-RS users who may want to work with Glassfish or JBoss but for Jersey and RestEasy users too who may want to try the containers where either of this popular implementations is not natively supported. Besides, it would meet the general expectation that a self-contained war should be deployable to any Java EE container.

In meantime, please consider contributing the tips to this section. The tips in the WebLogic section have been provided on the CXF users list, so please keep them coming.

CORS Support in CXF

2012-01-20T02:07:00.000-08:00

Cross-Origin Resource Sharing (CORS) is a W3C specification (Working Draft) which "defines a mechanism to enable client-side cross-origin requests". Please see the Introduction for more information.

We had several users asking questions about how CORS could possibly be supported in CXF. Then at some point of time a mysterious :-) sergkorney offered his help with prototyping an initial code for a CORS filter, and the process moved forward.

Benson took charge and wrote a comprehensive and well-documented filter implementation which follows the specification very closely.

This filter can do the preflight and simple request checks. It interacts with the JAX-RS runtime by relying on its selection algorithm to confirm that an application has a resource method which is capable of dealing with the current request in cases when the filter does not block. If a JAX-RS resource method which can handle the HTTP OPTIONS verb indicates via a dedicated annotation that it will handle the preflight check, then the filter will delegate to it. JAX-RS root resources and individual methods can be customized for them to take part in the CORS process.

It is likely to grow into a more complex security feature in time.

Please review this initial documentation (with the link to the package.html), start experimenting and provide the feedback.

RESTful endpoint in 60 seconds in Talend Open Studio

2012-01-11T05:42:00.000-08:00

I briefly mentioned in the end of this post that we are working on the tooling for creating RESTful endpoints in Talend Open Studio for ESB.

I'd like to offer to your attention my first screen-cast available on the Talend Channel. It shows how one create and test a basic HTTP Service endpoint echoing the POST payload back to the client. I timed it all for some fun, so it actually did took me 60 seconds to create a service and about 60 seconds to test it.

Of course one would spend much more time on developing a more involved service but the idea was to give you a glimpse of how easy you can create a RESTful service as well as to point to the flexibility of the tooling as far as wiring the extra components in is concerned.

Future presentations will show how to create more involved services, those supporting multiple HTTP verbs, with more components facilitating the access to the real data.

Please listen to this short presentation, download the Studio and try creating your own HTTP service and also check what it offers with respect to working with SOAP services and Camel routes.

Oh yes, one more thing, if you are into languages and you'd like to hear what an Irish-Belorussian accent is about :-), then please listen indeed to this screen-cast

Enjoy !

Maven archetype for creating CXF JAX-RS applications

2012-01-06T03:42:00.000-08:00

A number of Maven plugins that CXF JAX-RS users could try for generating the initial code they could build upon for creating working applications was close to zero not too long ago, in fact it was actually 0.

Then we added a wadl2java plugin so the numbers started to look better :-).

And now starting from CXF 2.5.1 an archetype plugin for creating Spring-based JAX-RS applications is also available, all thanks to Benson.

Please see this page for more information.
The generated project will get the integration tests running too, so having a simple end-to-end application created and tested in less than a minute is really cool.

Jettison 1.3.1 has been released

2011-12-29T07:48:00.000-08:00

Jettison 1.3.1 has just been released, please the Download page for more information about the latest fixes.

The two updates which would be of interest to CXF users (or those who rely on other stacks that ship the providers wrapping Jettison) are to do with making it possible to create formatted JSON outputs and making sure that the ignorable (empty) text content (reported by JAXB when processing the mixed content data) is blocked. The latter update, among other things, will make the WADL JSON representations look nicer given that they are produced from the wrapped XML payload.

Few other improvements made it into this release too, particularly those JIRAs which had the patches attached to them have been resolved.

I'd like to encourage the Jettison community to continue providing patches and as far as I'm concerned I can say that the patches will be eventually applied and the fixes will make it into the the future Jettison releases.

Happy New Year !

Associating user login names with OAuth Access tokens

2011-12-12T09:25:00.000-08:00

The classical OAuth flow involves the authorized 3rd-party client magically accessing the end user's resources without even specifying a user name or id, for example:

GET /user/calendar

How can the server figure out which resource to return ? The answer is that the request will have an Authorization header with an access token key and in OAuth 1.0 the token needs to get the information about the end user authorizing a given 3rd party consumer associated with it at the authorization time.

With this association in place, the server will have an easy way to get to the name or id of the user used to authorize the client, and the way to do it in soon to be released CXF 2.5.1 is documented here.

I'd like to thank Glen for helping me with getting this enhancement done.

We are continuing working on the demo which will show most of the CXF OAuth support in practice. Please stay tuned to see how you can write secure OAuth applications with CXF :-)

Locator Support For RESTful Services in Talend ESB

2011-12-07T02:26:00.000-08:00

Back in June I blogged about CXF JAX-RS providing a fail-over support for RESTful Java clients and mentioned some relevant work started in Talend.

Things are happening in the Talend land where all the interesting new features in Apache projects that our Coders team is contributing to are taken on board, analyzed and wired in the products real fast. And the newly released Talend ESB 5 brings a Locator support for RESTful endpoints and clients with the client-side Locator feature built on top of the CXF fail-over mechanism. Kudos to the ESB team for implementing it.

If you get a working HTTP-centric code then having such a code not hard-coding the endpoint address of the RESTful server which is part of the large WEB application and seeing it working even after a given server or the HTTP connection to it goes down will be encouraging.

Are you all into writing large RESTful applications end-to-end ? Have problems answering to your friends who like working with SOAP (they are still your friends though :-)) and tell you that with REST it's not possible to write Locator-aware fail-over capable clients ? If the answer to either of those 2 questions is yes then go to a new Talend web site, download Talend ESB v5, get to /examples/talend/tesb/locator-rest and proceed from there.

One thing I should mention is that Talend Open Studio for ESB is also available for download, it builds on top of Talend Data Integration suite and offers a second-to-none UI support for developing web services and routes. If you work with CXF SOAP Web Services or Camel then you probably won't be able to get back to your old UI tools after trying Talend Open Studio for ESB.

And the good news is that we are working on bringing the users a tooling for developing RESTful applications. It is a work in progress but it's happening, stay tuned !

Observations about Maven Central Search URIs

2011-11-23T05:30:00.000-08:00

I was using a Maven Central Search Engine to find a Google GWT artifact. The search engine is very useful, no doubt about it. I then somehow got focused on the actual URI which identifies the specific GWT artifact I was after:

"http://search.maven.org#search|gav|1|g%3A'com.google.gwt'%20AND%20a%3A'gwt'".

I'm using single quotes just to keep the whole URI expression inside double quotes.

That does not seem like a user-friendly URI to me, and I guess it does not have to be, but I'd just like to analyze it a bit more.

I'm not sure what "|gav|1|" is about, but the main expression (encoded), is really this one:

"g%3A'com.google.gwt'%20AND%20a%3A'gwt'" which reads like this: "find resources with a group 'com.google.gwt' and artifact 'gwt'".

Now compare it with this equivalent FIQL expression which CXF will happily help to handle:
"g=='com.google.gwt';a=='gwt'"

thus giving us

"http://search.maven.org?_s=g=='com.google.gwt';a=='gwt'".

This query a bit simplistic but FIQL does start 'scaling' when we want to use composite queries, for example:

"http://search.maven.org?_s=g=='com.google.com';(a=='gwt',a=='gwt-inject');(v=gt=2.0;v=le=3.0)"

which reads "Find all the modules with a given group, with artifact set to 'gwt' or 'gwt-index' and having versions greater than 2.0 but less or equal to 3.0". It's impressive how FIQL can capture so complex queries in a compact way with a URI which humans can understand. FIQL simply rocks and I encourage users to experiment with it more. By the way, check out the client-side FIQL support, can be handy for building FIQL queries inside the HTML forms.

[OT] CXF- Even Better Than The Real Thing

2011-11-23T02:03:00.000-08:00

Listening to U2 for a long time seems to start affecting me, so much that I can't stop 'producing' my own 'mix' (the Title line of this post) of the fantastic U2's "Even Better Than The Real Thing".
Those who follow this blog for a while will notice I'm getting a bit repetitive by mixing 'CXF' with phrases from some songs I've heard, sorry :-). But if you are working with CXF you may probably agree with the title :-). Have Fun.

Complex WADL Processing in CXF

2011-11-22T04:56:00.000-08:00

We have seen a number of JIRA issues opened against a WadlToJava generator since it was added to CXF 2.4.1. Seeing the community experimenting with it was really reassuring and it confirmed there was some genuine interest toward working with WADL. WADL was a really fine effort from Marc Hadley and it does seem to have nearly all it needs to move from a submission to a final recommendation.

One of the major contributions to the CXF WadlToJava code generator came from Christos Fragoulides who did help to push it to the next level by providing a lot of feedback and fixes while working with a more up-to-date WADL document describing Rackspace Cloud Servers API. They have a complex WADL document which utilizes most of the WADL capabilities and it is in such cases where one can start seeing the advantages of being able to get a document and start testing the server in a matter of minutes. By the way, Rackspace, hope we can see a more up-do-date WADL document live soon :-).

Then, when I already thought that our WADL code generator was flying high, came another very good contribution from Lars Weber which should make it possible to get a useful code from WADL descriptions like this one. Now the generator supports local references for all the WADL elements, in addition to external resource references.

Note that the AtomPub example relies on a WADL link element which can be used to identify a portion of the representation. How one can get to a portion of the representation in CXF JAX-RS ? Easy, use an XPathProvider.

So please try the WADL code generator in CXF 2.5.0, stress it more and provide the valuable feedback.

Lets make OAuth go mainstream with CXF JAX-RS

2011-11-10T02:17:00.000-08:00

OAuth 1.0 offers a fairly complex HTTP-centric solution to a classical problem of "how a resource owner (end user) can allow a third-party consumer to access some of the resources this user owns on the resource server".

I recall being quite confused about OAuth and what exactly it was supposed to help with, when starting to look into it about 2 years ago. I guess it was a typical reaction of someone trying to grasp a given technology without having any prior experience in the area. What was the story with that redirection, and then with yet another one, and how all the pieces were supposed to be wired together ? Was it about the authentication or authorization, and where would something like OpenId come in ? I was asking myself those kind of questions.

It takes a bit of time to realize how elegant OAuth actually is. OAuth 1.0 has been supported by major players such as Google, Facebook and many others. Jersey and RestEasy are offering their support. And OAuth 2.0 is going to make a massive impact real soon.

CXF 2.5.0 is joining the OAuth game. And we have tried our best to make it possible for users to write complete, functional, secure OAuth applications the way they write their HelloWorld demos.

Before providing more information, I'd like to thank Lukash Moren for providing a high-quality OAuth 1.0 implementation as part of his GSOC 2009 project, and Bill for asking me to work on OAuth during my brief spell at JBoss - it all kind of happened at the same time...

Now, please review this documentation providing a comprehensive overview of what it takes to create and deploy an OAuth server, with a lot of examples and hints on various approaches one may need to choose from when building a complete OAuth solution.

Much depends on how the resource server manages the user resources and provides an access the the end users and third-party consumers. Many options are available but the message we'd like to send is that you don't need to create a WEB application similar to those provided by Google or Facebook or Twitter in order to get working with OAuth. CXF JAX-RS provides the ingredients one may need to apply OAuth to all sort of problems requiring the end user authorizing a 3rd party access. Obviously we will be improving what is already there as time goes by.

So lets make OAuth go mainstream with CXF JAX-RS, start building OAuth applications and enjoy it all the way.

SAML Claims-Based Authorization for JAX-RS endpoints

2011-11-09T03:20:00.000-08:00

SAML has been around for a while and is used in real-world applications. CXF WS-Security framework is already offering a second-to-none support for SAML, especially with the introduction of the CXF's own STS, please check Colm's and Oliver's blogs and have some exciting read if you work with WS. Actually, STS can become quite important even for the advanced RESTful security - so follow those blogs even you don't work with WS :-).

The good thing about SAML is that SAML-based solutions do not have to be WS-* based only. SAML is an extensible and rich language and all sort of SAML profiles can be utilized for RESTful applications too. Arguably SAML is complex but the fact it's being used around is critical.

CXF JAX-RS is 'keen' to help users start working with SAML. CXF 2.5.0 offers an initial support for including SAML assertions in the HTTP request payloads and using them to enforce the Claims-Based or legacy Role-Based Access Control rules on the deployed JAX-RS endpoints.

One can get a SAML Assertion posted to the server inside a wrapper XML element which will include the actual application payload such as Book and the assertion itself, with the complete envelope being signed only or with both the application payload and the assertion itself being signed individually. All of it is done by registering a couple of client and server side handlers which will transparently add an envelope, signatures and then validate it all on the server side with the application payload (Book) becoming a root XML node in the end, ready to be processed by the JAX-RS runtime.

With REST we do not always post the XML data so what you can also do is easily add an optionally deflated and then base64-encoded assertion either to the Authorization header or a form field. Such encoded values might also be signed - something we may support in due time.

Having a SAML assertion available as part of the application payload raises a question as to what can actually be done with it. SAML is often used to provide SSO solutions for RESTful services, but we are not there yet, so the best thing that we could come up with at this initial stage is to let JAX-RS users utilize SAML claims in order to enforce the access control rules.

SAML claims are much richer than those which can be asserted with the RBAC rules. However @RolesAllowed and friends are still used a lot and probably will be so it was important to make sure that the legacy rules can work with SAML assertions having claims which are actually representing roles and also offer the way to assert much richer rules which are possible with SAML claims.

Have a look please at this sample code fragment and the follow-up comments. One have a lot of flexibility in the way the claim-based rules can be expressed and also complement the existing RBAC rules without even modifying the code which can also be important.

Before such rules can be enforced, the assertion needs to be validated. The SAML handler will do its own validation, and if you have STS deployed them you may actually want to delegate to it to do some validation too (recall the advice at the start of this post :-)). See also how you can setup an STS client.

The question which has not been seriously addressed yet is how one will create SAML assertions in the first place. At this stage one can start experimenting with using a callback approach and I think we can offer a support for utilizing a WS STSClient on the client side for getting the assertions and transparently adding them to the payload easily enough - please note, the fact that STSClient is a WS client is the least important fact here, it's a perfect mediator between the client code and STS and it does not matter if a SAML assertion which will make it into a non-SOAP payload was actually fetched using a SOAP client.

Note that supporting other interesting SAML-based solutions is of interest to us, that involves the possibility of supporting a WEB Browser SSO profile, etc.

In meantime, please write your simple SAML callback implementation which will generate SAML assertions and start stressing your endpoints secured by claim-based rules, or even invent a new SAML profile along the way :-)

Stay tuned !

Simple XML Security with CXF JAX-RS

2011-11-07T02:50:00.000-08:00

Enhancing the security support for JAX-RS services was a major theme during the CXF 2.5.0 development. CXF already offers a good support for users to create secure RESTful services relying on HTTPS and it also offers a number of useful utility classes for enforcing the authentication and authorization rules.

But the security can be a much richer subject, it is indeed and it is the right time now for us to start working on the advanced security features for CXF JAX-RS users to start experimenting and working with the message level security, tapping into the richness of SAML, deploying OAuth solutions. And we will be analyzing and providing a support for the most interesting and useful security features which are already being or will be used by the community.

As far as the message level security is concerned, XML Signature and XML Encryption are the two prominent W3C specifications which have been used as the basis for providing the message integrity and confidentiality without relying on HTTPS mainly for SOAP XML services, with the help of WS-Security related specifications.

In REST, XML is only one of the many formats which can be supported, but XML is still a very major format which is used a lot. Given the popularity of XML and also to simplify the integration with SOAP-based solutions, it does make sense to get the message-level security supported well for XML services and get to supporting other relevant efforts allowing to sign all sort of payloads next.

And this is what we did in CXF 2.5.0. We put a lot of effort in providing a solution that will make working with XML Security a child's play yet practical and able to deliver for users relying on JAX-RS.

XML Signature and XML Encryption are complex specifications but I hope you can agree after reading this section that working with these specifications and making them protect the messages can be interesting, simple and a real fun.

Note that all what is needed to get an XML signature applied to a given application payload is to register a single handler on client and server sides. By default, a signature will be enveloped as a last child inside a given XML instance such as Book. On the server side, the signature will be validated, removed from the payload and made available on the current Message for other handlers to use it if needed, for example, for optional SAML handlers be able to verify SubjectConfirmation methods such as "sender-vouches".

After the payload has become 'free' of its enclosed signature, it's wrapped in a useful CXF DOM-aware STAX reader and passed along to the JAX-RS runtime.

Making CXF JAX-RS produce enveloping or detached signatures is as easy as setting a signature style property on a client-side handler with the server side one capable of reading all types of signatures.

And now that we have a signed payload, isn't it tempting to get it encrypted too ? So here you go, all you need to get a self-contained EncryptedData with an embedded EncryptedKey capturing an encryption key is to register a single handler on client and server sides which will help CXF encrypt a payload (possibly signed) and then decrypt it on the server side.

One thing which is worth noting is that WSS4J is relied upon by this feature - this is an internal implementation detail and should be of no concern to users building advanced secure RESTful services. WSS4J has a lot of useful code and it makes sense at this stage to reuse it under the hood.

Give it a try please and as usual, please help us with the feedback. If you are a security expert - let us know what may need to be improved and if you are not - learn new advanced security concepts with CXF and become the one :-) Enjoy !

Capturing the info about roles with JAASLoginInterceptor

2011-11-04T03:32:00.001-07:00

CXF ships a useful utility JAASLoginInterceptor which greatly simplifies the process of interacting with the JAAS subsystem and creating a current SecurityContext encapsulating the information about a user principal and roles which will be used for making authorization decisions. See this post for some more information.

When working with Apache Karaf, the simple way to get roles distinguished from a user principal is to configure the Karaf JAAS context such that role names start from a prefix such as "role_" and then let JAASLoginInterceptor know about it using a now deprecated "rolePrefix" property.

However when the existing stores containing the info about roles are used this simple technique may not work given that all sort of naming conventions can be used which may not 'managed' by a rolePrefix property. It makes it trickier to capture roles given that in Karaf the classes representing roles and user principals implement only a single Principal marker interface.

So in 2.5.0 what you can do in such cases is to use new roleClassifier and roleClassifierType properties to let JAASLoginInterceptor know how to get to the roles. Please see this section for an example (the updated content will be visible shortly). This enhancement came after the conversation with my Talend colleague Andrei Shakirin.

Additionally, Aki Yoshida enhanced the interceptor to better cope with the containers providing custom callbacks, for example, it will work perfectly with Jetty providing ObjectCallback instead of javax.security.auth.callback.PasswordCallback.

Finally note that SecurityContexts set by JAASLoginInterceptor on the current CXF message implement LoginSecurityContext. This one can be very handy for getting say Spring SecurityContexts populated, for doing the custom authorization based on the list of provided roles and using the underlying Subject returned from the JAAS subsystem as needed.

If you are asking at this stage, hmm, do I really need to continue using the servlet security, then you are most likely on the right track :-)

Enjoy!

Better support for big attachments in CXF 2.5.0

2011-11-01T11:20:00.000-07:00

Dan had a high quality patch from Sam Meder applied just in time before CXF 2.5.0 has been released which is to do with limiting the max size of the incoming attachments - which is a very good improvement indeed. Whether you use WS and MTOM or depend on JAX-RS, a new "org.apache.cxf.io.CachedOutputStream.MaxSize" system property can be your friend, see this page for more info.
And virtually at the same time Dan did another fix for the runtime to cope better with attachments bigger than 2 GB, how about that :-) ?

It's great to see the CXF Runtime core delivering extremely well as far as working with attachments is concerned

All you need to get HTML views is RequestDispatcherProvider

2011-11-01T10:08:00.000-07:00

While working on the new OAuth demo for the soon to be released Talend TSF distro based on Apache CXF 2.5.0 (see Dan's announcement), I relied a lot on RequestDispatcherProvider.

As you know a typical OAuth flow may involve a lot of interacting with the user and a complete demo should also show the user going to or being redirected to the 3rd party provider site, as well as approving the 3rd party accessing one or more of its private resources.

I was amazed, I really was, how simple and easy it was to get multiple RequestDispatcherProvider instances configured to redirect all sort of responses to JSP views handlers while still being able to return alternative representations such as XML ones.

I highly encourage people to try RequestDispatcherProvider, say goodbye to complex views integrations and never look back.

CXF Transform Feature and Redirection

2011-11-01T04:40:00.000-07:00

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.

Describing JSON Services in WADL

2011-10-02T08:53:00.000-07:00

WADL can describe RESTful XML services really well, by having request and response representations linked to corresponding XML or Relax NG schema element declarations.
However, you've most likely seen the following fragments showing that both XML and JSON representations are supported:


<response>

<representation
   mediaType="application/xml"
   element="ns:Book""/>
<representation
   mediaType="application/json"/>
</response>

The above fragment can describe a method like this one:

@GET
@Produces(
{"application/xml",
 "application/json"})
public Book getBook() {...}

So given the WADL fragment above, the consumer can get an idea of how an XML response will look like, and thus how to consume and possibly validate it. The description of the JSON response representation gives no information at all.

That is not fair I can hear you, JSON fans, saying :-). Or perhaps I can hear people saying WADL is not good enough for describing JSON services. But CXF makes things possible :-), and hopefully the following two recent updates can help:

1. Setting a linkJsonToXmlSchema property on CXF WADLGenerator will result in a fragment like this one be created:


<response>

<representation
   mediaType="application/xml"
   element="ns:Book""/>
<representation
   mediaType="application/json"/>
   element="ns:Book""/>
</response>

Well, describing JSON representation with XML schema is not technically correct, but more often than not an XML schema element instance will give a pretty good idea how a JSON will look like, for example, a Book bean can be used to generate both XML and JSON sequences by the providers in charge.

Update: CXF WadlToJava generator has been updated to handle WADL representation elements with the "application/json" media type which link to XML Schema elements.

2. Setting HTTP Accept header to application/json when requesting WADL will result in a WADL JSON representation returned. For example, given

?_wadl&_type=json

will return a JSON-format WADL instance. Is that really cool ? You bet it is. What about WADL grammar referencing XML schemas, does it really make sense to JSON-format XML schemas ? No it does not, but we have a JSON schema initiative so what you need to do is just configure WADLGenerator to reference a schema like the one describing Products in this section and here you go. For example:

WADLGenerator wg = new WADLGenerator();
wg.setSchemaLocations(
   Collections.singletonList("json.schema"));
// do not create JAXB context
wg.setUseJaxbContextForQnames(false);
// let JSON provider handle it
wg.setIgnoreMessageWriters(false);

The provider can have the above properties set from Spring if needed.
The reference to the json.schema will be replaced with an absolute URI so the consumer handling a WADL JSON representation will be able to GET the referenced schema in the follow-up request.

For the above approach to become of some practical use, the tooling support is important. Consider opening a JIRA in the SoapUI project, vote for it and see what happens :-).

Enjoy !

What happened at Talend R&D summit

2011-07-04T04:12:00.000-07:00

Last week many of us had a chance to attend to a 3 day R&D event organized by Talend in Paris. And what a summit it was.

It was good to meet Dan, JB, Christian, our colleagues from Talend Bonn's office and of course the hosts, people who organized and run the event. The only regret I have I could not play our regular chess game with Hadrian - but I guess we have plenty of time in the future to do it again :-)

I've had a chance to attend to similar events before and I did like it very much, but this last event stands on its own. Talend is still a young company but one can't help being impressed by what this team has already achieved. The tooling is very impressive, be it Talend ESB, core Talend Data Integration or Master Data Management UI suites. They understand what managing data, jobs, processes is about, what good UI is about.

Talend ESB team has had cool demos showing how ESB consumers and producers backed up by Apache CXF can be wired in together, run as live jobs, exported as OSGI bundles, with consumers locating endpoints and users seeing the management statistics. It is really impressive, I thought it was. The new Camel Builder is the tool to explore too - it also supports linking to Talend Jobs with each Job possibly representing a super complex chain on its own.

Talend team works very hard and this team knows how to play hard too :-).

Good to be part of Apache and Talend teams...

WADL First Development in CXF

2011-06-26T14:20:00.000-07:00

The auto-generation of WADL documents has been supported in CXF JAX-RS for a while. Letting users get a WADL instance and use a tool like soapUI to test a live RESTful endpoint is very useful.

Don't get distracted by the fact WADL is not favoured by some REST advocates. Being able to test a live endpoint without spending time on writing a dedicated test code is good.

CXF JAX-RS also offers a CodeGenerator filter which can be configured on test/development/POC servers for possible users being able to download the source code, compile it and start experimenting immediately. Java is just the only option there for now but of course more languages can be supported easily.

That is all fine, but one limitation there is that what is possibly the most important WADL feature, underrated at the moment, is not really utilized. WADL is very resource centric and IMHO it's a perfect language for bridging would-be RESTful application modeling tools with the actual code. I'm not referring to UML-like modeling but a more high level approach with a tool linking entities representing root resources, subresources and data and using WADL as a internal link between a specific tool data representation and a wadl2java code generator. I'm not referring to a complex WADL XML editor here.

All/most of us do Java-first development and it's kind of easy to assume that nobody will need a document-first development. But the document-first approach has its followers as it has its benefits.

CXF is all about choice, options, diversity and letting users get their web services projects done using the strategies preferred in their teams. CXF 2.4.1 offers a server side WADL-first development support - give it a try and enjoy.

Talend joins JCP and JSR-339

2011-06-24T13:46:00.000-07:00

This week Talend has joined Java Community Process (JCP) and JSR-339 (JAX-RS 2.0) Expert Group (EG) with myself acting as the company representative in this EG.

This is a good news for us working on Apache CXF as it's another vote of confidence from Talend in CXF continuing positioning itself as the best-of-breed web services framework for developing WS and REST compliant and robust service endpoints and consumers which just work.

Talend has a history of supporting open source projects and communities. Joining JCP and supporting JAX-RS 2.0 specification is another step in that direction, simply because JAX-RS 2.0 will become important for Apache CXF users building RESTful services.

Another reason is that Talend has a lot of experience in data-integration technologies. Talend tooling is powerful and impressive which will be a subject of another post. REST and data are good matches. Many interesting opportunities will arise for exposing data as RESTful endpoints, letting people search and link to the data of interest. It's natural Talend would like to get involved in JAX-RS 2.0.

See this blog entry for more information.

Failover support for CXF JAX-RS clients

2011-06-16T03:43:00.000-07:00

You may recall all those discussions about "RESTful services can be consumed from browsers by humans only" statements. It was awhile back and of course it's been proven since then that it's possible to write a sophisticated client code consuming RESTful services in a number of ways.

In JAX-RS land, Paul Santoz innovated with introducing the fluent API with all/most JAX-RS stacks having custom implementations, and this API is now being standardized by JSR-339 expert group. Proxy based API is also supported by some stacks.

What is important to realize now is that JAX-RS client runtimes need to become more robust and sophisticated in order to move further, beyond supporting the assertion that "yes, we can do it, we can write the client code for working with RESTful services".

A human working with the browser has more space as far as time and decision making is concerned, when facing a connection failure for example. On the other hand, the code needs to be smarter and ready if the expectations that it does not exit immediately after a connection has become slow, broken or a target endpoint has been recycled is to be met.

This is where a failover feature comes in and it's been supported for CXF JAX-WS clients for a long time. Starting from CXF 2.4.1 it's also the case for CXF JAX-RS clients.

Please check this page for more info, experiment and provide the feedback.

It also confirms that in CXF we are committed to bringing the best support for developing SOAP and REST services. SOAP and REST developers have their 'differences' :-) but we understand them, bring both 'camps' together, and do our best to support them at the framework level.

As a side note, if you think about it, making clients failover-capable is a cheap way toward ensuring something close to 24-7 up time. If you are Amazon or BBC then you have all the hardware and experience in place to ensure the clients nearly never experience a "can't connect" problem. What if you are running an OSGI container hosting service endpoints and need to replace a service ?

Failover-enabling clients is a simple way toward making service endpoints replaceable without affecting the critical client code being executed somewhere. Configuring a CXF failover feature with a small timeout between retries will do the trick really well.

One thing which is really exciting for me is that my Talend colleagues are already working on providing enterprise-level failover-like features for CXF JAX-RS clients and I'm going to talk about it in one of the future posts.

If you have already integrated CXF JAX-RS in your higher-level product then I'd encourage you to follow Talend's lead.

Learn about major Apache projects with Talend

2011-06-06T08:09:00.000-07:00

Talend Application Integration Division team is working on organizing 1 or 2 day courses designed to provide developers with free, hands-on training on Apache CXF, Apache Karaf, Apache Camel and Apache ActiveMQ projects.

Talend will organize the training days in locations where a reasonable number of people can attend.

Please take this 5 min survey and start looking forward to meeting Talend in your local area :)

How to use Camel transport with CXF JAX-RS endpoints

2011-05-10T04:07:00.000-07:00

The following configuration shows how to have HTTP or JMS messages forwarded to
CXF JAX-RS endpoints in Camel:


<beans>
<jaxrs:server address="camel://direct:bookStore"
  serviceClass="service.BookStoreImpl"/>

<camelContext xmlns="http://camel.apache.org/schema/spring">
    
 <!-- JMS to CXF JAX-RS -->
 <route>
  <from uri="jms://test.bookStore"/>
  <to uri="direct:bookStore"/>
 </route>
        
 <!--  Jetty to CXF JAX-RS -->
 <route>
  <from 
uri="jetty:http://0.0.0.0:9002/bookstore?matchOnUriPrefix=true"/>
  <to uri="direct:bookStore"/>
 </route>
</camelContext>
</beans>

Note that you need to use "camel://direct:bookStore" as the address of the jaxrs endpoint and then use "direct:bookStore" in route definitions.

The above configuration will only work with the current CXF trunk and 2.3.x branch snapshots.
The address like "camel://direct:bookStore" is confusing CXF JAX-RS a bit in 2.3.4/2.4.0 and earlier.

However a workaround is available for earlier versions. Christian wrote a couple of Talend Integration Factory demos showing the workaround in action. It is just a matter of adding a simple handler into routes which will make sure CXF JAX-RS is capable of matching requests forwarded to "camel://direct:bookStore".

That said, I'd encourage those who are interested to check Christian's demos anyway, for example, the jaxrs-http-jms demo also shows how to build a Camel route which gets the response from the jaxrs endpoint and converts it using a JAXB converter and pushes it further to the JMS queue.

CXF JAX-RS: Moving ahead with WS-Trust integration

2011-04-29T09:30:00.000-07:00

Making sure existing WS-Trust STS services can be used to enforce the security of deployed web services is of high importance to customers who have invested into WS-Trust based security solutions. It's just a common sense for them.

CXF provides some very advanced support for securing communications between JAX-WS consumers and providers and delegating to STS for validating the security tokens. CXF JAX-RS endpoints rely on HTTPS. That is as far as it can get at the moment. That is sufficient in many cases but the fundamental issue is that customers who want to use STS can not depend on it for additionally securing JAX-RS endpoints.

Now, I've seen people talking about RESTifying STS services, i.e, making sure plain HTTP consumers can talk to it. That is probably a worthy idea as it is likely will make it easier to communicate with STS. It does not solve the issue of using STS for validating all sort of security tokens (SAML assertions, etc) though.

But the thing is that in CXF we have a very good integration between JAX-WS and JAX-RS frontends.
Reusing JAX-WS and WS-Security runtimes for talking to STS is the fastest and most effective way to ensure JAX-RS endpoints can also be protected with STS.

Right now, we've done a very small step forward, we can get Basic Authentication credentials validated by STS, see this section for more info.

More work will have to be done for supporting SAML assertions passed via HTTPS or as part of XML security protected payloads.

OAuth and OpenId are also there. CAS is there. Other efforts are under way. These are of interest to us. We have a brilliant OAuth contribution from Łukasz Moreń in the CXF sandbox. But at this stage the integration with WS-Trust/STS is of high priority.

Stay tuned!

Transform Feature demonstrated in Talend Service Factory 2.4.0

2011-04-28T05:25:00.000-07:00

Talend Service Factory 2.4.0 has several new advanced demos shipped as part of the examples distribution.

Please check Glen's blog for the information about WS-Trust and WS-SecurityPolicy demos.

Here I would like to describe a "jaxrs-jaxws-transformations" demo which shows the new Transform Feature at its best.

Many options for enhancing the existing XML schemas are possible. Usually, a namespace gets changed to indicate a breaking change to do with reordering elements, changing their names or structure or introducing new elements into a type with a closed schema content. Things are more complicated in the real world where best practices can require namespace changes for all updates made to a given schema.

The demo 'works' with the case where a Customer type has had a new optional property added to it. In addition, the namespace has also been modified, even though we are not dealing with the breaking update here.

The demo shows how:

* old and new JAX-RS clients can talk to existing (old) and new JAX-RS endpoints respectively - usual case
* old and new JAX-WS clients can talk to existing (old) and new JAX-WS endpoints respectively - usual case

Next, it shows how:

* new JAX-RS clients can talk to old JAX-RS endpoints
* new JAX-WS clients can talk to old JAX-WS endpoints

and

* old JAX-RS clients can talk to new JAX-RS endpoints
* old JAX-WS clients can talk to new JAX-WS endpoints

In this latter case, with old clients talking to new endpoints, two assumptions are made. First one is that the old clients know they are talking to new endpoints and thus Transform Feature affecting outgoing and incoming payloads is applied on the client side. Second one is that clients do not know that new endpoints will be used to handle their requests - the server side redirection and Transform Feature are used in tandem to make it work.

Finally, XMLSource is also shown in action on the client side.

This is a fairly involved demo trying to show how backward and forward compatibility may get achieved.

Try this demo and see if you can find it useful for the work you do in the real world.

Enjoy !

Building FIQL queries in CXF

2011-04-19T07:23:00.000-07:00

Building FIQL queries is not a difficult process. Typical queries are simple enough to build them manually, for example:

_s=id=le=123

More complex queries relying on 'and' or 'or' conditions (possibly composed with each other) and multiple operators are a bit more tedious and complex to build.

CXF 2.4.0 introduces a SearchConditionBuilder utility class (thanks to Andy Michalec) which can be used to simplify building FIQL queries and working with CXF JAX-RS endpoints already supporting FIQL queries.

Have a look please at this section, try SearchConditionBuilder and provide the feedback.

Transforming XML in CXF

2011-04-14T08:41:00.000-07:00

Working with XML based web services does not only involve having a proxy or HTTP client invoking on the remote endpoint with the underlying data-binding magically populating a given bean instance with the values contained in XML tags.

Working with XML also implies that some care has to be taken for all those clients distributed all over the enterprise and the WEB at large be able to consume the existing and newer endpoints.

If you have a newer endpoint deployed that can handle the payloads from the older clients then the backward compatibility is maintained. If the validation is enabled then this is usually achieved by adding optional elements to the updated schema.

What happens if you have so many endpoints that they have to be gradually replaced by newer ones, should newer clients be blocked from consuming the old endpoints ? Is it really needed if all the new payloads add is some ignorable content that makes the information about a given concept more complete for newer endpoints ? Is it even realistic as in the case of the WEB ? Is telling such clients 'wait, the endpoint is being upgraded' is the cheapest/simplest option ?

This is where the forward compatibility comes in and it implies that the unrecognized content has to be ignored. Disabling the validation is not always safe as the newer clients providing new content can expect that that new content has been processed into account as opposed to being ignored. Validation will prevent the important unrecognized tags from being dropped. But it also will prevent the forward compatibility altogether.

The new CXF Transform Feature has been introduced and hopefully it will help users with resolving all sorts of backward and forward compatibility issues. CXF JAX-WS and JAX-RS endpoints and clients can be configured for namespaces be dropped or changed, elements dropped, changed or appended to existing elements. This is all realized at the STAX XMLStreamReader and XMLStreamWriter levels so it is fast and effective.

Does your web service need to talk to the legacy server which does not understand what namespaces are ? Do you need to consume a response from the newer endpoint which has a new namespace introduced ? Do you need certain elements ignored or dropped on the input/output ?

Use the transformation feature, get inspired and write the services which just work and don't cause all the clients be recompiled/updated whenever a minor change to the new endpoint has been applied. Have the web service clients talking to a variety of endpoints without changing the code.

The use of the transform feature in combination with the servlet-based redirection allows for replacing the old endpoints with the new ones and redirecting the requests from the old clients to the new endpoints. Which is quite cool. See this web.xml (CXFServletV1 redirects to CXFServletV2, effectively changing final URI path from /v1/rest-transform to /v2/rest-transform), with CXFServletV2 serving a jaxrs:endpoint with the "restTransform" id, the last jaxrs endpoint in this beans.xml. Note this endpoint relies on the transform feature which drops the namespaces from the inbound payloads and changes the name of the outbound element, only for redirected requests - so that V1 clients can talk to V2 endpoints without V2 clients being affected.

Finally, if you use the default CXF JAX-RS JSONProvider then the transform feature can be applied to input/output JSON sequences too, surely you don't want the JSON clients failing to parse the JSON data if you happen to add one more property to the JAXB bean which is used to produce a JSON sequence :-).

Most of it can also be done by custom CXF interceptors as well, which can register custom STAX handlers or use XSLT or XPath. I've updated the Advanced XML section on the CXF JAX-RS wiki, have a look please.

Jettison 1.3 is released

2011-04-14T08:15:00.001-07:00

As it happens, Dan and Dejan have let me manage the Jettison project from now on. And thus I'm happy to announce that Jettison 1.3 has been released.

Jettison 1.3 has had two patches from CXF users applied.

MappedXMLStreamReader can now read top-level explicit arrays containing qualified and unqualified tags - this allows JAXB to deserialize such JSON sequences into explicit collections (lists, etc). For this to work, the support for older convention assuming a top-level array may only contain a single node had to be dropped. Additionally, simple tags explicitly set to null have no CHARACTER events reported.

I think the good news is that Jettison will keep moving forward. One thing I'd like to clarify is that I won't be actively working with Jettison - however you can definitely expect patches addressing open JIRA issues being applied. Jettison has a small code base, so if you use it and see some issue then just check out the trunk and create a patch.

This latest release has really being driven by lingering issues opened against CXF JAX-RS but you don't have to use CXF for Jettison JIRAs be fixed - if you like working with Jettison then providing a patch is the only thing you need to do for the given issue be addressed :-)

Advanced Integration with the Talend Integration Factory

2011-02-21T06:56:00.001-08:00

Talend Integration Factory, the Community Edition, has been released recently and is available for the download. Additionally, the Advanced Examples distribution can be downloaded from here.

The Talend Integration Factory (TIF) is an advanced platform for building real-world application integration solutions. It is centered around the powerful Apache Camel integration engine.

What I'm finding interesting about this solution is that the people involved into building it have the in-depth knowledge about what it takes to build the integration solutions which work and scale really well. Their optimism and the number of their ideas is boundless, and this solution will grow and deliver the real value for the customers.

Give the examples a try - the team is planning to bring you some really interesting and advanced examples in time, please see Christian's blog entry for more information.

JAX-RS Attachments demo in TSF 2.3.2

2011-02-01T13:29:00.000-08:00

The Talend SF 2.3.2.0 distribution contains various minor improvements and has some dependencies, including the Karaf one, updated to new versions.

The Talend SF 2.3.2.0 Examples distribution contains a new jaxrs_attachments demo.

CXF JAX-RS offers a comprehensive support for reading and writing attachments and this demo tries to demonstrate it by showing how XOP and regular multiparts can easily be dealt with.

We are going to build upon it when we move on to doing the more advanced development with the proper support for multiparts being required.

Have a look at this demo if you're interested. And expect more interesting demos added soon. Stay tuned.

Unified Search Experience Made Easy With CXF

2011-01-21T13:09:00.000-08:00

Providing the quality search experience is an important task for any serious web application project.

Most of the HTML forms let users do simple queries resulting in the equality or partial match checks on the server side. For example, "Find the book with the id starting from 123" or "Find all the books with the author's first name starting from Fred".

Imagine the following task. Provide a web interface which will let users search for all the books which have an id greater than 123. Or find the list if customers which paid less than 200 dollars.

What I've observed quite a few times is that when multiple services are built by individual teams within the same large organization or as part of single large project then every team will create its own query language.

One team will come with a custom query language built within this very team. And the other team working on some other service will build a slightly different variation of the custom query language.

The end result is that the users may need to learn two query languages, one in order to query the 1st service and the other one - in order to query the 2nd one.

Sometimes different teams will agree on using the same query language.

Using explicit SQL expressions is one option. Most likely a frontend UI tool will collect the user input and convert it into SQL and then pass it to the remote service. IMHO the use of SQL as a query language on the WEB should be discouraged for the obvious reasons: the fact the the end service uses an SQL database for storing the data is the very last thing the consumer should know about, just too much information is being leaked for this to work.

The use of XQuery or query languages created by Google Data and Microsoft teams is an entirely different approach. It does let developers provide a unified search experience to the users. For example, all the Google Data services have to support the same query language - something that users can appreciate.

As I mentioned in this post, CXF JAX-RS supports converting FIQL expressions into SearchCondition expressions which capture the FIQL queries and let users match them against the application data.

FIQL is indeed a simple language - please read this post from Arul for a nice introduction to FIQL. IMHO it does offer a viable alternative to more complex and advanced query languages and we'd like to continue enhancing the CXF search extensions for users be able to get the best out of FIQL.

The CXF SearchCondition interface offers a utility method for converting the FIQL queries to SQL expressions. This method (toSQL()) has been deprecated recently. While the users who find this method working for them may continue using it for a while, it is now recommended to use the SearchCondition visitors, thanks to Brian Topping for providing a patch.

It were possible to convert SearchCondition into more optimized SQL or non-SQL expressions even before the introduction of visitors but now the relevant code has become much cleaner. The SQLPrinterVisitor is shipped with CXF and it can be used to convert the queries to SQL, using the proper SQL aliases if needed. For example, imagine a query such as "a==b". The 'a' may easily be assumed to be the name of the column in some table - but we may not necessarily want the end users to 'hard code' the names of the columns in the queries; thus the SQL visitor lets the service developers to register an alias map, for the resulting query to contain say "A_Column" instead of 'a'.

I can imagine XQuery-aware and other visitors being added in time. In fact the way we are trying to build the search extensions is to make sure other query languages such as XQuery/etc are supported transparently. If users will start asking about supporting the new query language then we'll just provide the relevant SearchContext parser and SearchCondition visitor.

One immediate enhancement we are thinking of is to add a SearchQueryBuilder which users would use to build FIQL/etc queries using simple Java operations and pass the builder result to WebClients or proxies.

So imagine all the different web services within the same organization supporting the same simple URI friendly query language which is easy to understand and use. One thing you can be sure of is that the end users will appreciate it, especially when they start building their own client applications which need to query a number of those web services.

By the way, it should work nicely for CXF JAX-WS services too provided they've been JAX-RS-enabled.

JAX-WS and JAX-RS United in CXF

2011-01-09T11:38:00.000-08:00

I've just reread the REST and SOAP United blog entry I did back in July 2008, more than 2 years ago.

This theme is as active as ever in CXF; as I've mentioned on this blog quite a few times we've been trying to provide the environment for SOAP developers to experiment with JAX-RS with as few changes as possible and indeed, quite a few CXF SOAP developers do use JAX-RS today while continuing running their SOAP services. Some developers are choosing to annotate the same service interface or implementation class with both JAX-WS and JAX-RS annotations, while some of those, preferring to do the WSDL-first approach, have tried to apply an external CXF JAX-RS user model, something that is demonstrated now in one of the Talend SF demos, and thus avoiding having to modify the (generated) code altogether.

There have been some new improvements recently in the integration between JAX-WS and JAX-RS runtimes.

First, many of the custom CXF annotations are now supported by the JAX-RS frontend. So one can easily do a combined JAX-WS and JAX-RS service which for example supports a FastInfoset feature by using CXF FastInfoset, Feature or In/OutInterceptors annotations, possibly also relying on say a DataBinding annotation enabling the CXF SDO DataBinding.

It was possible to wrap CXF DataBindings as JAX-RS MessageBodyReaders and MessageBodyWriters for a while, with XmlBeans being the latest DataBinding supported, thus effectively reusing the same provider instance between JAX-WS and JAX-RS endpoints.

But just a couple of weeks ago a CXF user asked about having JAX-RS MessageBodyWriters being used by SOAP JAX-WS endpoints. Does it sound a bit hairy to you :-), irrespectively of whether you are a JAX-WS or JAX-RS developer ?
It might sound so initially but I think it is just the next natural step in the way both frontends can get integrated.

A user who asked a question had developed an optimized XML Stax provider and did not want to rely on JAXB while working with JAX-WS services. So I just went ahead and added a utility JAX-RS DataBinding which can be plugged in into JAX-WS endpoints and which will delegate to custom JAX-RS writers and readers. I used a JAXBElementProvider shipped with the JAX-RS frontend to test this feature. Thus, even though most SOAP developers will unlikely use the feature due to a number of limitations, some of them might go ahead and see if some of the existing JAX-RS XML-aware providers can do something useful for their SOAP applications.

I've just thought about doing SOAP-Atom with Atom payloads being transmitted inside SOAP envelopes and handled by CXF JAX-RS Atom providers. But no, I won't advocate doing the double enveloping (soap:Envelope plus atom:feed) at all even though this feature makes it possible now :-).

Have fun :-)

Authentication and Authorization the CXF Way

2010-12-17T05:16:00.001-08:00

I've been working recently on a number of tests and a demo showing how CXF endpoints can be protected by having consumers relying either on Basic Authentication or WS-Security UsernameTokens authenticated and the authorization rules enforced.

Often enough, when confronted with the problem of making sure the authentication and the authorization works, many users think of using either the J2EE-style authentication (configured via web.xml) or Spring Security.

The former option does not really work with WS-Security and sometimes may not be easy to configure in a fine-grained fashion, besides one may want to defer the role verification until just before the actual invocation occurs. The latter option can let you do it all, given how advanced the Spring Security is. If you're a Spring Security savvy person then wiring it in to secure the endpoints against some arbitrary WS-Security tokens can be a child's play :-) but one have to admit that it might be a bit 'intimidating' sometimes and in some cases Spring is simply not used in a given project. Additionally, making it work in OSGI may present quite a challenge on its own.

The other thing I've heard of is that users dealing with WS-Security may not necessarily want to deal directly with the WSS4J library at the level of their CXF interceptors (by the way, please subscribe to the Colm's blog for more information about WSS4J and other security-related thoughts and updates).

So in the end a number of CXF security interceptors has been introduced to make it as easy as possible for CXF users to secure the endpoints at the authentication and authorization levels.

Additionally, a CXF-specific UsernameToken has been introduced which at the moment encapsulates the information obtained from the WSS4J UsernameToken.
As you can see, it implements the SecurityToken interface with the idea being that more token types will be supported in time. For example, an AbstractSecurityContextInInterceptor converts a token to a CXF SecurityContext instance by delegating to subclasses which know about a current token type, with
AbstractUsernameTokenInterceptor being one such subclass. In the end, say a concrete AbstractUsernameTokenInterceptor implementation only sees CXF UsernameToken which it needs to use somehow for authenticating and populating a current Subject.

The Subject instance will be wrapped in a CXF SecurityContext which will be used later on to do the authorization or further wrapped by JAX-RS or JAX-RS SecurityContext objects and injected into service beans. You may want to use SimplePrincipal and SimpleGroup helpers if needed when creating custom Subjects.

Note that CXF ships two SecurityContext implementations which attempt to figure out which Subject Principals are roles. DefaultSecurityContext assumes Group instances represent primitive or group roles, while RolePrefixSecurityContextImpl find the Principals by checking if their names start from the configurable role prefix, example, from "ROLE_" (this post has some more information).

So far so good - the authentication has been taken care of if you use WS-Security. If you don't them the authentication will occur earlier on at the container entry level, with or without SpringSecurity involved. However, after working on the container-level authentication demo last week it became apparent that CXF needs a utility JAASLoginInterceptor. You only need to tell it the name of the LoginContext to resolve and optionally provide a role prefix name in case Subject does not use Groups to represent the roles. You may also need to override its getCallbackHandler method returning NamePasswordCallbackHandler instances by default, for example, this custom interceptor ensures it can handle Jetty ObjectCallbacks for setting the password.

Another good news is that the JAASLoginInterceptor will work equally well with CXF UsernameTokens (created during WS-Security-related requests) and AuthorizationPolicy capturing Basic or Digest authentication details.

Next we may need to enforce the authorization rules. SimpleAuthorizingInterceptor can be injected with a method names to roles map, while SecureAnnotationsInterceptor takes it one step further and lets users just inject a reference to a secured object and it will figure out how individual methods are supposed to be secured; it checks RolesAllowed annotations by default but one can provide the annotation class name used to specify the roles.
If you have roles stored in say the database then you may want to extend AbstractAuthorizingInterceptor and override its getExpectedRoles method.

If you are securing JAXWS or JAXRS endpoints, you only need to add one or two interceptors, say an optional JAASLoginInterceptor and SimpleAuthorizingInterceptor. When securing JAX-RS endpoints with these interceptors you may also want to add a custom CXF out fault interceptor, for example, like this one, if you want 403 or 401, instead of 500 being returned; alternatively you can let the exception propagate up to the servlet level when possible and deal with the ServletExceptions at the filter levels.

The JAX-RS frontend also ships two utility filters wrapping JAASLoginInterceptor and both authorization interceptors, The one which wraps the JAASLoginInterceptor returns 401 by default and adds a realm name to the WWW-Authenticate response header if needed. It also lets users specify the resource URI where the client needs to be redirected to instead of getting 401. If needed a simple subclass can ensure unrecognized callbacks are dealt with the same way it's done with JAASLoginInterceptor. Here is a sample filter .

Finally, some more information on how to configure the interceptors. Have a look at this beans.xml. The test assumes the authentication is managed by the container, for example, one can configure a Maven Jetty plugin to enforce it. The web.xml requests the authentication only and see how SimpleAuthorizingInterceptor and SecureAnnotationsInterceptor are set up to do the rest - the authorization.

This beans.xml introduces the JAASLoginInterceptor (and the JAX-RS filter) into the picture. I think it would be fare to say it is simple to setup both the JAAS authenticator and the authorization filters in CXF. And guess what - this very configuration can make your application secure without changing a bit in the standalone server, the servlet container and the OSGI container such as Karaf.

The varying part is ensuring the server/container sees the JAAS configuration such as this one (FYI, "BookLogin" is the name injected into JAASLoginInterceptor, while BookLoginModule is wrapping a Jetty PropertyFileLoginModule).

In my test I'm passing a system property "java.auth.security.login.config" to the test server process. In Karaf one needs to deploy a bundle containing the JAAS config. The bottom line is that the issue of bootstrapping the server with this information is an issue of its own.

So what do you do in the end once you set these new CXF interceptors ? You can just relax and see your secure CXF application working like a charm irrespectively of where it is deployed to :-)

Enjoy !

Talend Service Factory Examples

2010-12-17T03:17:00.000-08:00

As Dan has already mentioned, we have created a number of documented examples which have been tuned to run within the OSGI Karaf container shipped as part of the Talend Service Factory release.

The OSGI container in the release is really an optimized OSGI-aware Web Services stack with only the most relevant bundles being loaded. We've also tried to take care of minor issues such as ensuring that the default HTTP port is 8080 and that the HttpService context is set to "/services" by default as opposed to "/cxf". You can set these initial settings in 30 seconds yourself - but don't you want the demos just to work without having to know how to configure pax web and cxf osgi properties from the very start :-) ?

We have some serious plans to make sure CXF plays really well in OSGI - please keep an eye on the CXF dev list. We will want to make sure the CXF services and indeed the consumers just work in OSGI.

Additionally, most of the examples provide options for starting the services from the command line and within the servlet container.

Next I'd like to actually spend a bit of time and describe what examples we ship. What we have now is some classical CXF examples, such as the one demonstrating all sorts of CXF interceptors in action and additionally prepared to run in the OSGI container. The OSGI-fied example demonstrating SOAP over JMS specification is also there.

Finally we have started closing the gap which has existed in the area of JAX-RS demos and we've added 6 new demos.

Two first demos are called jaxrs-intro and jaxrs-advanced with the idea to show the basic JAX-RS features and then progress to a more involved example, not only showing more sophisticated JAX-RS features but also applying them to solving a reasonably interesting problem, traversing the Person family tree in a number of ways and updating individual Persons. These demos will be regularly updated.

The next 2 demos, jaxrs-jaxws-java-first and jaxrs-jaxws-description-first show how SOAP and RESTful services can be combined.
The first one shows how both JAX-WS and JAX-RS annotations can be combined on a single interface, how endpoints can share the same service bean and how both JAX-WS and CXF JAX-RS proxies can effectively use the same code for invoking on the services. The second one shows how SOAP services developed using a WSDL-first approach can be selectively exposed as RESTful services by applying an external CXF-JAXRS user model giving that modifying the interface generated from WSDL is not an option.

What we actually want to show with these 2 demos is that making this experience as seamless as possible is a top priority for us - we do want users to really like developing both SOAP and RESTful services with CXF.

The next demo, jaxrs-jms-http, shows how a typical JAX-RS HTTP server can be enhanced to receive the JMS messages with just adding few extra lines to the configuration. As noted here, you may want to do it if you'd like to preserve your investment in the JAX-RS but also make sure the service is capable of getting the messages from a variety of (transport) channels. This demo also shows how HTTP requests can be processed oneway with the server picking up the messages and forwarding them further to the JMS destination.

The last example is jaxrs-jaxws-authorization. This example shows CXF authentication and authorization interceptors in action, authenticating the users via JAAS and populating the CXF SecurityContext with Principal and its roles, and then enforcing the authorization rules for both JAX-WS and JAX-RS endpoints. The JAAS interceptor is only used when the demo is run within Karaf so that the Karaf JAAS context can be resolved. When the demo is deployed into the servlet container, the container-managed authentication is utilized to populate the current Principal.

This demo will be significantly simplified in the next release due to the recent related CXF enhancements (the topic of the next post).

You'll see many more examples added in time.

So please download the examples and give them a try. Note, you have to register in order to download the examples, this is due to the fact the examples content in general is considered to be a premium content at Talend, hopefully it won't be a problem for those who are interested.

Change the world and go home

2010-12-17T02:38:00.000-08:00

I recall I was reading the Change the world or go home post from Dare Obasanjo and being a bit confused not about the content (which was interesting and thought provoking as usual) but about the 'or' bit in the subject.

I was asking myself, would it make sense to say "Change the world *and* go home" :-) ? I believe all of us working with the Open Source are changing the world every day, then we go home in the end of the day, and then we are back at it the next day, changing the world with our individual contributions, negligible in the scope of the big picture.

Of course, "or" had the meaning in the Dare's post. But I kind of like 'and' more :-)

Sopera opens the development center in Ireland

2010-11-18T02:13:00.000-08:00

Last week myself and my colleague Colm stepped in into an office that Sopera secured for us in Dublin, Ballsbridge. We can nearly see the IONA Building we used to go to not that long ago from our place. The view from its window is really nice.

We are delighted. Being able to get to the office and work with and talk to your colleagues but also work from home on a given day is the ideal situation for software engineers and it really does feel it is the beginning of the new journey for us, with the only way ahead from here - onwards, especially now that Sopera has been acquired by Talend.

CXF Auto Redirect Feature in action

2010-11-15T09:08:00.000-08:00

I was working today on testing some CXF JAX-RS client code against Tomcat and Jetty servers. All was going well with Tomcat : after deploying a sample.war to Tomcat and doing :


WebClient wc = WebClient.create("http://localhost:8080/sample";
wc.getCollection(Book.class);
// print the collection

a collection of Books was printed in the console.

However this code stopped working once I deployed a sample.war to Jetty, using a Maven Jetty plugin. I spent some good few hours debugging it before I spotted that Jetty returns HTTP 302 to a "GET /sample" request with the Location header pointing to "http://localhost:8080/sample/", note the trailing slash.

So changing the code to


WebClient wc = WebClient.create("http://localhost:8080/sample/";
wc.getCollection(Book.class);

made it work for both Tomcat and Jetty deployments. One other option to deal with the redirects is to use one of the WebClient methods returning JAX-RS Response rather than a typed one, and check the status and then follow the new URI if needed.

But I found the following code working nicely in the end :


WebClient wc = WebClient.create("http://localhost:8080/sample";
WebClient.getConfig(wc).getHttpConduit().getClient()
         .setAutoRedirect(true);
wc.getCollection(Book.class);

Being at ApacheCon 2010

2010-11-08T08:48:00.000-08:00

I got a chance to attend to the Apache Conference in Atlanta last week thanks to Sopera organizing this trip. It was the first time I was at the ApacheCon, and it was an interesting and unique experience.

First, Sopera had a workshop during the first 2 days of the week, before the conference started, so it was a good opportunity for many of us in the OS team to meet each other and we had some interesting discussions along the way.

ApacheCon brings together an interesting mix of people, some of them having the commercial interest, some representing large commercial and government organizations adopting OS, and some working on OS projects because this is what they really like doing on their own time.

It was interesting to listen to some technical talks. And meeting new people and seeing the former colleagues I used to work with (with some of them I will be working again from now on :-)) was great. And of course, meeting CXF legends such as Glen and Benson was another highlight :-).

Give us your headaches

2010-10-27T09:24:00.000-07:00

Have I already mentioned that I liked reading the Richard Branson's auto-biography ?

I honestly think it was a gem of a book which I picked up in the Gatwick airport on the way to Dublin from Minsk. That is a story about the life journey told with a lot of humor, filled with some absolutely hilarious accounts of various events and with some very serious thoughts about doing business and contributing to saving the humanity.

You might want to ask, what is it all to do with the web services or software development given this post is not marked with [OT] ?

During his student days, Richard set up the Student Advisory Centre which consulted students on all the issues they could have, free of charge. One of their slogans was "Give us your headaches". This centre still operates today.

I thought, when I was reading about it, that to some extent, this is what the OS business model was partly about. In OS we are working on projects such as CXF and we are determined to make it all work really well, without any headaches, in the most demanding environments.

The OS business model is partially about providing the insurance that customers will experience no headaches when running such OS-driven projects in their productions. In fact this model has been proven very successful, by such top companies such as RedHat for example.

Are you considering to start using CXF but a bit concerned what will happen further down the road with all the OS development going on into it ?

Give us your headaches :-)

CXF : Here we come !

2010-10-27T08:59:00.000-07:00

I'm happy to confirm that after a short break I'm going to have a chance to resume working on CXF and its JAXRS project in particular.

I'll join Dan and the rest of the Sopera OS team and we will be determined as ever to bring you the best production-quality web services framework around.

And with your help we will make the CXF users and dev lists the "hippiest place to be", the phrase is borrowed from a Richard Branson's auto-biography.

CXF won't be the only effort we will focus in Sopera but it is going to be one of the main ones.

Stay tuned.

Goodbye JBoss

2010-10-27T07:57:00.000-07:00

So after less than 6 months after starting to work for JBoss I decided to quit and accept an offer from Sopera. In hindsight, I'm thinking that talking about the career publicly is not always the very best idea - spending such a short period of time at one of the leading company in the industry is not something that will improve my CV.

Back in April/May I was indeed looking forward to that great opportunity and it was not a stop-gap measure by any means. But CXF and CXF JAXRS are calling me back - it is next to impossible to resist. I'll blog about it next but this post is about JBoss and I'd like to talk about it a bit.

Just 6 months ago I had a fairly vague idea about what JBoss were doing, apart from knowing that they were part of RedHat, that it was an application server and that their JBossWS project was providing a CXF JAXWS integration option. And of course I knew about RestEasy.

In the reality, JBoss is a very live, active and progressive project, with a lot of very clever and innovative people working on it and who are really passionate about JBoss. And they have a very open and democratic environment with everyone being able to express their thoughts aloud.

I've promised in my previous post I'd link to various JBoss subprojects. Here are the links to some of them :

JBossWS : Web Service Framework for JBoss AS
RestEasy : JAX-RS implementation with various features
PicketLink : STS, etc
JBossTS : While many are saying that WS transactions support is next to impossible to provide this team just does it
HornetQ : Putting the buzz in messaging

As far as I'm concerned it is obvious I've given away the real opportunity with a great company. That said, the life is about many opportunities, and I'm about to pursue the new and exciting one, with the young and innovative company.

Goodbye JBoss, Hello Sopera !

The New Beginning : JBoss

2010-05-24T09:47:00.000-07:00

Today I've started working for JBoss, the division of RedHat.

This is a truly new beginning for me and I'm looking forward to my new career in JBoss and RedHat. I'll have a chance to work with and learn from a lot of great engineers and contribute to a number of interesting projects.

It is a big new world out there. RedHat Linux, JBoss, ws and restful services, clouds, virtualization, messaging, transactions, osgi, etc... I'm optimistic and hopeful it will be a great ride.

From now on I'll be linking to various RedHat/JBoss related projects, news, etc.

I'll continue working in a web services area. I'll be involved in a JBossWS project. I'll also have a chance to work with RestEasy and possibly contribute to it; it is a powerful JAXRS implementation which has been leading alongside with Jersey and it is also likely to become a home for realizing and implementing a number of pragmatic ideas coming from the Rest-* effort.

I also have a message for those of you who have decided to try or use CXF JAXRS. It is a project I've put a lot of effort into and I'm really keen to continue supporting CXF JAXRS users which is what I'll be doing though the time I'll be able to spend on it will be limited to after-work hours and weekends. I think CXF JAXRS will do well - it's become quite solid with respect to helping CXF users with developing REST-based services. The development effort which will go into it will become quite limited - but I hope it will live.

Stay tuned and have fun !

New Kid On the Block : JBoss OSGI

2010-05-19T06:06:00.000-07:00

I've been reviewing today the JBoss OSGI documentation and I've been really impressed. They can work with existing containers such as Equinox and Felix but can do well on its own too. Check the documentation - it is very well written.

For some of you a 'new kid on the block' may not sound right if you've worked with or heard of JBossOsgi already :-).

It's likely to affect the existing balance on the market of OSGI-aware frameworks. Watch this space.

OT : bbc.co.uk and tut.by

2010-05-11T09:48:00.000-07:00

Time and time again I'm being very impressed by the quality of [bbc.co.uk|http://www.bbc.co.uk/]. It is just possibly the best web site which I've seen. Their "Live Football" section is the best one too :-)

The [tut.by|http://www.tut.by/] (Belorussian news portal) is quite impressive too, not as powerful as the BBC one - but good nonetheless.

Converting FIQL expressions into SQL queries in CXF JAXRS

2010-03-26T10:37:00.000-07:00

I've done some more work on the search extensions so that users can easily introspect a given SearchCondition instance representing either a primitive or complex query and also added a utility SearchCondition.toSQL(String tableName, String... columnNames) which can be used to convert this search condition into an equivalent SQL query to be subsequently executed against a database.

For example,


// find all conditions with names starting from 'ami' 
// and levels greater than 10
SearchCondition sc = 
   fiqlParser.parse("name==ami*;level=gt=10");
assertEquals("SELECT * FROM table 
              WHERE 
              name LIKE 'ami%' 
              AND 
              level > '10'",
              sq.toSQL("table"));

// find all conditions with names starting from 'foo' 
// and those with names not ending with 'bar' or
// levels greater than 10 
SearchCondition sc2 = 
   fiqlParser.parse(
   "name==foo*;(name!=*bar,level=gt=10)");
assertEquals("SELECT * FROM table 
              WHERE 
              (name LIKE 'foo%') 
              AND 
              ((level > '10'") 
                OR 
               (name NOT LIKE '%bar')),
              sq.toSQL("table"));

Here are some clarifications. First, note that the above code shows that a FIQL parser creates a search condition but it is a unit test code, the actual user code will use a SearchContext instead in a type safe way, providing a bean class to it. SearchContext will create an instance and will inject into it the property values, those provided and extracted from the original FIQL expression.

This provides for a possibility to protect against possible SQL injection attacks at the Java and the bean validation levels. For example, if a Book bean has an integer 'id' property then there's no way an unsafe FIQL query such as 'id==DROP%20users' can result in a 'DROP users' value injected due to a NumberFormatException.

Additionally, bean setters may have some custom validation logic and the CXF FIQL parser may also get enhanced to check for the bean validation annotations.

Perhaps you might want to give it a try and see how safe this option of auto-converting FIQL expressions into SQL queries is ?

In the end of the day, the good thing is that you actually do not have to use
SearchCondition.toSQL to get the SQL query. Suppose you are still concerned about the security or see that this method is not going to help you with building the advanced SQL queries which you actually use in the production, may be you are using java.sql.PreparedStatements or perhaps you don't even use a relational database but rather work with say Cassandra. If it is the case then just introspect a SearchCondition by getting to all the subconditions it has, and build a query which suits best.

XOP support in CXF JAXRS

2010-03-20T10:20:00.000-07:00

An XML-binary Optimized Packaging (XOP) is a W3C specification which is mainly associated with a SOAP Message Transmission Optimization Mechanism (MTOM) but is equally applicable to plain XML.

XOP is actually a very good specification which provides for the inclusion of binary data in XML payloads via links to co-located or external parts and thus facilitates the processing of such payloads by technologies like XSLT or even XMLSecurity, this article gives a pretty good description.

A CXF user has recently tried to have a single Java service class serving both SOAP MTOM and 'basic' HTTP multipart-related requests. Now, it is possible to do it, but I found it was not quite appealing so to say for users having to create either MTOM or multipart/related (with no links from the root part) payloads for the whole idea to work out. In addition, users have to add CXF JAXRS Multipart annotations to every method parameters corresponding to individual multipart parts which was not ideal given that the same user was also experimenting with a document-first approach.

So it took me virtually 1 day to add a XOP support to CXF JAXRS, thanks, as usual, to the fact that CXF has it all, specifically, attachment interceptors already deal with MTOP/XOP and its JAXB databinding has all the related utility code required for serializing/deserializing XOP payloads. One would need to set a CXF Message.MTOM-ENABLED property on CXF JAXRS clients/endpoints, but I think it is ok even though a property name is SOAP related, but it is really just an indicator to CXF as to whether do XOP or not.

I think it is a good enhancement indeed :

- SOAP users doing multiparts (MTOM) can have a simpler option for reusing the same code base when trying to do HTTP/REST as well, the only restriction at the moment is that CXF JAXRS will not unwrap the complex data types, example, just have a single EmailPayload method parameter, as opposed to many parameters corresponding to EmailPayload parts, such as text, attachments, etc; it is better anyway IMHO

- it is just a nice to have feature for CXF JAXRS users to play with, as far the multiparts support is concerned

The only regret I have is that I started working on it late enough and thus did not have it merged into soon to be released 2.2.7.

WSDL - first, CXF JAXRS model - first !

2010-03-15T06:31:00.000-07:00

So you're a SOAP developer who prefers starting the development of a new service from creating a WSDL document first. It is a WSDL-first approach that works for you, not a Java-first one. You are also interested in giving it a try and seeing what advantages following the RESTful style can give the users of your application, but would also like to keep a single code base.

If so then please read on this long post...

CXF makes it easy for developers to expose a single Java class as a SOAP and REST service, by sharing a service bean between multiple jaxws and jaxrs endpoints. The problem is, as far as you're concerned, that it requires one to follow a Java-first approach.

One option is for CXF to offer users an option to do a WADL-first development. CXF JAXRS is not quite there just yet but nothing prevents it now from providing a code gen command line utility and a maven plugin. This is an ongoing effort though and some UI tooling support would also be required. So, eventually, one would be able to use WSDL for developing SOAP services and WADL for developing RESTful services. This may or may not become a viable approach for users preferring a document-first style. Working on different documents (WADL and WSDL) might not make much sense, and creating a shared service class will not be possible.

The other advice which you, the SOAP developer, are most likely to hear today is as follows : you'd be better off migrating to REST/JAXRS altogether rather than sticking with SOAP. So the issue of figuring out how to do SOAP and REST the document-first style at the same time would be resolved. Even though there is some evidence that a number of individual and corporate developers may have done just that, I think this advice may not be the most effective option, as far as convincing those who have invested in SOAP and actually liking it no matter what that there could be a better option awaiting them. It is enhancing the runtime for it to be able to do the advanced stuff SOAP developers can do today with respect to the message-level security, multiparts and the document-first development and providing the easy path for SOAP developers to experiment with REST in the live production is what can convince the most conservative developers over time that the other approach (REST) may be adopted, partially at least.

Here is another option CXF could try: implement WSDL2, thus letting users define both SOAP and REST bindings in a single document which can be quite effective from the development point of view. Now, WSDL2 is said to be a better language than WSDL 1.1, but the question is : would an investment into implementing it be cost-effective ? Will it bring new users to CXF? And is it worth investing into it just for the sake of letting users do both SOAP and REST development the document-first way ? It does not seem it can do better that WADL in describing a RESTful application, given that it is more likely WADL can be enhanced even further while WSDL2 will not(not touching here on the interface vs resource centric approaches issue). Finally, as Dan Kulp says, a user demand is just not there, at least at the CXF users list. It can be quite a difficult thing to do, deciding on whether a given feature should be implemented depending on the existing or anticipated demand from users, sometimes expecting the users/customers always indicate to you what should be done next can stifle the innovation, but in case of WSDL2 it seems like the right thing to do.

This post has been long enough but I've tried to do some analysis there...So here is what can be done right now the real cost effective way (thanks to one of CXF users trying this option first) : generate your SOAP and JAXB classes from WSDL and then
'attach' some RESTful behavior to generated interfaces by relying on the annotation-free feature and finally have both jaxws and jaxrs endpoint sharing an implementation bean, with the jaxrs endpoint including the model describing the interface only. Example, imagine that no JAXRS annotations exist in this (generated) source interface. Next, just describe this interface similarly to the way it is done here. Finally add a jaxrs endpoint (see the one with a 'bookservice3' id) referring to the model describing this interface and the bean which implements it and you're done.

It would be mostly about making your code a bit more HTTP aware as opposed to magically turning it into a RESTful application, but it is an easy start and you may want to give it a try. And if it works for you then you might want to ask your friends from the UI team to have a tool generating CXF JAXRS models for you :-)

CXF JAXRS Search Extensions

2010-03-13T08:46:00.000-08:00

What is it that defines a user experience on the WEB ? Reading the information, submitting some information, following the links and searching.

How to let the users do the advanced search of the data your application makes available publicly ? One way is to let users type or transform their requirements into XQuery expressions, another option is to build a URI-friendly query language which will let users easily type it and link to the resulting URIs.

This post provides a good comparison between two approaches used by Microsoft Astoria and Google Base Data respectively. As you can see one can do some fairly sophisticated queries but they seem to be quite complicated for users be able to type them manually and in some cases are not easy on the eye. Both approaches provide for advanced search capabilities (to do with hierarchies, etc) but which may not be easy to implement.

Andy Michalec and myself have worked recently on implementing a search extension which will allow users to use a Feed Item Query Language (FIQL) to do the advanced search queries against CXF JAXRS endpoints. FIQL is a simple, very intuitive and easy on the eye URI-friendly language which lets users express fairly advanced queries.

Mark Nottingham writes simple and practical specifications. CXF now implements two specifications authored by Mark, RFC-5005 (partially) and the FIQL draft and I think CXF users will start getting some real value out of it.

Even though FIQL is a language originally meant to be used for searching Atom feeds, it is written such that non-Atom data can be searched too. So after Andy has spent an hour or so :-) on writing a quality FIQL parser, I just wired in a SearchContext into the CXF JAXRS runtime and now users can do the following :


WebClient wc =
WebClient.create("http://localhost:9080/books?"
+ "_s=name==CXF*;id=ge=123;id=lt=555");
List<Book> books = wc.getCollection(Book.class);

Here we create a FIQL expression allowing us to get all the books with names starting from "CXF" and ids greater or equal to 123 but less than 555. FIQL can let you do much more powerful queries but I think it is just a brilliant effort from Mark.

Note how simple the query is, here are the rules in a nutshell : it is only the first '=', the one which follows an _s query name (for the record, _search is also supported) which acts as a usual separator between a query name and its value, '==' means 'equals', while '=' in '=gt=', etc helps easily identify a condition such as 'greater than'. A user can quite easily type such an expression in a browser without some (web )UI gadget hiding the complexity of the language.

And here is the server side test code :


@Path("books")
public class Books {

private Map<Long, Book> books;
@Context
private SearchContext context;

@GET
public List<Book> getBook() {

SearchCondition<Book> sc =
   searchContext.getCondition(Book.class);
List<Book> found = sc.findAll(books.values());
return found;
}
}

An injected SearchContext returns you a SearchCondition which can be a composite one and encapsulates a given FIQL expression, though nothing prevents us transparently supporting other languages in the future, such as XQuery, etc.

Now, at the moment the assumption is made that the data are kept in memory, but often enough the search requirements are passed down to the database layer. You can try to push SearchCondition as close as possible to the db layer but SearchCondition, having captured the FIQL expression can let you easily transform it into an SQL language expression if needed, ex, it can let you check all the conditions it encapsulates, and the values which will be used during the checks, etc.

I'm not sure yet if I'll merge it into 2.2.7-SNAPSHOT or not. May be I'll keep it in 2.3-SNAPSHOT and experiment a bit more and then merge it into 2.2.8-SNAPSHOT once the interfaces are deemed capable enough. Will also update the Atom pull server to let users search for very specific log entries, that what FIQL was created for :-)

Enjoy !

On the way to WADL-first development in CXF JAXRS

2010-03-10T04:17:00.000-08:00

Yesterday I added a CXF JAXRS request filter capable of generating the Java code for consuming a given JAXRS resource on demand. I was about to finish it two weeks ago but had to postpone it a bit. Here's a test code fragment showing how to get a zip containing the source :


// Get the link to the source
WebClient wc =
 WebClient.create("http://localhost:9080/petstore");
XMLSource source = wc.query("_code")
                    .query("_os", getOs())
                    .get(XMLSource.class);
String link = source.getValue(
  "ns:html/ns:body/ns:ul/ns:a/@href",
  Collections.singletonMap("ns",
    "http://www.w3.org/1999/xhtml"));
// download a zip file          
WebClient wcZip = WebClient.create(link);
InputStream is = wcZip.accept("application/zip")
                .get(InputStream.class);
// unzip and compile it

Please see a testPetStoreSource test for more details. The _os query is optional, it is there to ensure you can get OS-specific line separators added to some of the generated classes (ex, the server is running on Windows, you'd like to run a test client on Unix). You can also add a _language query but it is only Java which is supported for now.

What is interesting is that a newly introduced CodeGeneratorProvider generates the source from a WADL instance which another provider, WADLGenerator, creates after introspecting a given JAXRS resource. The zipped source will contain the JAXB-generated classes from a WADL grammar section (if any) and the proxies (interfaces) representing WADL resources, including the subresources, with the resource methods linking to corresponding JAXB classes.

You can request that classes be generated from a WADL grammar section only by adding a _codeType=grammar query. Two other possible values here are 'proxy' and 'web', the former value is a default one at the moment with the latter one being not supported yet. I need to think a bit more about what sort of code can be generated for a _codeType=web. Suppose we have a resource named BookStore. What is the difference between a method called getBook (in case of proxies) and a method called get(in case of web clients) ? I'm also not sure yet what to do with cases where WADL resource contains multiple methods like GET but with different mediaType values, need a bit more time. In meantime if the word 'proxy' makes you nervous :-) then please just use _codeType=grammar to download the classes representing schema elements and proceed from there by using your JAXRS runtime's web client api.

How does CodeGeneratorProvider generate the proxies given that WADL does not provide for it ? Internally, it requests a WADLGenerator to add 'id' attributes to WADL resource elements representing root or subresource resources and to WADL resource/method elements. Example, wadl:resource/@id="{org.apache.cxf.test.RootResource}" and wadl:resource/wadl:method/@id="getBook".

This is really all what 'facilitates' the WADL to Java code generation which is exactly what CodeGeneratorProvider does. In fact, I haven't actually even thought originally about introducing such a provider but then I thought that a future command-line codegen tool allowing for a server-side code be generated from a WADL document will do exactly what CodeGeneratorProvider does, albeit it will generate the resource class skeletons as opposed to proxies. In fact, given that CodeGeneratorProvider is a regular CXF JAXRS provider, you can set a false 'generateInterfaces' property on it and you'll get a *server-side* code downloaded, perhaps you might want to use it to write your own added-value service interposing the original one.

CXF 2.2.7 will be out soon so please experiment with this new feature.

I'll need to think a bit more about the format for resource ids, perhaps it can be just "BookStore" but a future codegen tool can ask users to provide a package name. We can have JAXB classes acting as subresources that is why I've introduced an extended QName format initially. At the moment WADL does not allow internal method elements to contain ids (as opposed to global ones), hope this restriction can be lifted, alternatively it would be easy for a (UI) tool allowing users to create WADL documents to ensure resource methods are declared globally and then linked to from internal resources.

Seems like using resource and method ids for the purpose of allowing WADL-first development might make sense, it will preserve the simplicity of WADL the language.

Finally, why worry about the WADL-first development ? It is simple : IMHO it might help in making the RESTful approach toward developing web services being more attractive to many developers who prefer starting with building a picture of the future application first. So imagine your UI tool showing a nice view of how resources relate/link to each other and what formats and HTTP methods they support and schemas they're aware of, would not it be cool to be able to press a button next and have most of the code being generated for you ?

CXF is my favourite game

2010-03-10T03:47:00.000-08:00

I was listening to the radio in the car this morning and I heard 'And I'm losing my favourite game' by The Cardigans. For some reasons, I'm often associating certain phrases from the songs I hear at a given moment of time with what I'm thinking or doing at the moment. So the idea of "CXF is my favourite game" sprang to mind and here I am, with all the time on my hands, blogging about it.

The last week was quite interesting. For the most of the last 20 years I've been at work virtually every day doing something, writing some code, discussing something, thus being presented with an opportunity (this is how I'd like to see our severance with the Fuse team) to rethink and take a break poses quite a challenge. But there's definitely something in it. For example, I've been to London many times but I felt the trip last week was the best one : you kind of feel the energy of the city and realize the world is so rich and there are definitely opportunities lurking out there.

I've been focusing mainly on CXF for the last couple of years. I don't know yet where my next career move will bring me to, but I'm feeling there could more coming from CXF, I'll try to keep contributing whenever a get a chance. The software world is big but I'd like to see CXF being a continuous success.

Higher and higher we are gonna take it...

2010-02-26T12:48:00.000-08:00

I've been thinking today how to title this blog entry. First I typed "Sky is the limit" but spotted this page. Then I typed "The best is yet to come" but surely I found this one. So I ended up borrowing a phrase from the Killer's Confessions of the King and stopped being melodramatic.

It is the time to seek a new beginning and reflect a bit on the last 5.5 years I spent with IONA and Progress Fuse.

IONA was the company where I grew up as a software engineer. I was fortunate to work from the day one with the best engineers one can dream of working with, some of them being very well-known in the industry and some not but it is them from the latter group who brought me to that stage where seeing a failing system test passing was the most satisfactory thing one can imagine. It was the company where one could learn to compromise and move forward. And we had quite a few laughs all the way ! And VisIONAry t-shirts were the 'best' in the industry :-).

Working for IONA was the real thing. I enjoyed it. But I have to admit working in Progress Fuse on the CXF JAXRS implementation was probably the best part. It was the 'working on the line' kind of experience, the bleeding edge, it had it all ! Working on the open source projects gives one a chance to be a coder and an architect and lets the one to talk to users on the everyday basis. I'm not sure what can be better, as far as the software engineering is concerned.

Now it is time to think. Listen to U2. Start updating my CV. Visit London next week and hope Arsenal will not lose again (good we bought the city break package the previous week :-) as I'm feeling a bit frugal at the moment :-)) Continue supporting CXF users. And seek the new beginning.

Stay tuned and have fun !

Use your favorite Atom reader to view CXF logs

2010-02-17T09:12:00.000-08:00

Andy Michalec and myself have worked recently on the Atom-based logging feature. Andy has implemented all the base classes and a push-style feature as well as wrote the initial draft describing how the push-style logging works. Myself has contributed recently by adding the initial code for supporting a pull-style logging.

Here is some more information about these features. They haven't made it into 2.2.6 nor will they make it into 2.2.7, etc but rather stay on the 2.3-SNAPSHOT trunk given that their code has been moved from the jaxrs frontend to a new rt-management-web component available on the trunk only.

I reckon the push style feature is already quite functional, you can try it by downloading a 2.3-SNAPSHOT and 'attach' AtomPushBeans to your jaxws or jaxrs endpoints by listing the loggers used by your code, as documented on the wiki. You may also find these links of interest :
beans.xml and JAXRSAtomLoggingPushSpringTest, plus non-Spring JAXRSAtomLoggingPushTest and batch logging.properties. You can have log entries wrapped in a number of ways, as feeds or entries, with the content being added as an explicit entry content or an entry extension. Processing such entries is easy on the client side, with CXF you can do xmlSource.getNode('atom:entry/atom:content/*', LogRecord.class) or xmlSource.getNodes('atom:feed/atom:entry/atom:content/*', LogRecord.class).

Before actually moving to describing the pull-style feature, I'd like to mention that CXF can transparently ensure that Log4J or SL4J events can be captured back into JUL log records so you can get non-JUL records pushed/pulled as well.

Now, just today, I've finalized the first cut of the pull-style logging feature and I'm actually quite excited with the fact I was able to get a link to an endpoint-specific log feed from the CXF services page and see the list of log entries in Firefox, IE and a standalone Atom reader, by traversing to individual log entries (not in IE though which does not seem to recognize alternate links). Give it a try please, you actually might like it and it is very easy to try :-) !

Have a look at this beans.xml (see an atomPullServer bean which 'attaches' itself to a 'resourceServer' endpoint and relies on an 'atomServer' endpoint to expose the log entries) and the JAXRSAtomLoggingPullString test (see testFeed()). You will also need to add a dependency on the rt/management-web.

Some more details about the AtomPullServer. By default it is set to display 40 entries per page and keep 500 records in memory. It uses 'previous', 'next', 'last' and 'first' links to let users traverse across the whole range. The problem here is that I don't know of atom readers supporting these link types, let me know please if you do. Perhaps you do a simple atom browser yourself or easily deal with these links programmatically. May be we even add a basic browser in CXF over time.

You can inject into it a ReadWriteLogStorage implementation which can be used to offload the records to the external storage and persist them after restarts. Or just register a ReadOnlyLogStorage if you do not want your logging runtime to generate duplicate records if they're already being saved to an external file. At the moment, the latter storage requires a bit more effort as you'd need to write a file parser but it's doable and we may add few helpers later on. ReadOnlyLogStorage relies on the SearchCondition, stay tuned on the updates about using it in a regular JAXRS application code. Note that even if you already log to a file, you can still use the AtomPullServer to capture the most important log entries, there will be few of them in a healthy system so you can probably just set the max in memory size to 1000 and not worry about reading the same events from a file...

So this is what we have at the moment, give it a try please and help us to improve this feature.

Enjoy !

Support for JMS in CXF JAXRS

2010-02-09T05:21:00.000-08:00

One of CXF JAXRS users have asked about the possibility of supporting JMS for a given JAXRS resource be able to get data over HTTP and JMS.

CXF has been designed from the ground up to support multiple transports so it was very easy to ensure CXF JAXRS could get the messages from JMS. Please see this beans.xml, it is just a matter of adding a transportId attribute to a given jaxrs:server endpoint, so if you have say a single service bean shared by both http and jms aware jaxrs endpoints you have multiple channels supported.

Now, you may ask, what is it all about ? JAXRS is about helping users to build HTTP-based RESTful services ? What about a "transport independence being a bug but not a feature" thing ?

I guess I could've said that REST is not about using HTTP, but it is just that HTTP, being the transport/application protocol of the WEB, is firmly associated with REST.

What really matters IMHO is that CXF JAXRS users will be able to see their 'investment' in JAXRS growing up. They've chosen to structure and annotate their resources in a way which makes it easy to expose them as RESTful services and being able to get data from different channels by relying on the underlying runtime is a good thing.

One of the reasons behind the 'longetivity' of SOAP is that users can get SOAP messages from JMS, in other words, they can easily tap into all those MQ stores with the help of the runtime.
Of course, one well-accepted alternative would be to use a routing engine such as Camel which would delegate from a jms channel to a given jaxrs endpoint. CXF gives you another alternative now.

What is common between CXF and Microsoft WCF

2010-02-09T04:22:00.000-08:00

This morning I've read the interview with Don Box (thanks to this blog entry). I'm kind of unhappy with Twitter 'hijacking' a lot of people like Don expressing their thoughts aloud, I like reading the blogs, I can not get a lot out of Twitter one-sentences. I was 'following' Don since him contributing to his MSDN COM column, I wish himself and others could still find some time and blog...

So back to the interview. Here is what I liked most. Stefan asks :

" What is Microsoft doing from your perspective with regards to REST support? Do you see the two worlds coexist? Which role does which one play?"

Don replies and finishes with :

"One of the interesting things about Microsoft that took me a couple of years to understand was there is no place for religion in products. We build products for lots of different people and if someone wants to do REST, I want them to love our stuff. If someone wants to do SOAP and WSDL, I want them to love our stuff. Basically, it's our job to allow our customers to do what they want to go do with their software and the easier we can make that, the better. "

+1. This is what it is all about. This is what CXF is about. I love working on the CXF JAXRS project, JAXRS is a fantastic spec. I've also had some great experience in interacting with (IONA) customers (though mostly indirectly by fixing bugs :-)) who continue building advanced SOAP services even today. In CXF we are trying hard to ensure users can get the best of their chosen technologies/approaches, by combining them if needed.

I also liked how Don was talking about Mark Baker. In fact I was quite fortunate to have a long exchange with Mark where I was asking him a lot of newbie questions, it can even be found at www-archive@w3.org.

Support for CXF in Enunciate

2009-12-18T13:31:00.000-08:00

Enunciate is a popular framework which can be used to deploy and expose Java applications as WEB applications. I had read good reviews about it long before I joined the CXF JAX-RS project.

Thus I was quite excited when I found out from this announcement CXF JAX-RS was also optionally supported. Please see some more information from the modules page which says that CXF JAXWS and JAXRS frontends are supported (as a side note, CXF users can deploy endpoints without depending on Spring by relying on non-Spring CXF servlets).

I would like to use this post to encourage the leads of other higher-level frameworks to let users choose between different web services enablers and those exposing Java applications as RESTful services in particular, by doing it the way Enunciate did.

It will not harm. Giving users a choice never harms. The most likely sideeffect is that your favourite framework will likely see more users coming in.

I hope Enunciate will make CXF and CXF JAX-RS more visible. Likewise I hope Enunciate will enjoy seeing a number of its users rising in turn too. I will be happy to play with this framework later on too and see if I can contribute somehow.

Enjoy !

The RESTful Java with JAX-RS book

2009-12-17T14:08:00.000-08:00

Bill Burke, the author of RestEasy, has had his new book, RESTful Java with JAX-RS, published recently.

Bill is one of the main contributors to the success of JAX-RS so this good JAX-RS reference book with practical examples will be welcomed by all JAX-RS users and ReastEasy fans in particular.

Here I would like to thank Bill for letting us do a small contribution to the book. He kindly approached us and proposed to do a brief description of the Apache CXF implementation of JAX-RS which is what we did. Seeing it being referenced alongside the heavyweights like Jersey and RestEasy is encouraging and humbling.

Finally, Bill, being the true host of the whole project, referenced RestEasy last in the list of the implementations. Very kind. Thanks Bill !

Please give this book a good read :-)

OT: The Fever Pitch

2009-12-16T03:13:00.001-08:00

I have to make an admission : I really start liking the way Arsenal FC plays. In fact, I simply can not help waiting to see them playing on the BBC Match of The Day tonight and then reading the reviews in different newspapers and online on BBC and arsenal.com tomorrow, even if they not win. Arshavin is 'to blame'. But now I can also see what a good team Arsenal is.

When I came to work to England nearly 13 years ago, I already was a ManU supporter. A lot of ManU supporters actually live abroad. After living for nearly a year in Manchester I became even more ManU-obsessed, especially after seeing them playing live in Liverpool at Everton, despite the fact I found out that actually there also was a Manchester City FC too, supported by quite a few locals I spoke too :-). I still love watching ManU playing, they are playing for people who watch them and they probably still have the more local-grown talent on the pitch than other teams in the top 4.

That said, Arsenal is the team which I am really excited about at the moment. It was a 'ruined' weekend when they lost to Chelsea but the last weekend was great ! Two weeks ago I watched them playing Stoke on the Match of The Day on Saturday on both RTE1 and BBC and then again the next day on the Match of The Day 2 on BBC.

What is the story ? Another milder version of the Fever Pitch ? And what a great book that was, my friend who is an Everton fan, presented it to me the other day.

I realized this Monday Arshavin inspires me. He is a match winner and a real fighter. Arsenal are a bit "vertically challenged" upfront as one of Arsenal fans said the other day :-), but they are a great team to watch.

Go Arsenal !

The argument about fast JSON processors

2009-12-11T05:01:00.000-08:00

I have heard by now a number of times that Jettison is slower than Jackson when it comes to handling large JSON sequences.

To be honest, I am not sure what this argument is about. Perhaps because I do not understand JSON ? I would rather see statements like : Jackson is a popular JSON processor which can let users create correct JSON sequences without users having to introduce JAXB dependencies. This is something I can get.

The argument about the performance sounds like a red-herring to me. Are you writing a service which returns a 7OK JSON sequence ? Is it the sign you may need to rethink the way your service has been designed ? IMHO JSON is not the means to pass around huge sequences, it is the format which has been designed to help users streamline the development of client-facing Web frontends, at least this is my understanding.

So if you need to deal with large chunks of data then may be you may want to return a JSON-formatted Atom feed, something that Abdera supports, with links pointing back to the next chunks of data. Or just use XML for a similar purpose ?

And if you write your Ajax JavaScript clients handling JSON sequences of small to medium size then perhaps the performance issue is not actually an issue ?

Having said all this, I will be happy to see Jettison supporting streaming eventually. Hope it will happen soon. The most important thing though is that it will now more likely to produce correct JSON sequences which is what users really want.

Better Jettison is on the way

2009-12-10T10:48:00.000-08:00

It would be fare to say the Jettison project has been stagnating for a while now.

I do think it has been doing really well as part of CXF, by generating and consuming JSON sequences from and into JAXB beans. It has not been always 'successful' but still worked well for many cases. In addition, CXF JAX-RS provides a number of options for customizing input and output JSON sequences on top of Jettison :

http://cwiki.apache.org/CXF20DOC/jax-rs.html#JAX-RS-JSONsupport
http://cwiki.apache.org/CXF20DOC/jax-rs.html#JAX-RS-CustomizingJAXBXMLandJSONinputandoutput

That said, Jettison has not been capable of handling recursive structures well, and may 'surprise' now and then in a number of other cases. Some CXF users have tried a well-rated Jackson, however, some users are still like working with the default Jettison-based CXF JAX-RS provider.

Thus it was just a matter of time before motivated and interested users were to step in and contribute to Jettison. John Worrell has recently done a major refactoring of the Jettison XMLStreamWriter implementation and his patch has already been applied by Dejan. In fact, CXF trunk has just been updated to depend on Jettison 1.2-SNAPSHOT containing the improved writer . This is a great contribution from John and I do hope it will give a new lease of life to Jettison.

If you do use Jettison, with or without CXF, then please give the latest SNAPSHOT a try. Please report the issues if any to the Jettison users list or leave a comment at Jettison-87 and also close the JIRAs which may have been fixed, example, a well-known Jettison-57 has been fixed along the way after the patch from John has been applied.

So it is a good news for Jettison users. Another CXF user has actually expressed an interest in enhancing Jettison for it to support streaming.

The better Jettison is on the way.

Embracing Atom with CXF

2009-12-06T10:42:00.000-08:00

Until recently, it has been possible to write an AtomPub JAX-RS application in CXF by using Abdera Feed or Entry classes like this :



public class AtomPubResource {

 @GET
 @Path("/feed")
 public Feed getCollection() {
     // create Feed as needed
 }

 @GET
 @Path("/feed/{id}")
 public Entry getEntry(@PathParam("id") int id) {
     // get individual entry
 }

 @POST
 @Path("/feed")
 public void addEntry(Entry entry) {
     // update collection
 }

 // etc
}

Going this route gives users the most control over how a given feed is initialized and how entries have the actual content captured. Some frameworks provide JAXB-based classes for dealing with Atom primitives such as feeds and entries - I am not quite keen on extending CXF JAXRS in a similar way, after all, what it can give a user apart from introducing alternative foreign classes into their main application code ?

With the addition of AtomPojoProvider provider and Atom-specific extensions few more options are now available for CXF users to start playing with Atom (note the provider and extensions code may still get changed).

To start with, users can now simply do :


@Path("/store")
public class BookStore {

 private Books books = new Books();

 @GET
 @Path("/books")
 @Produces(
  {
   "application/xml",
   "application/json",
   "application/atom+xml;type=feed"
  })
 public Books getBooks() {
     return books;
 }

 @GET
 @Path("/books/{id}")
 @Produces(
  {
   "application/xml",
   "application/json",
   "application/atom+xml;type=entry"
  })
 public Book getBook(@PathParam("id") int id) {
     return books.getBook(id);
 }

 @POST
 @Consumes(
  {
   "application/xml",
   "application/json",
   "application/atom+xml;type=entry"
  })
 public void addBook(Book book) {
     books.addBook(book);
 }

 // etc
}

What happens here is that you continue write your Java JAX-RS code, the way you may often do, without introducing any direct dependencies on the Atom-specific classes, and just experimenting at the same time with implementing an AtomPub application on top of your collection classes like Books. Starting with AtomPub and Atom is now as simple as updating Produces and Consumes values and registering an AtomPojoProvider.
As long as your Books class has default collection setter and getter methods, getBooks and setBooks returning and accepting a List of Book instances in this case, and happy with some of default Feed and Entry properties, that is all that needs to be done.

The next step is to tell the AtomPojoProvider the names of the collection getters and setters on individual classes such as Books.

The next step is to register Feed and/or Entry builders which can help AtomPojoProvider with setting various Feed and Entry properties, still without introducing direct dependencies in your main code.

Finally, you can take the complete control with registering Feed or Entry writers or readers. This option is similar to having Abdera Feed or Entry classes in your main application code except that these providers will let you deal with these classes outside of the main application code.

CXF users will now have plenty of options for writing AtomPub applications on top of the JAX-RS runtime. Give it a try and enjoy !

Come on, Abdera !

2009-11-25T13:19:00.000-08:00

Just few hours after blogging about the Atom blogging feature being now developed in CXF, I thought it might be worth checking what was actually happening with Abdera which we currently depend upon in CXF.

I actually noticed before not much was happening in the project by briefly looking at the main page but did not pay any attention to it. This time I clicked few more links, and when reading the November archive I just experienced a number of conflicting emotions during few minutes :-), starting from the disappointment and ending with a cautious optimism.

What I do not understand is how a project which by many users is assumed to be a Reference Implementation of everything to do with Atom and AtomPub ended up being nearly retired ? How it could have happened given that just a couple of years ago AtomPub and Atom were probably one of the most talked about technologies ? They were touted as candidates for a complete replacement for SOAP given that Feed provides an envelope-like wrapper around (data) Entries ?

Well, it is not that important today. The thing is that actually many users do use AtomPub and Atom. Things are happening on the atom-syntax list. Abdera is obviously not the only way to create Atom Feeds or Entries but it just a very good library for doing it. IMHO it is a perfect library for users to use when they need to create sophisticated and real-life feeds or entries. I am not so optimistic about Abdera acting as a standalone server framework, IMHO it is not why most users are relying on Abdera. I would personally like to see it moving toward imlementing other promising Atom draft specs, etc.

In CXF we are sticking with Abdera for the time being. As far as the Atom logging feature is concerned, using Atom was a rather obvious choice due to the fact it was the most cost effective way to have the interesting events be delived to a variety of the existing Atom-aware consumers.

We hope Abdera will help us. We would like Abdera, the Atom and AtomPub RI to live and succeed. This project needs a leader and it is good to know James Snell is planning to reengage.

Do you remember Microsoft Web3S ? I thought it was a good effort, but the Atom won.

So will Abdera stay around ? Come on, Abdera !

Updates to the CXF JAXRS runtime

2009-11-20T08:32:00.000-08:00

Updates to the CXF JAX-RS runtime have been somewhat limited during the last few months due the ongoing high-priority internal project I've been assigned to contribute to. This project is likely to continue for another couple of months.

Given this, I've focused on working on some of the issues which users have asked on the CXF lists a number of times, directly or indirectly.

So here is what has been done for CXF 2.2.5 :

1. Redirection support, both at the CXFServlet (check the Redirection section) and CXF JAX-RS levels. Users can redirect to static or dynamic resources such as JSP, or to some other servlets.

2. Additional updates to the way JAXB/JSON inputs/outputs can be customized. The purpose of this feature is to let users do simple input/output updates by changing, dropping or appending elements and or attributes. For example, it is now should be possible to deserialize the sequence of JSON arrays without a root element.

3. Few minor updates to JSONProvider, such as a BadgerFish convention support and a fix to let CXF JAXRS endpoints interact with the Dojo JSON RestStore (patch has been submitted).

4. Improvements to the way multipart/form-data requests are handled.

5. ResourceComparator extension which can let users affect the way multiple matching resource classes or methods are selected.

6. Documentation annotation has been added for more descriptive WADLs be generated

For the next couple of months or so, due the above-mentioned internal project, I will continue focusing on making the localized updates which will may make the difference for CXF JAXRS users. Plus do some JAX-RS 1.1 work and try to contribute to Andy's Atom logging project. I will not have time to do any Java EE work as mandated by the JAX-RS 1.1 maintenance spec - I'll rather focus on working on more down to earth issues for 2.3. By the way, if anyone out there is contemplating contributing to CXF JAX-RS then doing the EJB or other EE-related JAX-RS 1.1 tasks will be welcomed.

The release of CXF 2.2.5

2009-11-20T08:19:00.001-08:00

CXF 2.2.5 has just been released. I don't often, if ever, blog about individual CXF releases but I thought it was worth commenting about this release.

In CXF 2.2.5 improvements have been done to the core, JAXWS and JAXRS runtimes, but I'll post an update about JAXRS-related updates next.

What is remarkable about CXF 2.2.5 is that in the space of few weeks nearly 100 or so long-pending bugs and enhancement requests have been fixed. CXF core and the JAXWS runtime have been improved a lot. Dan, Benson, Christian and others have embarked on the bug fixing spree and the result has been impressive. I've become dizzy during the last few weeks getting the constant stream of merge emails to the trunk and 2.2.x in my email box.

I know it is next to impossible to do a perfect software product. The CXF JAXWS implementation is about to become the one.

Atom Logging in CXF

2009-11-18T01:35:00.000-08:00

Andrzej (Andy) Michalec, the CXF committer, has just committed the initial code for supporting push-style Atom logging in CXF.

It is only a beginning. It all seems quite straightforward to implement, but even a push-style Atom logger requires a lot of effort and thinking for it to be implemented well, and even more work will be needed to polish the original implementation. So it is a great effort from Andy, thanks.

This code will initially live in the CXF JAX-RS implementation code base but the idea is that all of CXF endpoints, JAXWS and JAXRS based ones, will be able to have their logging events handled by these Atom-based handlers, by registering them from the logging properties or from Spring.
The pull-style appender will be done later on, it will be more complex than the push-style one. Supporting Feed Archiving features, etc, is on the map, and we hope Abdera will help there.

Going forward, we can see users being able to selectively register callback URis with CXF endpoint-specific push-style loggers or subscribe to individual feeds, possibly finding the required feed from a master feeds endpoint. The users will be able to apply a lot of various configuration to both push and pull style loggers. Some of this configuration will have to do with the mechanics of the pull- or push- style deliveries, and some of it will have to do with how the log records will be presented in an Atom feed - there're quite a few possible options there.

This will also drive further requirements on the CXF JAXRS Client API, namely the support for one ways and asyncs will be on the map.

I'm thrilled. I really am. Hope you will be too once you start using this feature in CXF.
We'll start documenting it a bit later on, we might have it all done in time for CXF 2.3.

Think CXF, think Atom. Think Atom, think CXF. Enjoy :-)

The WADL Dilemma

2009-11-16T08:51:00.000-08:00

The Web Application Description Language (WADL) is now being acknowledged by many as a language which is practical, functional, very capable of describing the advanced RESTful web services and yet simple and easy to read and understand.

WADL has now been submitted to W3C which is a great achievement for Marc Hadley. What is really unique about this submission is that it has not been submitted by the usual suspects like Microsoft and IBM but rather by the individual author. It seems that the time when various web services specifications have been discussed by a number of years by various companies is behind us, but you never know.

CXF has been supporting WADL since 2.2.3. The auto-generated WADL instances can describe live RESTful services quite well, with JAXB-generated schemas being included in WADL grammar elements and indeed with all the subresources being described too, as long as the static subresource resolution is enabled.

More enhancements have to and will be done but first I'll touch on what I call a WADL dilemma.

It is a Web Application Description Language. It is the way it describes the *Web application* that distinguishes it. For example, a WADL consumer such as a RESTful client test framework can read a given WADL document and let users test the application by following the application paths described by WADL.

I think it's of little doubt that the decision has been made to design WADL such that application interfaces (such as Person or Book, etc) could not be described in WADL. This is absolutely normal given that RESTful consumers are generally programming againt generic HTTP interfaces and programming with proxies is often considered to be an antipattern. Thus I guess adding the possibility to describe application interfaces was an obvious non-starter.

As a side note, before proceeding further, I think I might be nearly coming to the conclusion, that as far as choosing between proxies or http-centric clients for consuming restful services is concerned, it is really like choosing between different shades of grey. Some users, when they see proxies, think RPC immediately but it is not quite the case for proxies producing perfectly valid RESTful requests. Neither option is immune to the service changes though but good frameworks such as CXF will offer a lot of help for coping with such changes. I think it may be more a matter of the taste these days...

So back to the dilemma. What I think is currently missing from WADL is the fact it can not be used to generate what seems to be the main source of auto-generated WADL instances : JAX-RS annotated service classes. The WADL-first option will work well for the http-centric consumers but it is Java-first all the way for the JAX-RS services.

The Java-first approach to the services development has proved to be very popular and viable. However, the option of modeling web resources and generating service classes seems quite attractive too but enhancing WADL to support such an option would just basically turn it into WSDL. And this is where the dilemma is.

In meantime, a number of various approaches is being tried to create richer WADLs out of Java classes. One of those attempts is to do with extracting Java Docs for resource classes and methods and publishing them as WADL documentation fragments - it does seem like a step too far given that Java Docs are meant for the Java engineers using a given interface or class. But not for the users of Web Services backed up by such classes/interfaces.

In CXF we've added a Description annotation which is mapped to a WADL doc element and we will recommend users to use this annotation for documenting resources or methods using the language intended for the users of a given web service.

The other thing we need to think about is how we can let users do the WADL first developement. The question is how to avoid turning it into WSDL. That said, we should also probably look closer at the option of supporting WSDL2, especially for the users who do both SOAP and REST - having a single document describing both SOAP and REST may benefit them, though as far as describing RESTful services is concerned WSDL2 seems a bit limited.

Stay tuned.

What is Distributed OSGI ?

2009-09-22T12:43:00.000-07:00

Many of you have already heard about Distributed OSGi (DOSGi) OSGi initiative and about the CXF DOSGi RI subproject (superbly documented by David).

I'd just like to comment a bit more about DOSGi.

Quite a few people have just immediately branded DOSGi as yet another RPC-technology and thus being not worthy of their attention. This is not quite correct.

DOSGi does prescribe how the OSGI consumers can end up with a proxy after using an OSGI ServiceTracker to get hold of a particular service interface reference. So it does make it possible for OSGI clients to consume remote applications with the help of proxies. Guess what ? Sometimes proxies will just work really well - some of those remote services will probably not change ever again or has been written by the same developer who writes a client bundle - thus making the future changes more manageable.

In the end of the day it is obvious DOSGi will help popularize OSGi among many developers out there as it makes it quite straightforward to have an end-to-end (D)OSGI application working.

But of course DOSGi is more than just about creating proxies under the hood. The primary use case is to let users expose their OSGI applications as remote services - you don't even have to use DOSGi on the other end to consume such services. It's become more obvious with the DOSGi RI now letting users to expose their OSGI services as SOAP based or RESTful (JAX-RS) services. You can consume such services from your browser if you wish.

So what some people might've missed is that in its basic form a DOSGi RI is an OSGi-enabled (CXF-based) web services stack. DOSGi RI is a handy collection of a number of OSGI bundles which you can drop into your favorite OSGI container and start developing web services (SOAP or RESTful ones) with OSGI in mind. DOSGi RI is a composite Web Services OSGi feature.

But DOSGi offers few more options. DOSGi Discovery service is a useful thing indeed. Now, it does facilitate the creation of proxies by helping DOSGI to discover that some services have been published. But note that DOSGI does not force your consumer bundles to use proxies, especially those consuming the RESTful services.
You can just write the client code using an HTTP-centric client API and simply use OSGi to replace your consumer bundles as needed. Or you can get hold of the DOSGi Discovery service and still use an HTTP-centric client API by feeding it the address of the remote RESTful service you've just obtained from the Discovery service. It would probably be worth adding a utiltity bundle to the DOSGi RI distribution which will help interested users to interact with the Discovery service though consuming it directly should not be too difficult.

Hopefully this blog entry has shed some more light on what DOSGi is about.

JAXRS and JAXB without annotations in CXF

2009-08-28T02:48:00.000-07:00

The CXF JAXRS extension allowing users to describe how their services have to be handled by the JAX-RS runtime without annotating them has already been mentioned in this entry.

It has been improved since then, it is now possible to describe interfaces with the runtime being able to apply the model information to the objects injected from Spring or registered from OSGI BundleActivators. Here is the updated documentation, and here is the short info on the DOSGi demo showing this feature in action.

Now, when I mentioned this feature for the first time, I implied that for the (CXF JAXRS) JAXB provider to continue working JAXB annotations still had to be there. The JAXB provider has been enhanced quite a bit recently but one of the enhancements which is worth mentioning here is that one can now tell it to marshal and unmarshal Java beans without them being annotated with annotations like @XmlRootElement or introducing JAXBElements in their method signatures. One can simply set a 'marshalAsJaxbElement' property on the JAXB provider and it will wrap all the objects as needed. It is also possible to be more selective about which objects will be wrapped under the hood. For more information see here and here.

So yes, it is possible after all : have a production code working without annotations.

Distributed OSGi RI gets the RESTful edge

2009-06-20T11:13:00.000-07:00

We have completed the initial CXF JAX-RS integration into the DOSGi RI.

There is a number of various approaches out there to expose a given OSGI service remotely - DOSGi is a good effort which describes how this task can be resolved in a standard way.

So now DOSGi users will be able to expose a given bean either as a SOAP or RESTful service. There will be more updates coming in shortly for a given bean be exposed as a combined SOAP/RESTful service and for properties be applied in a way which will let users easily configure a large number of services.

Now, as far as RESTful services are concerned, one can also expose them without applying JAX-RS annotations. I'm actually quite excited about this option despite the fact it kind of tries to sway you from being a good JAX-RS citizen :-). One thing is that one of the promises of DOSGi is that users should be able to expose the interfaces transparently, without forcing the knowledge of JAX-RS/etc on the remote consuming bundles. While there will be cases when having annotations is perfectly acceptable in DOSGi it is still nice to have an option to do it without annotations.

As a side note, applying the external model info to a lot of existing applications out there which are exposed as RESTful services using expensive adapters or can not afford changing the code looks really promising to me.

I would also like to thank Josh Holtzman for his contribution. More updates to follow soon.

Pragmatic Web Services with Apache CXF

2009-06-08T15:28:00.000-07:00

Pragmatic web services are the ones which deliver, have been written with the interoperability in mind and which can cope with inevitable changes.

Pragmatic Web Services with Apache CXF article has been published at DZone Architects Zone and it attempts to look at how changes might be dealt with the help of various CXF features. It spends little time talking about REST and SOAP though it describes how some JAX-RS extensions can help dealing with the changes.

Arguably, the example which is looked at in the article is a bit contrived in that search parameters are presented in some methods as PATH variables. One can easily come up with a more suitable example where PATH variables can be used and I thought the example served the purpose of the article really well.

There are some minor formatting and link issues with the article at the moment but hopefully the DZone team who have helped a lot in publishing this article will fix them.

Comments are welcome.

The benefit of a doubt

2009-06-02T10:12:00.000-07:00

I have read recently some thriller which has nothing to do with a "web services" topic. I don't remember now the actual details of that thriller but I read there something which I thought might be relevant.

It was something like "If you'd like to be a good doctor then you have to continue doubt everything you have already learnt or are about to learn".

I think something similar can be advised to software engineers, myself including, and to web services developers in particular. Of course, there should be some compromise there, so that one does not become a doubts 'freak' :-) and so that the doubts don't wreck the success of the project. I think "being doubtful" is the quality which no one will ask you about at the interview :-) but having some healthy pessimism is a good thing nonetheless.

Apache CXF passes JAX-RS 1.0 TCK

2009-06-02T09:35:00.000-07:00

The latest 2.2.2 patch release of Apache CXF is the first one which passes a JAX-RS 1.0 TCK.

It has been a long and rocky road for the CXF JAX-RS implementation. It came quite late into the game, with JAX-RS RI (Jersey), RestEasy, Restlets being already there. Doubts like "why a SOAP stack needs a JAX-RS implementation given that SOA has a new definition now or why duplicate what other JAX-RS implementations have done" combined with the lack of resources didn't help so by the time JAX-RS 1.0 RI (Jersey) was released in the end of last September, CXF JAX-RS was still suffering from some embarrassing bugs :-).

But we hanged on and CXF users started using it and helped us to move to the stage where it was sufficient to fix some edge cases during a 5-days spell to virtually claim a JAX-RS TCK 1.0 compliance.

One might say it is not a big news given that a JAX-RS 1.0 RI (Jersey) was released in the end of last September while RestEasy announced its compliance in January.

In CXF we are still seeing this result as an accomplishment which was only possible due to the fact that users tried it and helped us to push it forward. I'd also like to thank Dan for his support from the very beginning and Jervis Liu for his initial CXF JAX-RS effort.

So in CXF we have the best JAX-WS implementation out there and the JAX-RS implementation is now live and kicking. CXF does and will help users build their SOAs - it does not claim it knows the only definition of SOA. CXF JAX-RS has some interesting extensions and we have some more exciting ones in mind.

So stay tuned and thanks a million to all those who helped and supported us.

Annotation-free services with CXF JAX-RS

2009-05-21T07:26:00.000-07:00

One can hear now and then people saying : "It would it be good if I did not have to add so many annotations to a service class but well...". Many JSR specifications rely seriously on annotations and it does not seem like a reversible process really. Nearly every new enhancement leads to a new annotation type being introduced.

Annotations can be handy, they can save you a ton of time, they can help you with the injection of external resources, they can tell some great external library to do the job for you, they can be great after all. And they also can clutter your code and make it less readable or plain brittle.

Some annotations in Java-based web services frameworks enable Java classes to act as services, notably those defined in JAX-RS and JAX-WS. Here is a typical JAX-RS example :


@Path("/bookstore")
public class BookStore {

@GET
@Path("books/{id}")
@Produces("application/xml")
public Book getBook(@PathParam("id") Long id) {
  return books.get(id);
}

@Path("books/{id}/chapter")
public Chapter getFirstChapterSub(
  @PathParam("id") Long id) {
  return books.get(id).getChapter(1);
}
}

Several annotation such as @Path, @GET, @PathParam and @Produces enable Book and Chapter classes to act as resource and subresource classes respectively.

The JAX-RS specification primarily talks about two main things : which annotations enable a given Java class to act as a service and how to ensure that the expectations expressed through these annotations are met, that is how to dispatch to a given method or populate a given parameter value, etc.

In CXF JAX-RS, we thought of letting users to write services without them having to annotate Java classes for a while and now we have done a first step in this direction, by following an example of the CXF SOAP simple frontend. One can apply an externally defined model instance to an existing resource tree, on either server or client side (proxies) and a CXF JAX-RS runtime will use this model instead of annotations.

One can apply such model in a number of ways.

One can create a number of UserResource beans, each representing either a root or sub-resource resource. For example, one can subclass a UserResource instance and populate it in its @PostConstruct method using some external information. A list of UserResource instances can then either be registered from Spring using a jaxrs:modelBeans child element or programmatically.

Or you can define a model instance either directly in a Spring beans.xml or in an external xml file and link to it, using either a jaxrs:model child element or jaxrs:modelRef attribute .

When using Spring, you often want to proxify a given service bean so we ensured you can use annotation-free proxified beans too.

All options are supported on the client and server sides, for jaxrs:client and jaxrs:server. In the client case it obviously applies to a proxy-based flavor only given that http-centric clients deal with the metadata (such as path, queries, etc) explicitly.

So lets see an example. Here are BookStoreNoAnnotations root resource and ChapterNoAnnotations sub-resource classes. Both classes actually deal with JAXB-annotated beans, ChapterNoAnnotations being one of them, but such beans have been likely generated out of schemas, but even if not, one will not have to go and start coding in JAX-RS annotations if it is what one does not want to do.

In one test we attach an externally defined model instance using this configuration :


<jaxrs:server
address='/thebooks6'
modelRef='classpath:/.../resources/resources.xml'/>

In other one we embed it directly inside jaxrs:server using a jaxrs:model, see this endpoint with id 'bookservice7'. In both cases an HTTP client code can invoke on either BookStoreNoAnnotations#getBook() or ChapterNoAnnotations#getItself(), by going through a BookStoreNoAnnotations#getBookChapter() subresource method first in the latter case.

In model one simply lists all the resource classes which may want to act either as root or subresource classes. The runtime will detect which one acts as a subresource one based on the response type of a given resource method, provided the model defines path but no HTTP verb values for this method.

The model is flexible enough to accommodate for most of the information which is otherwise available from JAX-RS annotations. It is really a combination of 3 simple beans, notably UserResource, UserOperation and Parameter, and they can grow as needed to keep up with the progress of JAX-RS.

Such model can be generated by a UI tool and simple enough to be created using an XML-editing tool.

Note the goal of this CXF extension is give to users more options when a task of enabling a given set of Java classes arises. If you are conscious about writing JAX-RS compliant code such that you can swap JAX-RS implementations under the hood and see your resource working then you will likely want to skip this option.

But then you might want to consider it when a cost of annotating a set of resource classes is deemed to be high. For example, embedding explicit path values using @Path annotations does seem quite brittle - path values and the way one embeds values into them or format requirements may change and now you are faced with the need to recompile. It may or may nor be an isolated and cheap update.

So please think about it, try it and provide the feedback.

By the way, this post can be viewed as a continuation of the previous one.
Actually, I think this approach can work quite nicely once CXF JAX-RS gets embedded in a Distributed OSGi implementation, with some DOSGi users being keen to keep the Java interfaces as transparent as possible.

Standards in web services frameworks

2009-05-14T01:56:00.000-07:00

CXF implements a number of specifications which have been standardized for users be able to write interoperable and indeed portable web service implementations in Java.

Interoperable web service implementations are those which can successfully communicate with web services written in other languages or with the help of alternative Java frameworks.

In the SOAP world it is specifications like WS-Security for example which attempt to describe for what is needed for an interoperable secure multi-hop SOAP conversation to go ahead.

In the REST world it can be the combination of specifications like HTTP, AtomPub, XMLSecurity.

Portable web service implementations are those which can be successfully run on alternative Java web services stacks without their code having to be changed.

JAX-WS and JAX-RS are really those kind of specifications which enable Java implementations to participate in web services interactions as opposed to specifications like WS-Security for example. These specifications make it possible to write portable Java web service implementations.

It is interesting in this regard to comment on the fact that apparently Spring does not implement JAX-RS for example. I think Spring fans simply dont mind - they do care about being able to plug in into the web services world with the help of whatever tools Spring offers to them. Such web service implementations wont be portable but so what given than Spring users are probably not even thinking of leaving Spring ? What matters most is the interoperability.

In addition to those web services standards, there is another kind of healthy standards conflict in CXF : how to enable a certain feature, should it be enabled using the core Spring support or using a CXF specific Spring extension for example.

Many users who understand and like Spring consider using the core Spring support being the only standard way. Some other users are just happy with CXF extensions. For example in CXF JAX-RS, one can use either Spring AOP or CXF specific custom invokers to intercept a method invocation.

The goal of this blog entry is to say is that it is what your favorite framework does can become a standard for you. It is about liking what it does. If you are a Spring fan and do RESTful web services with Spring REST (or whatever it is being called) then it is the standard that works for you. If you are a JAX-RS RI fan then probably you dont mind if some of its features have not been standardized.

In CXF we will think and work on popularizing its own CXF standards, with the main goal, that of helping users writing interoperable and effective web services, being the priority.

CXF JAX-RS XPath provider

2009-05-13T09:42:00.000-07:00

I think writing the code like this is great :


WebClient wc = WebClient.create(endpointAddress);
Book b = 
  wc.get(XMLSource.class).get("/*/book[@name='Bar']", 
        Book.class);

But may be sometimes you may just want


WebClient wc = WebClient.create(endpointAddress);
Book b = wc.get(Book.class);

and still be able to get to the Book named 'Bar' which is part of a larger document.

So a simple XPathProvider reader has been added to CXF, you can use it on either sides by registering it programmatically or from Spring. You can register a unique provider per class by adding an expression and class name pair, or you can have a single provider applying a single expression in all cases or per-class specific expression.

MVC the XML way with CXF JAX-RS

2009-05-07T07:48:00.000-07:00

For some reasons, the 'V' bit in a MVC pattern is often associated by Java users with Java Server Pages (JSP). Personally I've never been a fan of JSP - I don't understand why would users want to mix Java code into HTML pages or pretend they don't do it by spending time on writing tag libraries in Java.

Fortunately, technologies like XSLT and well-known techniques for decoupling the presentation from content exist and in CXF we did a bit of work for users be able to refresh their XML skills and say goodbye to another legacy Java technology which is JSP and never look back.

If you work with CXF and do like JSP then please read on anyway - hope you will appreciate that XSLT (or technology like XQuery) can do the job too. As a side note, even if you won't want to use XSLT for generating HTML pages, in CXF you will be able to use it for generating all types of formats, doing micro-transformation routes by dealing with either legacy (backward-compatibilty) or newer (forward compatibilty) XML requests and responses. With XSLT you can pretty much just produce any format you need, starting from text and ending with RDF - you won't need RDF-specific libraries for it :-)

So we introduced an XSLTJaxbProvider. It's a very flexible provider. You can tell it to transform input or output data (on either client or server sides) . You can specify a stylesheet which will apply to all incoming data, or you can tell the provider to invoke a stylesheet a.xsl for application/xml and b.xsl for application/atom+feed formats. You can also tell it which Java classes are supported : for example, you may want JAXB to directly deal with Book class but you may also want to pre/post transform Book2 XML instances.

For a moment JAXP Templates are used to preprocess/compile XSLT templates and SAX events are used to drive in and out transformations. The base class, JAXBElementProvider does all the work and the XSLT provider only deals with the final marshal/unmarshal invocations by wrapping input or output streams as needed. For the record, JAXBElementProvider has been updated to deal with Stax XMLStreamReaders/Writers which gives yet another option of pre/post transforming the data and we will update the XSLT provider to pick them up, when they're available, which will essentially create 2-level transformation chains.

Template instances will get all the JAX-RS Path template variables, query and last past segment matrix name-value pairs as xsl:param parameters (note : you will only need to declare the parameters you need, in XSLT unused passed-in parameters will be ignored). Additionally UriInfo.getAbsolutePath(), UriInfo.getPath() and UriInfo.getBasePath() will be available as 'absolute.path', 'relative.path' and 'base.path' respectively. We'll update the provider as needed to push more useful information to templates.

If you don't use JAXB but deal with XML then please feel free just to create a custom provider. You'll just probably need to remove the 'extends JAXBElementProvider' bit from a class definition with few other minor updates.

I added a simple system test which shows how to merge the (JAXB-produced) XML into HTML. It's well-known technique, described in articles like

Style-free XSLT stylesheets
Integrating data at runtime with XSLT stylesheets

The idea is not to go the traditional JSP way by combining XSLT instructions and presentation tags into a single source which makes the source unreadable and difficult to maintain. Rather let people who understand how to do proper HTML work on HTML templates, Java developers produce Java code (possibly dealing with either Java classes for JAXB to handle or JAXP Sources ) and those who like XSLT write XSLT templates which sources both presentation HTML and content XML inputs and transforms them as needed. HTML templates have special xml tags which XSLT templates replace with actual data. Trust me, this seperation of roles does work in practice quite well, I can vouch for it based on my previous experience, though I guess we didnt do the complicated stuff - but it worked nonetheless.

Now lets get back to the test. Look at the jaxrs endpoint with 'bookservice5' id. It registers an XSLTJaxbProvider which is told to handle Book classes only and invoke a template.xsl for application/xhtml+xml and template2.xsl for application/xml. (For the record, this endpoint also registers CXF JAX-RS Request/Response filters which install custom Stax stream readers/writers which perform namespace translations - as advised by one of CXF users recently). The provider is also injected with URIResolverImpl, a systemId property is also supported.

The template.xsl template sources in an xhtml template book.xhtml and imports template2.xsl. Thus template2.xsl can be used on its own too. A URIResolver instance registered earlier on takes care of resolving those relative references. Now, the book.xhtml has a special tag books:bookTag which is what a template.xsl reacts upon : the flow is to copy the html tags and pull in the xml content as needed when special tags get encountered. Note that fundamental XSLT style is to do a free flow and rely on matches which makes the templates code much more readable and easier to understand.

In our test we simply copy the whole XML content blob into the resulting HTML, by preprocessing a Book instance as needed (see the imported template2.xsl). Perhaps it would be better to add special tags to book.xhtml corresponding to Book id and Book name, with HTML table tags if needed.

The server test code is in BookStoreSpring.getBookXSLT(). Note that JAX-RS Path, Query and Matrix parameter values are available to template2.xsl, when used on its own or when being imported.

See testGetBookXSLTXml() and testGetBookXSLTHtml() here. Here is the one which extract the Book instance from an HTML document :



WebClient wc = WebClient.create(endpointAddress);
wc.accept("application/xhtml+xml")
.path(666)
.matrix("name2", 2)
.query("name", "Action - ");
XMLSource source = wc.get(XMLSource.class);
Map namespaces = new HashMap();
namespaces.put("xhtml", "http://www.w3.org/1999/xhtml");
Book2 b = source.getNode(
"xhtml:html/xhtml:body/xhtml:ul/xhtml:Book",
namespaces,
Book2.class);

In reality you wont see a Book element in an xhtml namespace though :-)

So it is the XML all the way. I believe it's great fun to be able easily and explicitly control how the XML looks like and to mix a much looser XPath style with the Java code. So give it a try and have fun.

Update. I mentioned above that XSLTJaxbProvider can choose which template to use depending on the media type, such as application/atom+feed for example. Note that even though this provider has static Produces and Consumes values, you can still tell to handle other media types for the runtime to view it as an eligible provider, look at the bean with 'jsonProvider' id on how to overwrite the static Produces and Consumes values on a given message body provider. So for example you can easily tell XSLTJaxbProvider to actually convert a given JAXB-produced XML into JSON by registering an application/json specific template (which will transform XML into JSON) with it and registering application/json as a custom Produces value.

Analysis of CXF RESTful client APIs

2009-04-13T08:09:00.000-07:00

We have recently introduced the CXF RESTful client API for CXF users be able to consume non-SOAP HTTP-based web services at ease. The goal of this blog entry is to compare the three different API flavors CXF offers, discuss the pros and cons of each one, with some occasional off-topic musings :-)

Before I proceed I'd like to acknowledge the fact a Rest Easy JAX-RS implementation offers a proxy-based support in their own client framework. I was not aware of it at a time of introducing the CXF RESTful api but I'm happily doing it now - well done Rest Easy :-). If at least two implementations do a proxy-based API then may be there's a chance we'll get this approach standardized ?

Now, here's the actual comparison of the CXF RESTful apis.

Beautiful Proxies

Proxies have been written off as the main reason behind the brittle client applications having to be recompiled every time a service they consume changes. Others say they epitomize all the problems associated with the rpc-encoded, SOAP-based services. Others would avoid them simply because they're not cool.

Things can be quite different in the reality though and here's why.

Typically, the code which relies on proxies has to be recompiled whenever the service interface changes. These proxies have often been generated from a given service document. The key thing here is that it's actually service interface developers who control how robust the client-side proxies will be.

Whenever a new requirement arises users will often add yet another operation in the interface description instead of extending the data the existing operations operate upon or introducing another interface instead. Read the last sentence again : you should recognize this is how HTTP-based resources cooperate with each other. When a current (service) resource 'exhausts' itself, a new resource is introduced with the previous one delegating to the new one.

So what's it to do with proxies ? Proxies can capture this process remarkably well and with some help from the service interface authors they can weather the changes.


BookDescription desc = new BookDescription();
desc.setId(123);
Book book = BookStore.getBook(desc);
Chapters chapters = book.getChapters();

The rule is simple : design the interface such that a single complex type is accepted and/or returned from a given method. In the above example, when the book description changes it is well likely the client code won't need to be recompiled.

In fact it's likely the service code won't need to be recompiled either. It's ironic that everyone accepts the code like this on the server side, without talking about RPC, for writing say RESTful services :


@Path("/store")
class BookStore {

@GET @PATH("/{id}")
public Book getBook(BookDescription desc) {
}

}

Look - this code can be as brittle as the client code shown earlier on. Just add an integer id instead of BookDescription and then see what happens to this code when you need to retrieve by a book name as well : recompilation to accommodate for a new argument 'String name' or a new operation like getBookByName() in the Java code is a typical answer. Get a complex type instead and both clients and servers will become much more cost-effective when dealing with minor changes. By the way, pay attention to the getBookByName() alternative - it's not the problem of documents like WSDL that such operations pop up - rather it's the absence of single complex types in the signatures that cause them appear in the Java code.

Another thing to recognize in the above server code fragment is that the code which returns a Book serves as a client to a code which expects the Book on the other end. Rather than returning a name this code returns a Book - it's natural but imagine what would've happened to the code on both sides if a name was returned originally but then a new requirement to get the chapters would arise as well...

In fact the server code is often less aware of the fact that the distributed network is out there. With CXF JAXRS proxies you can get all the details of the underlying exceptions if needed and switch easily to their HTTP-centric forms.

When you view the outside web services world through a given proxy you often won't notice a difference between the styles. In fact, sometimes you'll actually see how little substance is there in some of those REST vs SOAP discussions. In my own mind, it's not generic interfaces in REST vs proxies in SOAP. Rather, shortcomings of the individual (WS-*) interfaces are often confused with those of SOAP or blamed on WSDL. In my own mind SOAP suffers from the lack of GET but on the other hand it can get the people agree on how to get messages secured across the hops. REST forces people to think in terms of data as a given resource typically supports a common set of verbs, with SOAP you tunnel everything through POST but nothing prevents you from thinking in terms of data too, with REST you get the support of generic tools like browsers, with SOAP you miss on it but sometimes you probably don't notice it nor WEB does - you're just happy that your application delivers.

With the advent of JAX-RS MessageBody providers, proxies can cope even better with changes to the data. Everyone uses JAXB now because it magically hides the 'complexities' of XML from developers. Sometimes I find it strange though I do use JAXB now and then too. You know what - sometimes it is ok just to write a little bit of XML processing code, web services are about interoperability and XML is the underlying format which can make it possible. But if you do JAXB then you can always interpose an XML-processing JAX-RS provider which will adapt an incoming XML to the one which will be deserialized properly by JAXB. Or perhaps you can just skip JAXB altogether as one of CXF users suggested once.

Proxies based on the JAX-RS Path values with custom regular expressions can serve as early validation points. Proxies in CXF can throw the exceptions you need and can let you examine the actual response headers and easily switch to HTTP-centric clients. Using a given proxy is like exercising a micro Domain-Specific-Language instance.

Proxies and existing JAXRS annotations can coexist very well in most cases. One exception is that @Contexts can not be used as method parameters, it is ok. Another edge case is that when root path annotations with template variables, those sitting on top of the resource class, may (not always) require a client to provide the substitution instances at the proxy creation time.

Would I use them myself. If it were not an infinitely rich data model that my code were to consume then why not ? If I knew I was about to write a code consuming a well-behaving web service which deals with books and clearly documents its extension policies, then why not ? Would it turn my client code into an RPC-encoded piece as opposed to the RESTful one ? I don't know...

The breeze of fresh air : HTTP-centric clients

I have to admit : programming HTTP can be very refreshing, liberating if you wish. You can see it actually works, you know you do the generic interface programming, the code is explicit about gets, updates, deletes. It's new and indeed it's cool.


WebClient wc = WebClient.create("http://bookstore.com");
Response r = wc.get();
Book b = getWithJAXB(resonse.getEntity());

In CXF we saw no reason in introducing the client analogs of Response. When a server code uses Response, clearly it's intended for a client ? It's called 'Response' and one can get the status, headers (metadata) and the entity on either side. Same for other types like WebApplicationException.

I like this http-centric code but I'm still trying to figure out why and when I would actually use it.

First, I think it would be naive to assume using the above code makes it any more reusable than the proxy-based one. It's simply not the case that you can take this code and use against any other Book service out there simply because other services will do something different with a common set of HTTP verbs, or simply will deal with a completely different set, PATCH anyone or WebDav ?

Second, the combination of the generic HTTP code and that of JAXB (suppose a default JAXB provider is used to deal with XML) makes me a bit dizzy - though I like the above code still - may be because it is just something new. Why do we say we write a remote web services code here and yet completely hide away from what makes the fundamental idea behind web services, that of interoperability, work ?


WebClient wc = WebClient.create("http://bookstore.com");
Response r = wc.get();
Book b = getWithJAXB(resonse.getEntity());

Response r = wc.path("/foo/bar").get();
r = wc.back().get();

I do like the way WebClients can switch back and forward when working with a given service, or indeed convert themselves into proxies and back, say when dealing with a large set of services, with proxies being available for a subset of exposed resources. Switching from proxies to WebClients can be handy when handling the remote exceptions.

I like the way Builder pattern. It was obvious we'd need to do the builder pattern given that Jersey does it on the client side - if the client API does get standardized then you know the builder pattern will be there.

There is only one problem with the Builder pattern - you may not actually want to hardcode the wc.path("/foo/bar") into your client code - it's plain brittle. It's a common problem with all those in-code rules, paths, routes - people forget sometimes why they are writing the web service code - to work in the interoperable way as long as possible.

When would I use WebClients ? They'd excel in testing the resources, for sure. It's new and it's fresh. They'd work nicely in combination with proxies, or indeed against the well-behaved services, perhaps embedding explicit paths will work.

Want to be cool ? Use XMLSource

In CXF we have introduced an XMLSource, a light weight utility class for dealing with XPath expressions.


WebClient wc = WebClient.create("http://bookstore.com");
XMLSource source = ws.get(XMLSource.class);
source.setBuffering(true);
Book b1 = source.getNode("/store/book[1]", Book.class);
Book b2 = source.getNode("/store/book[2]", Book.class);
Book[] books = source.getNode("/store/book", Book.class);
URI firstBookLink = source.getLink("/store/book/@href");
// xml:base
URI baseURI = source.getBaseURI();

I do like it. Working with XPath is the best way to write a robust web services code, on either side (note, XMLSource can be used on the server side too as a method input parameter). It does support namespaces too, just pass along a map of prefix to namespace pairs :


WebClient wc = WebClient.create("http://bookstore.com");
XMLSource source = ws.get(XMLSource.class);
Map<String, String> map =
  new HashMap<String, String>();
map.put("ns", "http://books");
Book b1 = source.getNode("/ns:store/ns:book[1]", map, Book.class);

As you know, in XPath, you don't need to match the prefix like 'ns' against the actual prefix which will be on the wire, so the above code will work even if books are qualified with 'bar:', as long as it is "http://books" which that prefix binds to.

At the moment XMLSource uses JAXB but it will support custom XML-aware providers too eventually. One problem with existing JAXP classes like Source is that you can run an XPath expression against a given Source just once really, with XMLSource you can do multiple times against XML instances of small to medium sizes (note that setBuffering(true) call).

We will help users to get back to XML - it's good and very cool to know and understand the technology which underpins the modern web services - so be cool !

Look at it the other way. You are about to start writing a code which will consume one of those Atom-inspired Google services : http://code.google.com/apis/base/starting-out.html. You know what you need to do, XMLSource will make it trivial for you :-)

So that is it for now, and the long story cut short : please use CXF Restful API, choose the flavor you like and help us to improve it.

GET is the real differentiator

2009-03-24T14:28:00.000-07:00

It's been few months since I actually read the posts from the blogs I follow. On Monday I got the chance and I was not disappointed at all :-). A lot of interesting stuff as usual from the likes of Bill D'Ora, etc, etc. Since I started reading the Bill's blog first, I immediately spotted what is it that I can't help avoiding commenting upon.

Bill says in his feedback to a Tim Bray's Name-Value Pairs post, when explaining POST vs PUT differences : "The pro-REST answer is to use PUT". Now, there's more context in Bill's post, but this statement which finally sent a message to me, though may be not the intended one.

I'd rephrase this phrase like this : "The HTTP Programmer's answer is to use PUT (in certain conditions)". This is what it is. REST is not about stating that PUT has to be used, rather it's an interface design question for a given HTTP service resource whether it's PUT or POST which is used. I think it only adds to the confusion as to what REST is about when people say the RESTful way is to do PUT and DELETE as opposed to say doing updates with POST.

After reading Tim Bray's post I found another interesting one. I don't think REST practitioners will start switching to just GET and POST. But it's good to see some clarifications in this area from the experts.

I browsed through some of my old posts, here're some related ones :
My Simple WEB and One For Reads Many For Writes

CXF JAXRS Client API updates

2009-02-26T09:11:00.000-08:00

We've been working on improving the initial Client API prototype we had added to CXF. Particularly, the goal was to tap a bit into a powerful CXF core runtime which gives us interceptor chains and a highly optimized HTTPConduit.

I was overwhelmed with how many options CXF JAXWS client runtime had for all sorts of invocations, asynchronous ones, one ways, synchronous ones with retries, automatic processing of cases where a destination has been moved to a new address, secure HTTPS invocations, etc. So CXF JAXRS client runtime will eventually end up being as flexible and configurable as its JAXWS 'brother' (hopefully, if you're completely into REST then this analogy does not shock you too much :-)).

With CXF 2.2 coming out soon I didn't have time to update the CXF JAXRS client code to do all the things CXF JAXWS can do - this will gradually be done later on. But few key things have been done, mainly it's now possible for both proxy and http-centric CXF JAXRS clients to transparently pick up the CXF Bus configuration, rely on the HTTPConduit which deals with all the complicated HTTP stuff (chunking, http proxies, timeouts, etc), as well as custom outbound and inbound CXF interceptors.
One interesting thing about it is that you can now basically reuse in certain cases, say, secure JAXWS and JAXRS proxies (with the HTTPS-related configuration being picked up from Spring) and you can always find out what type of proxy you're dealing with :



BookService jaxwsService = ...
BookService jaxrsService = ...
useBookService(jaxwsService);
useBookService(jaxrsService);

if (WebClient.client(jaxwsService) == null) {
// it's a jaxws client
}

For example, see this JAXRS HTTPS test which does a secure invocation with both proxy and http-centric clients. Note how straightforward it is. Actually that needs to be simplified, with a CXF Bus creation code to be pushed into a JAXRSClientFactoryBean - but you can do it right now by simply passing a command line CXF property pointing to a configuration code with the bus creation code becoming redundant.

The actual simple configuration is here, it configures both client and server sides.

Another interesting thing is that we can now inject JAXRS proxies into the server service code, be it JAXWS or JAXRS one. For example, have a look at this test resource class which can serve both JAXRS and JAXWS invocations. JAXRS proxy is injected like this :


public class BookStoteSoapRestImpl {
 @Resource(name="rectClient")
 private BookStoreJaxrsJaxws webClient;
}

and then it's used inside a getBook() method, irrespectively of whether it's a jaxws or jaxrs invocation which is inderway, by invoking the same method :


public class BookStoteSoapRestImpl {
    public Book getBook(Long id) {
        // if it's not a recursive invocation then
        webClient.getBook();
    }
}

Now the invocation goes over HTTP in this case but we'll add the support for local transport invocations too.

Please check this configuration sample on how a jaxrs:client is configured. Among other things you can setup all the headers which need to flow, plus input/output interceptors and whether subresource proxies if any need to inherit the headers. I'll also add a support for a basic autorization here as opposed to doing it at the Client level, as one really needs to do it in combination with HTTPS.

You can also inject jaxws:clients into your JAXRS endpoints if you wish. REST and SOAP united indeed.

So that's what happening with CXF JAXRS Client API. More enhancements will be done to it, to its proxy, http- and xml-centric parts and the way it integrates with the core runtime.

Stay tuned.

CXF JAXRS in Camel

2009-02-26T06:24:00.000-08:00

My colleague William Tam has spent some of his time on Camel providing the support for CXF JAXRS consumers, which is much appreciated.

The way William did it is very nice in that JAXWS will eventually be supported too, using the same high-level route definition. What is also good is that no strange queries like ?httpverb=POST will have to specified in routes, as in case of other Camel components consuming HTTP requests.

Here's a basic example (courtesy of William) :

from("jetty:http://localhost:9000?matchOnUriPrefix")
.to("cxfbean:serviceBean")

where 'serviceBean' is an identifier for a resource class bean under which it's also been registered in a Camel service registry.

With CXF 2.0 being released soon we have a client api support coming out too, which will make it possible to add cxf jaxrs producers calling out to external services, we'll make sure it goes into a Camel 2.0 final release.

I'd encourage someone from a Mule community to add support for CXF JAXRS routes too, perhaps by combining it somehow with the existing Mule CXF JAXWS routes.

FAQ : Why CXF implements JAXRS

2009-02-19T14:07:00.000-08:00

A number of people have asked us why, or why, do we spend the time on implementing JAXRS in CXF, despite the brilliance of existing third-party implementations, with all the resources and big names support behind them.

The answer is quite simple actually. We're not hell-bent on trying to emulate what others have done, nor are we into some kind of JAXRS 'battle' - not yet anyway. We aim for a 'simpler' goal which is to make sure CXF is seen as the best of breeds platform for developers writing web services. We won't tell them they have to write REST services - we'll trust their choice and ensure CXF will handle most demanding requirements, whether it SOAP, REST or both.

CXF is being recognized now as a top platform for writing SOAP services - highly optimized, tried and tested. There were times it was beginning its life with writing JAXWS from scratch and people, myself including were asking why. It was quite a bit of time ago though, and no one asks such questions any more. CXF JAXWS is just going to get stronger, it' s happening every day. IONA trusted in those few involved in the early CXF work to pull it off and that trust payed off.

So here we're, tinkering with the CXF JAXRS implementation. Odds are not that terrific for now but we'll persevere and see what happens. We continue trust in our experience and we'll get to the final destination eventually. And when we do we won't mind if a fledgling CXF JAXRS will get off the ground on its own...

The bottom line is that we do see JAXRS as a very important technology for CXF. CXF is not a pure SOAP stack anymore. It's a progressive framework where all sorts of services will coexist.

Have fun

CXF JAXRS Client API Preview

2009-02-13T12:59:00.000-08:00

We've worked very hard recently on prototyping the client API for CXF JAXRS. We've tried our best to come up with something which will offer at least something new. It has not been easy but hopefully you'll acknowledge some differences. So without further ado here's the first overview of the CXF JAXRS Client API.

The proxies : design your resource classes and use them everywhere.

Proxy-based API is very familiar to CXF JAXWS users. As I've mentioned a number of times before it's our top priority to ensure JAXWS users can start playing with RESTful services similarly to how they do it with SOAP services. I can already hear people saying - sure, that RPC stuff is here again - but hold one please, proxy-based API can be made quite robust and I will dedicate a separate post to the comparison of different forms of client API that CXF JAXRS supports and talk about their pros and cons. And you know what, CXF JAXRS proxies are http-centric too. So here are some examples for a start.


  ProviderFactory.getInstance().register(
       new ResponseToBookNotFoundMapper());
  String base = "http://localhost";
  BookInterface bp = JAXRSClientFactory.create(base,
                                     BookInterface.class);
  try {
       Book b = bp.getBook(123);
  } catch (BookNotFound ex) {}
  BookSubresource bs = b.getSubresource(1, 2);
  bs.getBooks();

BookInterface and BookSubresource are proxies created by JAXRSClientFactory. You've already spent some time designing your service resource classes - no need to do it again for a client side. Proxies 'navigate' with the help of JAXRS annotations and do the remote invocations. The power of UriBuilder makes the replacement of URI template variables along the way quite straightforward really. All the JAXRS parameter annotations are handled such that the receiving end will work as expected : path, query and matrix parameters will find its way into a resulting URI while HttpHeader and Cookie will go to request headers.

The values will be encoded by default unless Encoded annotation is available - if you do plan to decode yourself then it's reasonable to expect you encode yourself in such cases.

FormParams and MultivaluedMap parameters are handled like any other parameters representing a request body - they're serialized with the help of JAXRS MessageBodyWriters. Likewise, return values are handled by JAXRS MessageBodyReaders.
Registered ResponseExceptionMappers will be given a chance to handle exceptional JAXRS Responses, othewise JAXRS WebApplicationException containing the Response will be thrown.

Consumes and Produces values control Content-Type and Accept headers.

Note that in the above example the root proxy is created on an interface. It might not always be possible to refactor your resource class to get the JAXRS annotations inherited from an interface. No worries, CGLIB proxies will be created in such cases, for root and sub-resource classes - you'll just need to be a little bit careful and avoid doing some initialization with side effects in default constructors.

With proxies you can't have Context parameters in your method signatures - but may be it's a good thing indeed. You can't also have Objects returned as sub-resource instances - I know JAXRS lets you do it and indeed it's a great way to test how well the dynamic resolution on sub-resources works :-), but it's Java afterall :-), not a big deal I think.

Proxies are HTTP clients

Every proxy is Client which represents the common capabilities for both proxy and http-centric clients. JAXRSClientFactory has few methods for common cases when headers need to be customized but here's how you can control what the proxy sends and receives :


BookProxy ps = JAXRSClientFactory.create(uri);
WebClient.client(ps).type("text/xml").accept(text/xml)
  .modified(date, false);
Book b = ps.getBook();
if (b == null) {
  Response r = WebClient.client(ps).getResponse();
  if (r.getStatus() == 204) {
      // check what the story is with
      // the http-centric client
      WebClient wc =
        new WebClient(WebClient.client(ps), true);
      Response r2 = wc.get();
      // create a new proxy now
      BookProxy ps2 =
         JAXRSClientProxy.fromClient(wc, true);
      assertEquals(
         WebClient.client(ps).getCurrentURI(),
         WebClient.client(ps2).getCurrentURI())
  }
}

The headers set explicitly will be chosen instead of those derived from Consumes and Provides (for Content-Type and Accept). If no information is available then most likely application/xml will be set - after all, it's all mostly about XML services.
The code above also shows few more details. If Book instance is null then most likely the conditional GET has worked but we'd like to do more checks just in case, first by checking the actual Response and then using a WebClient http centric client which is initialized with our proxy's current URI and existing headers. Then we create a new proxy from a WebClient instance by inheriting its headers too.

HTTP-centric clients

WebClient represents HTTP-centric clients. I do think it's unfortunate we have no standard client API. We tried to apply the same builder pattern used by JAXRS ResponseBuilder. All the header-related methods have been done after checking the section 14 of HTTP 1.1, plus JAXRS JAXRS HttpHeaders and ResponseBuilder. Here are some examples.


  WebClient wc = new WebClient("http://foo");
  WebClient wc2 = new WebClient(wc.getBaseURI());
  Response r = wc2.accept("text/plain").get();
  Response r = wc2.post(new Book());
  Book b = wc2.get(Book.class);
  Book b2 = wc2.invoke("myhttpmethod",
                                       body, Book.class);
  //etc

You can get a Response or a typed object, you choose. WebClient is a Client, but the builder pattern works thanks to the covariance support.

WebClient acts like a browser



WebClient wc = new WebClient("http://foo");
// submit form to http://foo/bar/foo/baz
wc.path("bar").path("foo/baz").
     form(new Form().set("a", "b")
                                    .set("c", "d"));
wc.back();
assert(wc.getCurrentURI(),
            "http://foo/bar/foo");
// get back to base URI
wc.back(fast);

assert(wc.getCurrentURI(),
            "http://foo");

wc.to("http://newhost");

The power of XPath and XSLT

Sometimes you just need to look into a resulting XML, either when dealing with unexpected changes or when retrieving a subnode. So we've gone ahead and created a utility class XMLSource, to be optimized and enhanced later. You'll be able to easily get to a required XML piece in a number of ways, initial example :


XMLSource xs = new XMLSource(
    (InputStream)client.get().getEntity());
Book b = xs.getNode("/books/book[1]", Book.class);

There are quite a few more things to say about what we have but I guess it's enough for now.
It's not yet finished at all - stay tuned for more updates. And we'd welcome a lot any constructive feedback - please send the comments to CXF lists or comment here or contact me directly.

And yes - thanks to JAXRS and RI (Jersey) for being innovative and inspiring.

Enjoy.

JAXRS Spring Security Demo in Fuse

2009-02-05T03:11:00.000-08:00

We've recently added a Spring Security JAXRS demo to our Fuse Service Framework distributions covering both 2.1 and 2.2 lines.

Spring Security is powerful indeed. The demo shows how easily one can secure JAXRS resource classes, those derived from interfaces and those which are plain classes and are wrapped by CGLIB proxies, with or without applying dedicated security annotations to individual resource methods.

You need to create an account in order to see the source of the demo. I hope you can appreciate why we added the demo to Fuse : we intend to continue raising the awareness of Fuse. This demo will be regularly tested by our CPI process which is based on Xharness.

You can also get the idea of what the demo does by checking the system tests in CXF trunks on Apache. In fact the system tests evolved a bit since the demo was created, they show how subresource methods can be controlled too, with subresource instances being injected Spring proxies themselves.

Hopefully though the perceived initial inconvenience to do with the account activation :-) will be compensated by the fact that you're likely to find some information of interest on everything which is happening in the Fuse world and may decide to get back again :-)

New CXF SubProject : Distributed OSGI RI

2009-02-04T13:25:00.000-08:00

Apache CXF has recently had a new subproject created which hosts a Distributed OSGI Reference Implementation.

David Bosschaert and Eric Newcomer have already posted about it.

I'd like to add few comments.

I think in the todays software world it's not easy to innovate and it's a great achievement indeed for Eric, David, Tim Diekman, Eoghan Glynn and all the folks from various companies who worked very hard and have contributed to the DOSGI-related efforts.

Don't get discouraged by the RPC-ishness of DOSGI - if you do then I recommend you to read this very convincing post.

I do hope to plugin the CXF JAXRS implementation into a DOSGI RI. It's a topic for a separate post, but one can write a perfectly restful yet capable of surviving the changes client code which relies on proxies.

While DOSGI will be perfect for OSGI developers, it will also attract those who are primarily after the promise of OSGI containers to replace modules on the fly in a predictable way - this is one of the reasons people might want to play with DOSGI even though today they may do fine without it.

When a given DOSGI server module will get replaced it would be ideal for the active incoming client requests not to be lost or for clients to get helpful error messages. OSGI can help here. Hopefully future versions of DOSGI will address this fundamental issue. Perhaps we can expect a dedicated (OSGI) service be introduced which will process the pending messages as needed, by either replying properly or saving them to some storage while a given service implementation or a DOSGI bundle itself get replaced.

You can expect a lot of features from DOSGI RI which sits on top of WS-Policy aware CXF runtime.

Please give it a try, contribute and provide some feedback and enjoy playing with this new and cool technology.

Multiparts in CXF JAXRS

2009-02-02T08:28:00.000-08:00

We've just had CXF JAXRS updated to deal with multiparts. Multipart/related, multipart/alternative, multipart/mixed and multipart/form-data are supported at the moment.

The reason I've decided to blog about it is that I was fascinated how little work I had actually to do to make it all happen. CXF JAXRS sits on top of the robust CXF runtime core component, which, among other things, has a great support for (de)serializing multipart requests, with the ability for attachments exceeding a given configurable memory threshold be saved into a configurable directory.

A number of options is available for developers wishing to handle multipart requests. First we tried to make sure that JAXWS users trying JAXRS can reuse the same code they use when dealing with attachments in JAXWS. Particularly, one can get a root attachment bound to a method parameter, while the subordinate ones can later be retrieved for further processing :


public class Resource {
@Context 
private MessageContext cxfJaxrsContext;

 @POST
 @Path("/")
 public void handle(StreamSource root) {
   // check the root one...
   // get to the rest of them
   Map<String, DataHandler> parts = 
       AttachmentUtils.getChildAttachmentsAsMap(mc);
   handleParts(parts);
 }
}

The root attachment can be bound to any type which can be supported by registered providers :


public class Resource {
@Context 
private MessageContext cxfJaxrsContext;

 @POST
 @Path("/")
 public void handle(JaxbBook book) {
   // book represents the root one
   List<Attachment> parts =  AttachmentUtils.getChildAttachments(mc);
 }

 @POST
 @Path("/")
 public void handle2(JSONBook book) {
   // book represents the root one
   List<Attachment> parts =  AttachmentUtils.getChildAttachments(mc);
 }

 @POST
 @Path("/")
 public void handle3(MultipartBody body) {
   Attachment a = body.getRootAttachment();
   List<Attachment> parts =  body.getChildAttachments();
 } 

 @POST
 @Path("/")
 public void handle4(List<InputStream> all) {
 }

 @POST
 @Path("/")
 public void handle5() {
    Attachment a = AttachmentUtils.getRootAttachment(mc);
    List<Attachment> parts =  AttachmentUtils.getChildAttachments(mc);
    AttachmentUtils.getAllAttachments(mc);
 }
}

One can address individual parts like this :


public class Resource {
@Context 
private MessageContext cxfJaxrsContext;

 @POST
 @Path("/")
 public void handle(@Multipart(value="id1", 
                    type="application/json") JSONBook book, 
                    @Multipart(value="id2") JaxbBook book) {
   
 }
}

For multipart/form-data, FormParams can be used to bind to individual parts representing form fields. MultipartMap is supported. One limitation at the moment is that with multipart/form-data, parts can only be bound to Strings (which can further be processed as per the JAXRS parameter handling rules if FormParam is used, with CXF JAXRS ParameterHandler being of likely help here). Thus if one wants to upload files then at the moment one needs to use MultipartBody and do some custom processing :


public class Resource {

 @POST
 @Path("/")
 @Consumes("multipart/form-data")
 public void handle(MultipartBody body) {
     // presumes the part has a content id
     Attachment a = body.getAttachmentById("file");  
     ContentDisposition cd = a.getContentDisposition();
     InputStream is = a.getDataHandler().getInputStream();
     // proceed
 }
}

Configuring the attachments directories and memory thresholds can be done on a per jaxrs:endpoint from Spring, setting corresponding bean properties on a CXF JAXRS provider dealing with multiparts. Or you can do it from your code if you wish :


public class Resource {

 @POST
 @Path("/")
 public void handle() {
     List<Attachment> all = 
         AttachmentUtils.getAllAttachments(mc, 
                                           "/tmp", "589678")
 }
}

Outbound attachments will also be supported. Give it a go and let us know what you think.

Managing contexts in CXF JAXRS

2008-12-17T03:51:00.000-08:00

In JAXRS, a number of classes representing various features of a given request exist, as opposed to a composite WebServiceContext in JAXWS which lets get to individual contexts and message properties.

Imagine this JAXRS resource class which needs to know where the request came from, how secure it is, what the structure of the request URI is, what servlet context parameters corresponding to a given request are, what HTTP headers are involved and if certain request preconditions are met. And if you're writing a composite message body provider then, in addition to the above requirements, you also want to query other available providers as well as to check if a certain context resolver is available.

How unreatistic these requirements are ? It's likely they won't arise in many cases at the same time but likewise it's likely they'll will have to be met in some cases.

So here's a portable JAXRS code showing how you can get an access to all the contexts :


public class CompositeMessageReader
  implements MessageBodyReader<Composite> {

  @Context UriInfo u;
  @Context SecurityContext sc;
  @Context HttpHeaders  h;
  @Context Request r;
  @Context ServletContext sc;
  @Context HttpServletRequest httpR;
  @Context ContextResolver contextR;

  // use the injected contexts

}

And here's a CXF JAXRS specific code on how you can get an access to all the contexts plus the properties of the underlying message.


public class CompositeMessageReader
  implements MessageBodyReader<Composite> {

  @Context org.apache.cxf.jaxrs.ext.MessageContext mc;
  // use the injected contexts
  mc.getSecurityContext();
  mc.getHttpHeaders();
  mc.getUriInfo();
  mc.getContextResolver(JAXBContext.class)
  mc.getRequest();
  mc.getServletContext();
  mc.getServletConfig();
  mc.getHttpServletRequest();
  mc.getHttpServletResponse();

  FutureJAXRSContext newContext =
      mc.getContext(FutureJAXRSContext.class);

  mc.get(PROPERTY_KEY);

}

I'm contradicting here to my previous post where I'm whining :-) about the JAXRS portability.
But you know how long would it take you to get back to a portable JAXRS code.

JAXRS Wish List

2008-12-17T03:22:00.000-08:00

I think I won't say anything new by repeating that a JAXRS specification has been a success.

It brings so many new annotations into a Java code but the main goal behind it, at least as far I see was to popularize the REST paradigm among java developers and surely, the goal has been achieved.

Marc Hadley, Paul Sandoz and indeed all the experts who contributed to the JAXRS specification have done a fantastic job. And no doubts more is to come from newer versions of JAXRS.

So here's my wish list. It's not a long one. May be it's a bit early given that JAXRS 1.0 was only released last September but here it goes :

Please focus on the Portability.
There's no uniform way to express that a given service class is a singleton. There's no portable client api - why is that ? In JAXWS one can do a portable code which creates and consumes services. There's no uniform way to query for a document describing a service.

That's it really - not a long list indeed :-)

CXF JAXRS Keeps Getting Better

2008-12-09T13:03:00.000-08:00

I could not resist it, even though I'm not a Christina Aguilera's fan :-)

CXF JAXRS is catching up. Jersey is an extremely strong player, and I have little doubt about the top quality of other JAXRS implementations - but their CXF competitor has something to say on its own - right now.

CXF is there to offer a number of approaches toward building serious web services. The fusion of JAXWS and JAXRS is likely to appeal to many developers and this is just one of the areas where CXF JAXRS can play its part.

Stay tuned.

Continuations in CXF

2008-12-01T13:43:00.000-08:00

It's a classic problem really, how a service can help a client to submit a request and obtain a response asynchronously. A number of approaches exist :

* Client does an invocation on a web service and provides an address to reply to - this requires a client to have a web service of its own for the callback to eventually arrive while on the server side, for the (HTTP) transport thread be released, a typical HTTP 201 may be sent back as an initial acknowledgement, depending on if it's a typical two-way or so-called one way operation.

* Service responds with a resource address a client needs to poll for the results be eventually obtained which requires a client to structure the code accordingly.

There's another approach emerging - using suspended invocations or continuations. Actually, it's not a new approach but with Jetty supporting and Servlet 3 embracing them the suspended invocations are bound to enter the mainstream.

Please read a Jetty Continuations page on when using continuations can make sense.

Without further ado, here's a sample code fragment showing how one can do continuations in CXF in a transport neutral way. CXF Continuations API is currently supported for SOAP-HTTP services based on Jetty 6 and SOAP-JMS services. CXF JAXRS runtime supports them too :



import org.apache.cxf.jaxrs.ext.MessageContext;

@Path("/")
public class WebResource {

 private @Context MessageContext context;
 private Executor executor = ...;

 @GET @PATH("/quote/{id}")
 public Quote getQuote(@PathParam("id") String policyId) {

  String key = 
   "org.apache.cxf.continuations.ContinuationProvider";
  ContinuationProvider provider = context.get(key);

  Continuation c = provider.getContinuation();
  synchronized (c) {
       if (c.isNew()) {
          FutureTask f = new FutureTask(
             new  CallablePolicyHandler(policyId, c));
          c.setUserObject(f);
          executor.execute(f);
          c.suspend(timeout);
       } else {
        FutureTask f = (FutureTask)c.getUserObject();
        if (f.done())  {
          return f.get();
        }
        c.suspend(decreaseTimeout());
       }
     }
   }
}

What happens is that when continuation.suspend(timeout) is called, the current transport thread gets immediately released and a pending request is put back in the requests queue. Once an asynchronous activity gets completed, it will call continuation.resume() - in this example it's done somewhere inside a CallablePolicyHandler, which results in a suspended request be returned to this method. The code now checks if the FutureTask is done and if not then it means an initial timeout was not enough for the asynchronous activity to complete - in this specific case we decide to suspend a request yet again but with a smaller timeout.

Note that in case of JAXWS the code will be absolutely identical for this specific sample, except that a ContinuationProvider instance will have to be obtained from a JAXWS WebServiceContext.getMessageContext().

Both CXF JAXRS MessageContext and JAXWS MessageContext will have to be used when combining JAXWS and JAXRS. I think we may need to come up with a common MessageContext interface for such cases.

Finally, this CXF Continuations API won't change when Jetty 7 (and indeed Tomcat) implementing Servlet 3 specification will ship.

For another example see this CXF-based demo in a Jetty 7 trunk. It shows the use of JAXWS asynchronous handlers among other things. Note in this demo a new ServletRequest.suspend() call is used as opposed to ContinuationsSupport.getContinuation() and Continuation.suspend() pair of calls in Jetty 6. Nothing to worry about though if you're a CXF Continuations API user - it all will be handled internally without you noticing it.

Portugal

2008-11-06T14:48:00.000-08:00

Here are some photos from our trip to Portugal, it was a great trip.

Pragmatic message about REST

2008-11-04T13:38:00.000-08:00

Sam Ruby says in his Progressive Disclosure post :

"Without intending to take anything away from Roy’s (valid) criticism on labeling, REST isn’t an all or nothing proposition. One can get significant value from partial adoption."

IMHO this message is much stronger and much more likely to be heard in the SOAP quarters than the "drop WS, adopt REST" message. For the latter message to (ever) get mostly if not fully materialized, the former needs to be heard well.

+1.

Indeed, Apache CXF preaches this message too with its best-of-breed JAX-WS support and its fledgling but being constantly improved JAX-RS support, now supporting 1.0 API with just few exceptions.

On How to Get a Cup of Coffee

2008-11-04T12:40:00.000-08:00

InfoQ has recently published a How To Get a Cup of Coffee article about RESTful services.

I did like reading the article : it talks about workflows, shows with the help of state diagrams how clients actually drive and execute applications and overall it entertains the reader so I'd like to join those who welcomed this article. It was the only technical article I read last week, on vacation, and I was nearly killed when I was spotted reading it :-)

What surprised me a bit though is what the authors say about clients discovering which method, say PUT which may be invoked on a given resource service. For example :

"to find out if we can change the order, we ask the resource what operations it's prepared to process using the HTTP OPTIONS verb, as shown on the wire in Figure 6." - please refer to the original article to see Figure 6.

Next :

"From Figure 6 we see that the resource is readable (it supports GET) and it's updatable (it supports PUT)."

I think this use of OPTIONS is of no practical use at all. I agree it does show what OPTIONS can be used for but I find it difficult to imagine a compiled client code checking how a given resource can be updated, especially given what is said next in the article :

"Although partial updates are the subject of deep philosophical debates within the REST community, we take a pragmatic approach" and (authors) decide to use PUT to do a partial update. Big +1 on the pragmatic approach by the way.

In meantime Mark Nottingham provides some insightful comments but again this comment on the use of PUT for partial updates catches my attention :

"This is a flagrant abuse of the semantics of PUT; if you want to combine a representation with the existing state of the resource, use POST or the emerging PATCH. "

To me it all means only one thing : the RESTful HTTP-aware compiled client code is as tightly coupled to a given resource with a generic HTTP interface as the client code generated from either WSDL or WADL is. One service will use PUT, the other one will do POST and the 3rd one will use PATCH - but the knowledge of the verb to be used when doing a given type of update is embedded in the client application code - unless it's a totally generic client application, say a browser handling HTML forms.

Here's one more excerpt from the article.

"Consumers typically agree the semantics of representations and transitions with a service during design and development. But there's no guarantee that as service evolves, it won't confront the client with state representations and transitions the client had never anticipated but knows how to process – that's the nature of the loosely coupled Web. Reaching agreement on resource formats and representations under these circumstances is, however, outside the scope of this article."

I'm curious what can be said about reaching agreements under these circumstances ? I'm seeing the client codes being recompiled in these cases if the newly introduced data or semantically important links are to be noticed.

Football : Belarus vs England

2008-10-17T06:56:00.001-07:00

Belarus played versus England on Wednesday 15th of October and lost 1 : 3. Even though I was disappointed they did not manage to draw or even win, I was still encouraged by quite positive reviews of the way Belarus played.

They managed to get level after losing 0:1 and who knows what could have happened if Rooney hadn't rediscovered his lethal attacking skills by the time this campaign started.

I was on a plane when the match was on, but I have it recorded. The only thing which concerns me a bit is that my (soon to be) 6 year-old son Alex is getting crazy about football at the moment and he's so excited about watching Rooney playing. I'm concerned that if I show him this match he'll start supporting England even when they play Belarus :-) May be I should wait and see if Belarus manages to shock England in the away game :-)

Slightly orthogonal note : BATE, a football club from Borisov, a small town near Minsk, is playing in the Champions League this season. In fact, it's the first ever club from Belarus which managed to achieve it. And they play Real Madrid (0:2 - in their 1st meeting in Madrid), Juventus (2:2 in Minsk) and Zenit St Petersburg (1:1 - away). Well done - great effort and it brings that much needed experience and indeed finances into the Belarussian football.

Fixing capitalism with the open source

2008-09-02T04:58:00.001-07:00

I never thought I'd write about capitalism on this blog :-)

So I was flying to Minsk the other day and I was about to enjoy my holidays at home. While my fellow passengers were reading the home newspapers, I was reading an article by Bill Gates "How to fix capitalism" published by "Time". I knew I was looking a bit pretentious :-) at a time, but it was an interesting read. I picked up my copy of Time in the Dublin airport for the only reason - Bill Gates was looking at me from the front page. Actually, the article is called differently online, not sure why, possibly because 'fixing' sounds a bit strong to some hard-core capitalists :-).

That article is a brief and concise guide on how businesses can help those in great need and still make money out of it. For someone like myself knowing not much about how the business is really made it was quite an inspiring read - I was flying high - literally :-) at that moment of time and I was imagining myself doing some strategic business decisions which would make the world a better place.

Like the way the open source movement is affecting the way the business is made in the software industry, it's likely what Bill Gates wrote about will affect the way the business is made in general, sooner or later. Customers will prefer to buy from producers who are known to be associated with good causes.

The open source business model is primarily based on the promise that once the ubiquity is reached there will always be customers which would prefer to buy a certified version of the open-source product, that is, pay for the top-class support.

The open source, by definition, is free and it's being doing well in making capitalism more creative by lowering the cost of entry for those who need to write functioning applications fast. Not everyone who is using the open source software is in great need but those who really are can certainly avail of the freely available software.

And it's likely that customers will eventually reward vendors who're investing in the open source - simply because the open-source vendors will be seen as the ones who are associated with the good cause.

Rest and Soap united in CXF

2008-07-25T09:08:00.000-07:00

Please ignore the fact that Rest and Soap are presented as two alternatives - even though it's not very accurate this just helps me to make a shorter title for this blog entry.

I was quite interested in a 'Restifying' SOAP-based services idea awhile back, especially after a Web Method Feature was introduced. I'm not sure anyone relies on it today, when writing practical SOAP-based web services - I just don't know.

The arrival of JAX-RS introduces some new interesting possibilities in this area - from the perspective of the server-side application development at least.

Consider the ever popular Bank-Account scenario which uses a Factory pattern.
Here's a typical JAX-WS class :

@WebService
public class BankService {

public javax.xml.ws.wsaddressing.W3CEndpointReference createAccount(AccountInfo ai) {
// code omitted for brevity
}
}

This class will return EPRs, one per every new Account created.

Now consider the same class slightly updated :

@WebService(wsdlLocation="bank.wsdl")
@Path("/bank")
public class BankService {

@POST
public javax.xml.ws.wsaddressing.W3CEndpointReference createAccount(AccountInfo ai) {
// code omitted for brevity
}
}

It is the same class with JAX-WS and JAX-RS annotations mixed in.

In case of SOAP, POST createAccount requests will be targeted to, say, http://localhost:8080/bankservice endpoint address, while in the other case POST requests will be targeted to http://localhost:8080/bank address.

The only missing bit is a JAX-RS MessageBodyWriter which can handle the handling of W3CEndpointReferences :

public class W3cMessageBodyWriter {

public void writeTo(W3CEndpointReference epr, ..., MutivaluedMap<String, Object> headers, OutputStream os) {
// just update the headers, do not write into the stream
headers.putSingle("Location", getEprAddress(epr));
}

}

Now, the problem is that status code needs to be set to 201 in this case and it's not possible to set a custom http status code in JAX-RS MessageBodyWriters. Enter CXF JAX-RS filters. They will be invoked before the headers and status code is set on a CXF private Message class :

public class EprResponseHandler implements ResponseHandler {
public Response handleResponse(Message m,
OperationResourceInfo invokedOperation,
Response response) {
Object entity = response.getEntity();
if (entity != null
&& W3CEndpointReference.class.isAssignableFrom(entity)) {
return Response.created(getEndpointAddress(entity)).build();
} else {
return null;
}
}
}

Note, the need for a custom MessageBodyWriter goes away now.

Finally, one needs to configure both JAX-WS and JAX-RS endpoints using Spring for ex, and you're done.

A couple of additional notes. There's really no need to go for all this trouble of creating custom filters unless you'd like to preserve the same interface you've already used before starting to play with JAX-RS - this may not be that far-fetched a requirement at all. And sorry for writing a lame and incomplete code - hopefully it still makes sense :-)

Finally, note how very similar the programming model on the server can be, when using both JAX-WS and JAX-RS. Big Web Services are often compared to Corba for a number of reasons, one of them the use of EPRs - this is definitely a red-herring. It's the non-support for GET and fine-grained interfaces which put the sides apart.

A RESTful Core for Web-like Application Flexibility

2008-07-25T08:32:00.000-07:00

I spotted a RESTful Core for Web-like Application Flexibility article on the ServerSide.

Please read it.

I was musing a bit about the universal web programming in a couple of previous posts, using an "if REST approach is considered so appealing to the web application developers then why don't we just have the generic interfaces even in the local JVM" kind of argument, without any practical suggestions.

Looks like some clever people are after it - and my take on it is that it's just a matter of time before we'll see a new programming language, say, W#, pronounced as 'Web Sharp'. It will come out from Microsoft or Sun or IBM or Google or indeed from 1060 Research labs. I don't see how this would be W# language ever replace Java , but I have little doubt it will be unveiled eventually.

The authors do not propose to replace, say, a java.util.List interface with a more generic version such that a client code is never even compiled against a fine-grained interface. Given that what they write is considered 'extreme' by some of the readers of their article, deprecating the whole notion of the interface is not a starter even in the nearest longer future :-) What the authors propose seems like an interesting and promising idea, of some moderate 'extreme' :-).

Interesting stuff.

Is it all about agreement ?

2008-07-15T13:31:00.000-07:00

I remember reading one of the Mark Little's posts (sorry can't find the link) where he was saying that, yes, it was possible to write transactions in REST, in fact he'd even had some practical experience in that area before.
Yes, while I don't have such experience I know now how I can do it now with REST.

Then Mark said that a number of partners had managed to demonstrate the interoperability of one of WS-* Transaction specification as part of some of the interoperability events.

This makes me wonder : is it what actually defines Web Services ? Not only the actual technology per se but the fact that multiple businesses can do the same technology and successfully interoperate ?

Will it ever happen with RESTful services ? Will it be possible for multiple companies to interoperate with more sophisticated things involved such as transactions, for ex, something which is possible to do with WS-BusinessActivity which does not really lock all involved ?

Or is it something which will not be ever needed in practice ? Local transactions, different business alliance-specific standards is all what will be needed to either just do transactions or achieve the interoperability in say the transactions area ?

About the 10 year plan

2008-07-15T13:05:00.000-07:00

Through Stefan Titkov I came across this comment by Benjamin Carlyle. Benjamin says :

"Perhaps the clearest contrast is between REST and a strongly-typed O-O language. In nice, crinkly java I get a compile error whenever two components disagree on the definition of an interface. The client tries to call method foo. There is no method foo. Bail. In this setting it makes sense to leverage the strongly-typed nature of the language to make sure you don't release junk. You define interfaces in a detailed and domain-specific way that is checked to yield a consistent releasable whole."

I briefly touched on it before but given that an interface with more than 4 methods is deemed unsuitable on the Web (for all the reasons associated by REST advocates with this approach) why does it seem so natural and acceptable to do OO finer interfaces in a single JVM ? Will it be the ultimate WEB experience everywhere if there were only generic methods everywhere, on the WEN and in virtual machines ? The only difference would be that when programming remote services clients would need to be able to catch up remote exceptions and handle them as needed ?

This is probably a lot of nonsense. But I hope it captures what seems like one the main reasons behind a 'split' between RESTful and WebServices communities : for some it's natural to program in terms of generic interfaces, some will eventually accept it, for others it's simply a non-starter and more specific interfaces are on the map - with the proper data extensibility policy they can fare pretty well too.

Benjamin then says :

"In REST, I want the client or the server I deployed literally 10 years ago to work with whatever I am putting out today. I also want whatever I'm putting out today to work with every bit of code written since that time, and every bit of code that will be written in the next 10 years. "

I think I've read on one of the Benjamin's blogs that in 10 years time it will be all about REST. I have to admit that prediction may be much closer to the reality as people are getting behind REST more and more.

The one quoted above is basically unrealistic IMHO. With one exception only. If you're a client doing GET. I've always believed that GET is one of the main driving force behind the Web (plus links to URIs which can be GETed). Doing POSTs, PUTs, etc, in 10 years time ? I doubt - but I'm happy to be eventually proven wrong.

CXF and JAX-RS

2008-07-15T12:13:00.000-07:00

I've had a chance to get involved recently in a JAX-RS project in Apache CXF. This project is far from being complete yet but that's another story... I have to admit I've had a very positive experience while working on it.

CXF JAX-RS has entered the game quite late, with the leading implementations like Jersey, and very likely equally strong RestEasy and Restlets JAX-RS being there for a while already. Thanks to the work of my former colleague Jervis Liu, the feedback from the CXF users and the tremendous feedback from JAX-RS experts and the very open process behind the way JAX-RS and Jersey RI team operates has helped CXF JAX-RS to catch up a little bit with 0.8 api mostly supported now.

One can wonder what is next for CXF JAX-RS ? I hope that with the help of the large CXF community, its JAX-RS implementation will eventually become as solid as its top-notch (CXF) JAX-WS 'counterpart'. Will it be able to compete with the likes of Jersey, with it's client api gem (which will hopefully get standardized one day :-) ) ? It's hard to tell - not in the nearest future for sure.

Still I reckon CXF JAX-RS will eventually find its niche. While CXF JAX-RS users can certainly write RESTful service only with no JAX-WS (SOAP) involved, possibly its best 'argument' is that it sits on top of and is closely integrated with the same runtime which hosts quite possibly the best JAX-WS implementation out there. CXF users will be able to write the services combining JAX-WS and JAX-RS technologies, with one or more closely related Java classes involved, some will experiment and decide to move to JAX-RS altogether, some will use the combination of two technologies and some might get back to JAX-WS, you never know :-)

Generally, I'm somewhat pessimistic about Java code relying on various annotations which is what JAX-RS is all about. Having said that I have to admit that JAX-RS is much more involved in that it's not only about the annotations. Possibly the main achievement of JAX-RS authors is that JAX-RS 'breaks' the barrier for Java users at large and let them experiment with RESTful services while still being in the comfort of the their JAVA code. It's a great effort by those behind the specification and the RI.