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.

Tuesday Aug 25, 2015

Asynchronous Support in JAX-RS 2/Java EE 7

Asynchronous processing, non-blocking I/O, events and messaging are keys to more reactive applications. Fortunately Java EE has long organically provided such features in the platform at pretty much every key API layer including Servlet, CDI, EJB and JMS. These features were strengthened further in Java EE 7 and even more could be done in Java EE 8. Spurred by a real world developer I met at a conference writing a highly reactive IoT application with Java EE, I've actually developed a talk about reactive features in Java EE (click here if you can't see the embedded slide deck):

One such feature added in JAX-RS 2/Java EE 7 gets surprisingly little exposure - asynchronous capabilities added for both server-side REST endpoints as well as clients. Fortunately Sam Sepassi has stepped up nicely to fill the gap with a detailed blog entry that covers both the servers-side and client side capabilities. Bonus points to Sam for demonstrating how nicely JAX-RS 2 asynchronous endpoints and EJB @Asynchronous work together! Sam also shows the Java EE 7 Concurrency Utilities in action and does a nice job explaining the basics/what's going on under the hood.

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.

Wednesday Sep 10, 2014

Supporting CORS in JAX-RS 2/Java EE 7

Many developers, especially more inexperienced ones, don't seem to realize that browsers automatically enforce the well-known same-origin policy. This means that browsers will make sure that any scripts (likely JavaScript :-)) can only access URLs on the same server that the script came from. For most applications this is not an issue. However, in some deployment scenarios (e.g. JavaScript clients on a plain web server trying to access REST resources on a separate back-end application server) this can be a real and unexpected problem. The solution to this problem is CORS or Cross-Origin Resource Sharing. If you are not familiar with CORS, you should read the detailed write-up here. Essentially using CORS a server side resource indicates that it is explicitly allowing an exception to the same-origin policy.

JAX-RS users should ask how they can handle CORS if the need arises. The answer to this question is that while most JAX-RS providers may not yet support CORS out of the box, it is pretty easy to handle this yourself using JAX-RS 2 server-side filters. Max Lam does a very nice job showing you how in a code-intensive blog entry. The entry is actually a nice demonstration of JAX-RS 2 filters in action in the real world.

Perhaps JAX-RS 2.1 could explore built-in CORS support as a possibility?

Tuesday Jun 17, 2014

Jersey OAuth support

