WADL and Swagger United in Apache CXF

Who could've thought that Swagger and WADL can be real friends ?
Both Swagger and WADL are about describing REST APIs and while the former has a definite momentum, the latter has proved to be very capable and helpful to JAX-RS users.

The important thing is that we have users who submit WADL documents  to the runtime or build time code generators which is all working fine. We also have Swagger users who use cool Swagger features and being happy with a nice UI being generated. And WADL users, while being happy with WADL (which IMHO is indeed a very capable language for describing schema rich XML but with some extensions - even JSON - services) would like to use Swagger to introspect the code generated by WADL processors and have a nice API UI.

So my colleague Andrei and  Francesco, Apache Syncope maestro, have driven the work about enhancing a WADL generator to set WADL documentation fragments as Java Docs in the generated sources and then having CXF Swagger features being very smart about enhancing Swagger JSON payloads with these Java Docs, with Francesco doing some magic there. I should also mention Andriy Redko doing some work earlier on directly with Swagger for it to better support JAX-RS annotations and initiating the CXF Swagger project and Aki Yoshida doing a lot of Swagger2 work next.

So here you go, WADL and Swagger United in Apache CXF.

IMHO this project has been a perfect example of the power of the Open Source collaboration with the contributors from different teams working effectively on this project.

HTrace your Apache CXF Service flows

Andriy Redko keeps pushing CXF to the next level with adding new features nearly every few weeks :-).

One of his latest projects has been to do with wiring Apache HTrace into CXF such that CXF users can HTrace calls starting from CXF clients going to CXF servers and then to such HTrace aware containers as HBase  and using the collectors like Zipkin.

I'm looking forward to Andriy talking in detail about it on his blog and at the conferences, but in meantime you can check the documentation. Note that it works not only for JAX-RS but for JAX-WS too: if we can have a new feature working with both frontends then you know it will be done. The demo is here.

Give it a try and stay on top of the web services game :-)
Enjoy !



 

JAX-RS 2.1 specification work has started

JAX-RS 2.1 specification work has finally started after a rather quiet year and this is a good news for JAX-RS users at large and CXF JAX-RS users in particular.
JAX-RS 2.1 is entirely Java 8 based and a number of new enhancements are on the way. I was concerned earlier on that having a Java 8 will slow down the adoption but I think now the spec leads were right, Java 8 is so rich and JAX-RS needs to be open to accepting the latest Java features - ultimately this is what will excite the users.

The main new features list is: support for Server-Sent Events (something CXF users will enjoy experimenting with while also keeping in mind CXF has some great WebSocket support done by Aki), enhanced NIO support and introducing a reactive mode into Client API.

I've already mentioned before that JAX-RS 2.0 AsyncResponse API is IMHO very impressive as it makes a fairly complex task of dealing with suspended invocations becoming rather trivial to deal with. Marek and Santiago are doing it again with the new 2.1 proposals. Of course there will be some minor disagreements here and there but overall I'm very positive about this new JAX-RS project.


We now have a CXF Java 8 master branch to support the future JAX-RS 2.1 features but having a Java 8 trunk is great for all of the CXF community.

What is really good is that there appears to be no obvious end to the new requirements coming into the JAX-RS space. The HTTP services space is wide open, with the new ideas generated around the security, faster processing, etc, and it all will be eventually available as future JAX-RS features. I'm confident JAX-RS 3.0 will be coming in due time too.

[OT] Apache CXF: Nothing Else Matters !

One can ask, do web services still matter in the today's world of emerging technologies such as Cloud and Big Data ?

Of course they do still matter. Take Big Data. The important thing to realize is as far as a remote client interacting with your HTTP server which internally initiates BigData flows is concerned it is still a client and HTTP server only - the client submits the data and gets the response it needs - the mechanism used to produce this response is, and has to be, completely opaque to the remote client, nothing unusual here, simply a proper service design leaking no implementation details to the client. In some cases one may not want to link BigData response streams to remote clients but in other cases it may make a perfect sense.

So yes, the web services do still matter because one still needs a production-quality, secure, flexible HTTP layer between the remote clients and internal data systems.

In fact, if you are an Apache CXF user, I can already hear you all saying (or even singing ?), Apache CXF: Nothing Else Matters ! Just make it loud enough to have your colleagues from the other team hear it :-)

Make your CXF JAX-RS servers OpenId Connect ready

We've been doing a lot of work during the last year to ensure CXF developers can start experimenting fast and effectively with the latest RS security advancements such as OAuth2 and JOSE which are also the building blocks for OpenId Connect (OIDC).

