Wednesday Jan 13, 2016

Hypermedia/HATEOAS Support in JAX-RS 2/Java EE 7

The concepts of Hypermedia and HATEOAS (shorthand for the mouthful of "Hypermedia as the Engine of Application State") have made the rounds in the REST ecosystem for a little while now. If you Google around a bit you'll find no shortage of arcane academic-sounding text describing it's supposed universal virtues. For the rest of us a simple explanation is that it is an attempt to utilize web page style links in REST based web services. Using the hypermedia concept, you can send the client links for what they may be able to do further after receiving a REST response. A simple example is including links for canceling or getting details for an order in addition to a confirmed order object probably retrieved via a GET request. Although less common, links can also be embedded as data within the response. An example would be embedding a link to retrieve the delivery address in the order data body instead of embedding the actual address body or an address ID. Finding a reasonably down-to-earth, unpretentious explanation of Hypermedia was shockingly difficult. The best I could find is the humble documentation for the PayPal Payment REST API that makes real world use of Hypermedia.

In practical terms Hypermedia helps make clients more flexible by avoiding hard-coding REST URLs. It can also help in self-documenting REST APIs. If you look around on the web it is an open question whether these purported benefits are actually worth the additional implementation complexity. Hypermedia may be best applied in a situation when you are developing a public API where you do not know much about potential users of the API. The PayPal Payment REST API is a good example of such a case.

The good news is that if you have a good use case for Hypermedia Java EE 7 adds support for it via JAX-RS 2. Sam Sepassi recently did an excellent write-up detailing the newly added API. It is far and away the best write-up that exists on the topic. He includes a brief explanation of Hypermedia including example code using JAX-RS 2. He also included some details on experimental work that is being done in the Jersey JAX-RS RI to include support for declarative Hypermedia (the Hypermedia APIs added in JAX-RS 2 are basically programmatic).

Enjoy and feel free to share with anyone that you might think would find this useful.

Tuesday Dec 15, 2015

Content Negotiation using 'q' Factors with JAX-RS 2/Java EE 7