"The biggest guru-mantra is: never share your secrets with anybody. It will destroy you." (Chanakya

You have probably already heard of OAuth as it is widely used by many online services providers such as Google, FaceBook, LinkedIn, Yahoo, Twitter, ... to name just a few! OAuth is an authentication protocol that allows users to approve application to act on their behalf without sharing their password.  

OAuth support was introduced, several years ago, in Jersey 1.x. 'Recently' ... well more than 6 months ago (*), OAuth support has been added to Jersey 2.x, this post post covers in more details the OAuth support added to Jersey 2.3

If you are not yet familiar with OAuth, it is probably a good time to start to look at this open protocol. The OAuth chapter of the Jersey documentation should be a good starting point.

(*) It's sometime difficult to keep up with the Jersey release cadence! At the time of writing, the current release is Jersey 2.9!

Thursday Nov 21, 2013

Jersey 2.x Tracing support

"Rest is the sweet sauce of labor." (Plutarch – a long time ago!)

Jersey is JAX-RS 2.0 Reference Implementation and as such it's fully compliant to JSR 339. The Jersey Team goes beyond the specification by adding features and functionalities to their JAX-RS implementation. Overtime, some of those features might be good candidates for standardization.  The Client API is a good example of that. In JAX-RS 1.x, Jersey and some other implementations has their own proprietary Client API. In JAX-RS 2.0, the Client API has been standardized and is now part of the specification. So it is not uncommon to have, in an implementation, features that are (not yet?) part of the specification. Those extra capabilities are also a way for an implementation to differentiate itself from the other implementations.

Tracing is a feature that was available in Jersey 1.x, this feature has now been ported to Jersey 2.x (2.3 and above). The Jersey Tracing capabilities allows to easily diagnose server-side request processing pipelines.  Libor Kramoliš, a member of the Jersey Team, has written a detailed post on how to use the Jersey's Tracing capability.

Tuesday Oct 08, 2013

JavaOne 2013 Trip Report

JavaOne 2013 San Francisco was held September 22-26. This was a particularly important year from a Java EE standpoint with the release of EE 7 and GlassFish 4 - the content reflected this fact. JavaOne 2013 can certainly be considered a success by most measures. It's clear the best and the brightest in the Java ecosystem continue to see participating in JavaOne as a badge of honor and a privilege.

Besides booth duty at the GlassFish 4/Java EE 7 kiosk on Monday/Tuesday, I led the GlassFish Community Event on Sunday, had a BOF titled "What’s New with Bean Validation and Expression Language in Java EE 7" on Monday, led the GlassFish BOF on Tuesday and had a technical session titled "Android and iOS Development with Java EE 7" on Thursday. More details on the sessions and JavaOne, including the slide decks and code, posted on my personal blog.

Thursday Jun 28, 2012

EclipseLink 2.4 Released: RESTful Persistence, Tenant Isolation, NoSQL, and JSON

EclipseLink 2.4 is released as part of Eclipse Juno release train. In addition to providing the Reference Implementation for JPA 2.0, the key features in the release are:

  • RESTful Persistence - Expose Java Persistence units over REST using either JSON or XML
  • Tenant Isolation - Manage entities for multiple tenants in the same application
  • NoSQL - NoSQL support for MongoDB and Oracle NoSQL
  • JSON - Marshaling and unmarshaling of JSON object
Eclipse Link 2.4

Here is the complete list of bugs fixed in this release. The landing page provide the complete list of documentation and examples. Read Doug Clarke's blog for a color commentary as well.

This release is already integrated in the latest GlassFish 4.0 promoted build.

Try the functionality and give us feedback at GlassFish Forum or EclipseLink Forum.

Sunday Feb 05, 2012

POJOMapping in Jersey for type-safe clients

Over on his blog, Jason Lee has a detailed post on the new POJOMapping feature in Jersey/GlassFish which offers strongly-typed client API's and illustrates this with a GlassFish Cluster administration sample.

ALT_DESCR

The post shows how to enable POJOMapping with a Jersey servlet initialization parameter and goes on to show the Cluster domain model. An archive with the entire sample is available there.

Sunday Jan 08, 2012

RESTful JAX-RS Roundup

Note: if you're reading this using a feedreader, please make sure you've updated to the updated TheAquarium feed.

While most parameter handling examples with JAX-RS focus on @PathParam, there are other JAX-RS 1.x annotations that are worth knowing.

Mkyong has a short and simple example for how to use @MatrixParam (and for many more here) while John Yeary covers @CookieParam. The JavaDoc for both annotations can be found here and here.

ALT_DESCR

Meanwhile, François explores Jersey's support for MVC where the Controller is a resource class, the model is returned by a resource method, and the view is a template which operates on the model (this is inspired by the stapler project and is also used by Hudson). Note that this is not part of the JAX-RS standard.

To close this quick roundup, I'd like to point you to a month-old JAX-RS blog entry by Adobe's Christophe Coenraets combining jQuery and JAX-RS/Jersey as probably the one with the best taste to date (IMO, etc...) !

Update: John Yeary has (a lot) more JAX-RS resources for you.

.

Tuesday Dec 13, 2011

Jersey 1.11 is here with MOXy support

Jakub, the Jersey lead has just announced Jersey 1.11 which offers EclipseLink's MOXy support, attaching filters to non-blocking clients as well as some docs cleanup.

Moxy Band

Jersey 1.11 is scheduled to be available as part of the upcoming GlassFish 3.1.2 release. More on other component updates for this release in an upcoming post.

I can't help but wonder if the number of Canadians involved in MOXy has anything to do with it being named after a heavy metal band. Project and product names are always fun stories.

Tuesday Sep 27, 2011

Coherence 3.7.1 is out with RESTfulness, courtesy of Grizzly/Jersey

With its latest 3.7.1 release, Oracle Coherence is now offering REST support using Jersey 1.8 and Grizzly 2.1.1 (as a standalone HTTP server) under the covers. This opens up the Coherence data grid to yet more languages such as PHP or Python.

ALT_DESCR

This documentation page lays out all the steps to build a Coherence REST Application. You'll also find Release Notes enumerating all the enhancements in this version of the product.

Oracle GlassFish Server customers using Active Cache will find also that this version includes a number of bug fixes in Coherence*Web.

Added: Press Release

Friday Sep 02, 2011

Tab Sweep - JCache, REST, CDI samples, JavaOne, ... and James' new gig

Recent Tips and News on Java EE 6 & GlassFish:

Radio Receiver

JCache: Alive and Going to be Part of Java EE 7 (QCon)
Unit Testing for Java EE (Adam)
REST-JEE (minuteproject)
Autumn JavaEE workshops, sessions and events (Adam Bien)
Java SE 7 - New File IO (Dr. Dobb's)
Java EE 6 examples of CDI usage (code.google.com)
JavaOne 2011 : un Hands-On Lab Serli / Oracle (Serli)
Mapping XMLTYPE (Shaun)
GlassFish 3.1.1 and JDK 7 Webinar replay (GlassFish Videos)
OTN Developer Day New York, September 14th 2011 (OTN)
Java EE 7: The Voyage of the Cloud Treader (Werner)
I've moved again (James Gosling)