With OAuth2 and JOSE modules becoming quite solid, it was time to turn the attention to OIDC, OIDC RP being a starting point - which is a mechanism to log on the users into the servers by federating to OIDC IDP providers such as Google and Facebook.  OIDC is a fairly complex protocol but with OAuth2 and JOSE covered it was not that tricky after all.

The initial result is these two demos:

1. BigQuery


This demo shows a client OAuth2 server that accesses a user's BigQuery data-sets. The demo checks a public data-set of Shakespeare works but once you have a Google Developer account you can easily create your own BigQuery data-set and use the demo to access it instead.

2. Basic OIDC

This demo shows that a server does not have to be specifically coded around OAuth2 flows to use OIDC - it only uses OIDC to log-in the users and then work with these users.

I'd like to encourage you to run these demos - ask at CXF users or #apache-cxf if you have any issues running them and start making your CXF servers OIDC-aware now !

I look forward to the feedback from the early adopters. And please watch this space - this is only a start :-)

Apache CXF and Aries Blueprint Everywhere

Many times, when developing JAX-RS demos, I had to solve the following issue: how to describe the demo endpoints to be run in OSGI and the same endpoints to be run in Tomcat.

Typically I'd create a Spring context file describing few JAX-RS endpoints and use it when running a demo in Tomcat. Next I'd create an equivalent Blueprint context file and run the demo in Karaf.

It works but having to duplicate the contexts in Spring and Blueprint languages is unfortunate. Granted, one can use Spring DM to run the endpoints described in Spring contexts in Karaf but OSGI developers know Spring DM is a finished line.

So we did some work first to make a CXFBlueprintServlet referencing a Blueprint context working in OSGI - the same way a CXFServlet can work with Spring contexts in OSGI with the help of Sprinjg DM.

Next, my colleague Alex suggested to have the same mechanism working in non-OSGI deployments - for the reason described above, i.e, to reuse the same context language (Blueprint) when deploying CXF endpoints to OSGI and servlet containers. As it happens Apache Aries team already did some work for supporting Blueprint in non-OSGI setups, so after doing some more work in CXF and Aries we can now have CXFBlueprintServlet loading Blueprint contexts in standalone Tomcat/Jetty too. Some work still needs to be done here, particularly ensuring such endpoints can run offline, but overall it looks promising.

The short overview is here.  Note the same web.xml and Blueprint context is used in OSGI and non-OSGI setups - the only thing which changes is a single Maven Aries dependency.

Note this mechanism works for CXF JAX-RS and JAX-WS endpoints.

If you are a Blueprint fan: Enjoy!  

The Rise Of Apache Tika

Apache Tika is an interesting project. It is not a very big one but IMHO it is poised to become the project every team serious about doing the complex, unstructured, binary content processing will talk about and use.

The power of Apache Tika lies in the simplicity it offers for processing different types of binary and other types of complex data. Consider a simple situation: your project needs to support analyzing PDF files. One approach is to write a PDF library specific routine. This approach stops scaling as soon you need to support Excel and ODT files too. And stops working once you have a task to support a possibly unlimited number of types of data.

Apache Tika helps with generalizing the processing of arbitrary types of data and thus offers a unique opportunity for a given project to offer a real value add-on.

I really liked this presentation at the recent Apache Con NA.  It was absolutely packed with the interesting content and Chris talked a lot about applying Tika to solving the real life problems. Andriy Redko did a brilliant talk about the CXF and Tika integration. There were more Tika presentations and I regret I could not make it to all of them.

The future is bright for Tika. And for the projects that will use it :-)

Open Id Connect Certification Strategy

I've just read about an OpenId Connect Certification open strategy. IMHO it is brilliant and no doubt will guarantee a wider adoption of OIDC. Mike Jones's explanation of why it will work is a good read.

The closed (payed-only) certification model limits the adoption of a given technology by the implementors.

[OT] Apache CXF is Electric !

I remember this day as it was yesterday. April or March of 1998. I'm in England, Stockport city centre, listening to Oasis's latest single. It was absolutely great, the energizing effect of it.

As it happens I haven't listened to Oasis for the next 17 years apart from hearing them occasionally on the local FM. But a month or so back, I finally got their disk.

"She is Electric" is one of the best songs, classical Oasis. Nearly every time I listen to it I think, well, one can definitely say "Apache CXF is Electric". Why ? Because Apache CXF is cool, active and alive !  Work with it and you will become Electric too :-)   

