Friday, December 18, 2009

Support for CXF in Enunciate

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 !

Thursday, December 17, 2009

The RESTful Java with JAX-RS book

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 :-)

Wednesday, December 16, 2009

OT: The Fever Pitch

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 !

Friday, December 11, 2009

The argument about fast JSON processors

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.

Thursday, December 10, 2009

Better Jettison is on the way

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.

Sunday, December 6, 2009

Embracing Atom with CXF

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 !

Wednesday, November 25, 2009

Come on, Abdera !

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 !

Friday, November 20, 2009

Updates to the CXF JAXRS runtime

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

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.

Wednesday, November 18, 2009

Atom Logging in CXF

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 :-)

Monday, November 16, 2009

The WADL Dilemma

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.

Tuesday, September 22, 2009

What is Distributed OSGI ?

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.

Friday, August 28, 2009

JAXRS and JAXB without annotations in CXF

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.

Saturday, June 20, 2009

Distributed OSGi RI gets the RESTful edge

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.

Monday, June 8, 2009

Pragmatic Web Services with Apache CXF

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.

Tuesday, June 2, 2009

The benefit of a doubt

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

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.

Thursday, May 21, 2009

Annotation-free services with CXF JAX-RS

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.

Thursday, May 14, 2009

Standards in web services frameworks

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.

Wednesday, May 13, 2009

CXF JAX-RS XPath provider

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.

Thursday, May 7, 2009

MVC the XML way with CXF JAX-RS

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.

Monday, April 13, 2009

Analysis of CXF RESTful client APIs

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.

Tuesday, March 24, 2009

GET is the real differentiator

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

Thursday, February 26, 2009

CXF JAXRS Client API updates

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

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.

Thursday, February 19, 2009

FAQ : Why CXF implements JAXRS

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

Friday, February 13, 2009

CXF JAXRS Client API Preview

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.

Thursday, February 5, 2009

JAXRS Spring Security Demo in Fuse

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 :-)

Wednesday, February 4, 2009

New CXF SubProject : Distributed OSGI RI

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.

Monday, February 2, 2009

Multiparts in CXF JAXRS

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.