When we think of HTTP and content negotiation most of us probably immediately think of mime-types. Agreeing upon the mime-type is indeed part of the HTTP conversation between a client and a server. However HTTP has also had an even finer grained content negotiation mechanism called the relative quality factor or 'q' factor for short. 'q' factors are so far not that well supported by browsers and are even more unknown to most developers. Using a q-factor, a client can specify a preference for the mime-type they want if they are able to support multiple mime-types (let's say to state a preference for PNG over JPG). The 'q' factor is essentially a number between 0.0 and 1.0 tacked onto the mime-type. A higher value indicates a more preferred mime-type. Similarly the server can also indicate what mime-type it prefers to send as a response by specifying a 'qs' factor or quality of source factor. The best written explanation of 'q' factors that I could find is here. Note that the article also points out the somewhat obscure nature and poor browser support for 'q' factor based negotiation in the web world so far. It does however point out the fact that Apache httpd has long had strong support for 'q' factors.

'q' factor based negotiation can be very valuable in REST. It can help you write a more robust service API. For example, you could support both JSON and XML for a resource and then state that you prefer JSON over XML if the client supports both. Similarly you can write more powerful clients that can flexibly process multiple content types. These capabilities are especially helpful while writing public APIs with REST or dealing with heterogeneous clients that you cannot completely predict. The same is true on the client side as well especially while dealing with third-party services. The good news for you is that JAX-RS 2 and Java EE 7 has strong support for 'q' factor based content negotiation. Sam Sepassi did a very nice job explaining the feature in a recent article. You should give it a read and consider using it if you have a good use case for the feature.

Thursday Dec 11, 2014

Named and Dynamic Binding in JAX-RS 2

Providers, interceptors and filters are excellent mechanisms to bring pluggability and cross-cutting concerns to JAX-RS. By default these artifacts are applied globally to all available JAX-RS resource methods. This is probably fine for the most part but in some cases it's useful to have a bit more control over where filters and interceptors are applied. Fortunately, JAX-RS 2 has two mechanisms to facilitate this - named and dynamic bindings. Named bindings are much like binding CDI interceptors in that it is declarative and static - you get to choose in a loosely coupled, type-safe fashion where you want a binding to occur but you can't change bindings at runtime. Dynamic bindings as the name implies gives you a much greater degree of flexibility. You can choose at runtime in a completely programmatic fashion where bindings should occur. The trade-off is that dynamic bindings are a bit more complex and verbose. Michal Gajdos explains both named and dynamic JAX-RS 2 provider bindings in a fairly brief but excellent blog post.

Towards the bottom of the post, Michal has links to the Jersey docs that is a great resource for understanding the concepts of providers, interceptors and filters in a general sense.

Tuesday Oct 21, 2014

New book: RESTful Java Patterns and Best Practices

RESTful Java Patterns and Best Practices” written by ’Bhakti Mehta' has been recently published. One of the great thing about this book is that it is not a theoretical book covering the JAX-RS API 2.0. As its title suggest, this book is talking about different best practices that are relevant when it comes to build efficient, scalable and secure RESTful services. So the focus of the book is really on REST best practices. It then shows how you can apply the practices and patterns using the JAX-RS 2.0 APIs.

Some of the covered practices discussed are:

  • How to design and expose your resources
  • Error handling 
  • API versioning
  • Testting
  • Security
  • Caching
  • Asynchronous behaviours, etc.

Another aspect I particularly like about this book is that it also covers features that are not yet part of the standard. It should be mentioned that some of those features (e.g. SSE, JSON-Pointers, ...) will high likely be introduced in Java EE 8. So the book give some useful background material to understand why it would make sense to add those capabilities to the platform.

Finally, the book is really trying to not overload you with too many details, with too much information. For each of the discussed topic, a technical solution is presented and explained. Pointers to additional ressources are then also suggested in case you need to dig into a specific topic in more details.

All in all, this book is a nice reading for anybody designing RESTful based applications... and who isn't?

To celebrate this, Packt Publishing will raffle 10 copies of  “RESTful Java Patterns and Best Practices” (5 eBook copies and 5 paper copies). To participate, just leave a comment about the book on your preferred social media using the 'http://bit.ly/1uUs7QR' URL and the '#JavaBhakti' hashtag. PackT will randomly select 10 lucky persons.

Please do note that Oracle is not involved in this raffle, we are just relaying this information. For any question about this raffle, please contact Packt Publishing directly.

Tuesday Oct 14, 2014

JSR 339 Maintenance Release: JAX-RS 2.0 rev A

JAX-RS 2.0 (JSR 339) has been slightly revised through the JCP Maintenance Release process and has recently passed the JCP MR ballot

This update (JAX-RS 2.0 rev A) is mostly about clarifications (including JavaDoc clarifications) and some fixes in Jersey, the JAX-RS Reference Implementation. The updated documents will be published soon on the JSR 339 page but in the meantime, you can check this page for details about the changes of JAX-RS 2.0 rev A.

It should be noted that GlassFish 4.1, the Java EE 7 Reference Implementation, already supports this version of the JAX-RS specification (i.e. JAX-RS 2.0 rev A).

Wednesday Jul 09, 2014

Java EE @ NFJS Central Ohio Software Symposium

As some of you may be aware, I recently joined the well-respected US based No Fluff Just Stuff (NFJS) Tour. My first engagement with NFJS was the New York Software Symposium on April 4-5. The show went relatively well. My second engagement was extremely encouraging - the Central Ohio Software Symposium in Columbus, Ohio on June 6-8. Unlike New York, the Columbus show was fully sold out and very vibrant.

I had five talks total over two days, essentially back-to-back. I had a full house for all my sessions and had many of the same folks staying for multiple sessions which is always a very good sign. I did talks on Java EE 7/Java EE 8, the Cargo Tracker Java EE Blue Prints, JMS 2, aligning Java EE 7 with the HTML 5/JavaScript Rich Client landscape and JAX-RS 2. More details, including slide decks and code, posted on my personal blog.

Tuesday Jul 01, 2014

Java EE @ Java Day Tokyo 2014

Java Day Tokyo 2014 was held on May 22nd. Organized by Oracle Japan, it is the largest Java developer event in the country. Indeed it is really a replacement to JavaOne Japan. This was another highly successful year for the event with a fully sold out venue packed with youthful, energetic developers. Speakers included Steve Chin, Stuart Marks, Simon Ritter, Nandini Ramani, Cameron Purdy and Yoshio Terada. Topics included Java SE, Java EE and JavaFX. Cameron Purdy, Vice President of Development at Oracle responsible for Java EE, shared the Java EE 8 road-map during the opening keynote.

I did talks on Java EE 7/Java EE 8 and aligning Java EE 7 with the HTML 5/JavaScript Rich Client landscape. There were many other very interesting Java EE related session in Japanese and English, including a Java EE adoption story from Rakuten. More details, including slide decks and code, posted on my personal blog.

Sunday May 11, 2014

Using HTTP PATCH with JAX-RS 2

Thanks to the popularity of REST, most of us now know HTTP methods like GET, POST, PUT and DELETE better than we probably care to. Nonetheless, most of you probably don't know much about a more obscure but pretty handy HTTP method - PATCH. If this is the case, you should check out this well-written blog post explaining the basics of HTTP PATCH.

JAX-RS 2 and Jersey do not support PATCH out of the box as it is not that widely understood or used quite yet. However, you can fairly easily add PATCH support using JAX-RS 2 - Oracle's own Gerard Davison shows us how. Like a small handful of us here at Oracle Gerard is a JavaLobby/DZone Most Valuable Blogger (MVB). Besides demonstrating how you might implement PATCH, the code-driven post uses a number of cool JAX-RS features such as meta annotations, name bindings, interceptors and providers. Enjoy!

Monday Nov 25, 2013

Asynchronous clients integration with Java EE 7

"The client is not always right." (Enzo Ferrari)

Integrating clients with a back-end server may pose some challenges as it involve a mix between asynchronous and synchronous behaviour and data exchange.

The 'communication related APIs' of Java EE 7 APIs have all some asynchronous capabilities, e.g. JAX-RS 2.0, WebSocket 1.0 , JMS 2.0, Servlet 3.1, JAX-WS 2.2. In his 'JavaFX Integration Strategies' article, Adam Bien explain some strategies to easily integrate JavaFX clients with a back-end using some of the asynchronous capabilities of Java EE 7. The article also illustrate how to push information from the server to the client using WebSocket.

The article uses JavaFX as the client side UI framework but the patterns and strategies described are not necessarily JavaFX specific and are easily applicable to almost any types of client. As Adam says "REST and JSON become the new, least common denominator for communication with HTML5 clients, Java applications, and even low-level devices.". Finally, the article also illustrate how Java SE 8 Lambda leads to a cleaner code.

Tuesday Nov 19, 2013

New book: RESTful Java with JAX-RS 2.0


Bill Burke's RESTful Java with Jax-RS is a book that comes to mind when talking about JAX-RS. It is has been published by O'Reilly in its Animal Menagerie a few years ago.

Bill is a long time JBoss contributor and is also the RedHat representative in theJAX-RS 2.0 Expert Group.

O'Reilly has just published a revised edition of the book to includes the new JAX-RS 2.0 features. RESTful Java with JAX-RS 2.0 has new chapters to cover the specification important additions such as the JAX-RS 2.0 Client API, the Asynchronous Client and Server APIs, Filters and Interceptors. In addition, the new edition also covers smaller JAX-RS 2.0 updates such as ParamConverters, UriBuilder extension, etc.

JAX-RS 2.0 cover


Friday Nov 15, 2013

MOXy is the New Default JSON-Binding Provider in GlassFish 4

When I talk about JAX-RS 2, JSON-P and Java EE 7 a surprising number of people seem to assume that GlassFish and Jersey does not support JSON binding and just supports lower level JSON processing. It is in fact correct that Java EE 7 has standardized JSON processing (via JSON-P) but not a JSON binding API yet (although such a standardized API is a very strong consideration for Java EE 8 and would build upon the JSON-P work). However Jersey, the popular JAX-RS reference implementation, has long had strong support for JSON binding via MOXy, Jackson and Jettison (now it also has support for JSON-P of course). In fact, in GlassFish/Jersey the default JSON binding provider is MOXy. If you are not familiar with MOXy, it is a very interesting project part of EclipseLink (the JPA reference implementation) that translates JAXB annotations to JSON. In a code driven post, Blaise Doughan of the Oracle EclipseLink team explains the details of using MOXy with JAX-RS in GlassFish.

For more details on Jersey's support for JSON, you should check out the very well-written documentation.

Tuesday Nov 12, 2013

Java Developer Days India Trip Report

October 21st through October 25th I spoke at Java Developer Days India. This was three separate but identical one-day events in the cities of Pune (October 21st), Chennai (October 24th) and Bangalore (October 25th). For those with some familiarity with India, other than Hyderabad these cities are India's IT powerhouses.

The events were focused on Java EE. I delivered five sessions on Java EE 7, WebSocket, JAX-RS 2, JMS 2 and EclipeLink/NoSQL. The events went extremely well and was packed in all three cities. More details on the sessions and Java Developer Days India, including the slide decks, posted on my personal blog.