Talking about CXF at Apache Con NA 2015

Apache Con NA 2015 will be held in Austin, Texas on April 13-16 and as it is usually the case there will be several presentations done there about Apache CXF. There will be interesting presentations from Hadrian and JB too. There will be many other great presentations as usual.

As far as CXF presentations are concerned:

Aki Yoshida will talk about combining Swagger (Web) Sockets, Apache Olingo and CXF Web Sockets Transport - now, this is seriously cool :-) The good news the presentations will be available online for those who will not be able to see it live.

Andriy Redko will talk about something which equally rocks, about combining a CXF Search Extension (FIQL or OData/Olingo based), Apache Tika and Lucene to show the effective search support for uploaded PDF and Open Office documents.

Attending both presentations can get anyone over-excited, that is for sure :-).
This is going to be tough, choosing to which presentation to go with my other colleagues presenting on the same day.


Finally, I will do the introduction of Apache CXF JOSE implementation which I briefly introduced in the previous blog. I'll describe all that CXF JOSE project has in place, and finish with a demo.

The demo deserves a special attention: I haven't written this demo, Anders Rundgren did. The original demo is here. This appears to be like a regular JavaScript-based demo but it is bigger than that, it shows what WebCrypto can do. Supporting generic browser-based signature applications, and interoperating with target servers in a variety of formats, with JOSE one of them. So the demo will show a WebCrypto client interoperating with an Apache CXF JOSE server.


Anders has been incredibly helpful and supportive, helped me to get his demo running in no time. Anders is working on a JSON Clear Signature (JCS) initiative that offers an XML Signature like support for signing JSON documents.  JCS are easier to understand than JOSE formats where Base64URL content representations are used. I'd like to encourage the interested users experiment with JCS, and help Anders. Hopefully something similar to JCS will be supported as part of a wider JOSE effort in the future.

I'm happy as usual I've got a talk selected and my employer's support to travel to Apache Con. It is always great to talk to my colleagues who work with CXF and other Apache technologies, it is important to show others CXF is very much alive and 'looks forward'. I regret I won't see some of my team colleagues there who haven't had a chance to submit for various important reasons but overall I'm looking forward to the conference with a great anticipation. Especially because I promised someone to beat him in chess after the presentations are over :-).

See you there !

Apache CXF is getting JOSE ready

I've already talked about JOSE on this blog. In my opinion, it is one of the key technologies, alongside OAuth2, that will deeply affect the way developers write secure HTTP RS services in the years to come.

A one sentence summary: one can use JOSE to secure, sign and/or encrypt a data content in any format, JSON, text, binaries, anything. JOSE is a key component of an advanced OAuth2 application, but also is a good fit for securing the regular HTTP web service communications.

As such it should not be a surprise that CXF now ships its own JOSE implementation offering a support for all of JOSE signature and encryption algorithms and representation formats and joins a list of other frameworks/projects directly supporting JOSE.

I've done an initial documentation here. There's so much to document that I will need probably another week to complete it all. Lots of interesting stuff for developers to experiment with that needs to be documented. I think it is unique in its own way while probably repeating some of the boilerplate code that any JOSE implementation needs to do.

Apart from being keen to directly deal with such an implementation, IMHO it is also good to have it supported in CXF due to how important this technology will become for web services developers in the future. It is always healthy to have multiple implementations as the JAX-RS space has demonstrated. And if CXF users would prefer to use other JOSE implementations then it will be fine.

One such 3rd party implementation is Jose4J. I'd like to thank Brian Campbell for creating it - it did help me to keep my sanity when I only started trying to write a test validating an RSA-OAEP output which is random. I also looked at its source recently when I was puzzled as to why my tests involving EC keys produce wrong-size signatures, even though the validation was passing - the comment in Jose4J made a rather cryptic JOSE spec text obvious, JOSE EC signatures are formatted in a format more compact than DER. I still wrote my own code though :-) which one might say is questionable but there you go. Thanks Brian. I think we can plug in Jose4J with CXF JOSE filters easily enough should users demand it.



CXF JOSE project is not completely finalized but I'm thinking it is getting pretty close to the final API. I'd like to encourage the early adopters give it a go and provide the feedback. In meantime I'll be working on completing the documentation and tweaking the code to enforce some of the security considerations documented in JOSE specifications, etc.

Enjoy !

Camel CXFRS Improvements

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

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

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

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

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

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

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

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

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

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

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

Enjoy !