Book Review: Developing RESTful Services with JAX-RS 2.0, WebSockets, and JSON

I was particularly interested in accepting Packt Publishing's offer to provide a book review of Masoud Kalali's and Bhakti Mehta's Developing RESTful Services with JAX-RS 2.0, WebSockets, and JSON because its title mentions three things I have had good experience with (REST, JAX-RS 2.0, and JSON) as well as a concept that I only have basic familiarity with but wanted to learn more about (WebSockets). For this review, I was provided with an electronic copy of this book with about 100 pages of "regular" text and code examples.

Preface

The Preface of Developing RESTful Services with JAX-RS 2.0, WebSockets, and JSON is a good place to start if you are thinking of purchasing this book and want to get an overview of what it entails. The Preface breaks down what is in each of the five chapters with three or four sentence descriptions of each chapter.

It is also in the Preface that the reader learns that the book assumes use of Maven (final chapter only) and GlassFish Server Open Source Edition 4 (most chapters) for building and running the examples. The recent news that Oracle will not provide commercial support for GlassFish 4 has certainly added tarnish to the idea of using GlassFish 4, but it is still a valid application server to use for Java EE illustrative purposes as it remains freely available and is going to continue to be the reference implementation of the Java EE 8 specification.

Developing RESTful Services with JAX-RS 2.0, WebSockets, and JSON's Preface also states "who this book is for": "This book is ... for application developers who are familiar with Java EE and are keen to understand the new HTML5-related functionality introduced in Java EE 7 to improve productivity. To take full advantage of this book, you need to be familiar with Java EE and have some basic understanding of using GlassFish application server." I agree that readers of this book will be much better off if they have a basic understanding of Java SE and Java EE principles. Examples of this are terms that are assumed to be implicitly understood such as POJO (Plain Old Java Object) and StAX. Perhaps the most important assumed knowledge is awareness of what JSON is and how it differs from and compares to XML.

Chapter 1: Building RESTful Web Services Using JAX-RS

The initial chapter of Developing RESTful Services with JAX-RS 2.0, WebSockets, and JSON begins with a brief introduction to the basic characteristics and principles of the REST architectural style before quickly moving onto "the basic concept of building RESTful Web Services using the JAX-RS 2.0 API." The chapter states that the "Java API for Representational State Transfer (JAX-RS) specification defines a set of Java APIs for building web services conforming to the REST style." Note that JAX-RS 2.0 is standardized via JSR 339 and is more commonly as "The Java API for RESTful Web Services.

Chapter 1 provides step-by-step instructions for converting Java POJOs into RESTful resources via application of JAX-RS annotations such as @Path (defining resource), @GET (defining methods), and @Produces (defining MIME type). This section continues these step-by-step instructions by illustrating how to write an Application subclass and define subresources. Along the way, this chapter also demonstrates using curl to communicate with an HTTP-exposed service from the command line.

After covering converting a POJO to a resource and listing additional JAX-RS annotations in a handy table, the first chapter moves onto discussion of the client API for JAX-RS (this standardized client API for JAX-RS is new to 2.0). Entities, which are passed as part of requests and responses, are also covered along with custom entity providers (implementations of MessageBodyReader and MessageBodyWriter). Use of JAXB with JAX-RS is also introduced.

One part of this chapter that I found particularly interesting and useful is the inclusion of a highlighted section on "Tips for debugging errors with MessageBodyReader and MessageBodyWriter." I would like to see more books have sections like this.

Chapter 1's section on "using the Bean Validation API with JAX-RS" introduces the @ValidationOnExecution annotation as part of Java EE's Bean Validation support. The chapter's Java validation coverage also talks about extracting status responses from Response.readEntity(GenericType<T>) to handle errors.

Chapter 2: WebSockets and Server-sent Events

As the chapter's title suggests, Chapter 2 is an introduction to WebSockets and Server-Sent Events (SSEs), with Chapter 3 going into more details on these subjects. This second chapter begins with an overall view of polling between a client and server and then illustrates an example of this using an Ajax (XMLHttpRequest) JavaScript client example.

After outlining the drawbacks of polling mechanisms between clients and servers, the chapter moves onto coverage of long polling. The XMLHttpRequest of Ajax fame is then used again, but this time with significantly more explanation. The chapter includes a discussion on the disadvantages of long polling.

Chapter 2 introduces concepts that attempt to address the drawbacks and limitations of polling. Server-sent Events (SSE) (or EventSource) are described as "an HTML5 browser API that makes event pushing between server and client available to web application developers." The authors add, "The major SSE API that is considered the foundation of SSE in the client side for JavaScript developers is the EventSource interface." Code listings are provided to illustrate SSE implemented via Java servlet on the server side and JavaScript on the client side along with a JSP example that embeds JavaScript.

WebSockets are the theme of the remainder of Chapter 2 and are described as a "component of HTML5" that "adds a brand new method for interaction between clients and servers to address the scalability and flexibility required for modern web-scale applications by introducing a full duplex event-based communication channel between clients and servers." Chapter 2 mentions that modern browsers support WebSockets and discusses operations available on a JavaScript WebSockets object.

The authors mention that Java EE 7 provides "full support for HTML5, SSE and WebSockets" and references JSR 356 ("Java API for WebSocket").

This information-packed second chapter begins to wind down with a table comparing characteristics (browser performance, communication channel, and complexity) of the three covered communication approaches (long polling, Server-Sent Events, and WebSockets). I liked the fact that the chapter then concludes with example use cases/scenarios where each of the three approaches to asynchronous web communication is best suited.

I found it a bit odd that the second chapter has the side note referencing Jersey as the JAX-RS reference implementation rather than the first chapter (which was devoted to JAX-RS) including that side note. A more appropriate side note for this chapter references the article Memory Leak Patterns in JavaScript.

Chapter 3: Understanding WebSockets and Server-sent Events in Detail

Chapter 3 dives more deeply into the concepts introduced in Chapter 2. These more in-depth topics related to WebSockets include encoders and decoders in the Java API for WebSockets (@ServerEndpoint), Java WebSocket Client API (@ClientEndpoint), sending blob/binary data rather than text (JSON/XML), WebSockets security (including example in GlassFish), and three best practices for WebSockets applications. The more in-depth topics on Server-sent Events covered in the third chapter include an example of developing a Server-sent Event client using Jersey API and three "best practices for applications based on Server-sent Events."

The third chapter introduces JSON and JSON-P.

Chapter 4: JSON and Asynchronous Processing

The fourth chapter of Developing RESTful Services with JAX-RS 2.0, WebSockets, and JSON covers JSR 353 ("Java API for JSON Processing") and "related APIs." The chapter explains that Java EE 7 adds JSON support that replaces less standard open source Java JSON processing products such as google-gson and Jackson.

Chapter 4 provides a nice overview of the JSON API and includes a table that lists the classes provided along with a description of the classes and how those classes are used. The authors state that "JSONObject is the entry point to the entire JSON API arsenal," but it is the Json class that provides factory methods for creating instances of other classes in the JSON API. The chapter covers generating JSON documents (JsonGeneratorFactory and JsonGenerator), parsing JSON documents (JsonParser), using JSON object model to generate JSON (JsonBuilderFactory and JsonObject), and using JSON object model to parse JSON (JsonReader and JsonObject). A quick paragraph contrasts when to use the streaming approaches versus the object model approaches for generating and parsing JSON; the trade-off is similar to that between StAX and DOM (memory considerations versus ease of use).

The next section of Chapter 4 covers Servlet 3.1 enhancements with specific focus on NIO additions to servlets (ReadListener and WriteListener) and WebSockets support in servlets. Changes to servlets to support this new functionality are covered and include ServletOutputStream, ServletInputStream, @WebServlet asyncSupported attribute, asynchronous request and response processing, and JAX-RS 2.0 filters and interceptors.

The authors introduce asynchronous support with EJB 3.1 and 3.2 and include an interesting observation: "In Java EE 6, the @Asynchronous [annotation] was only available in full profile while in Java EE 7 the annotation is added to the web profile as well."

One of the interesting side notes of this chapter is mention that key JSON API classes can be used with the Automatic Resource Management (try-with-resources) mechanism introduced with Java SE 7.

Chapter 5: RESTful Web Services by Example

While the first four chapters of Developing RESTful Services with JAX-RS 2.0, WebSockets, and JSON are packed with new information and details related to writing RESTful web services with Java EE, JAX-RS 2.0, WebSockets, and JSON, the fifth and final chapter provides two examples of applying these concepts and technologies to representative use cases. The samples in this chapter are built with Maven and deployed to GlassFish.

As the authors advertised at the beginning of the chapter, these two samples do illustrate integrated application of topics covered in the prior chapters of the book. The first sample employs Server-sent Events, Asynchronous Servlet, JSON-P API, JAX-RS 2.0, EJB Timers (@Schedules) and the Twitter Search API (including Twitter's OAuth support and Twitter4j).

The second Chapter 5 example demonstrates integration and application of WebSockets, JAX-RS/HTTP "verbs" (GET, DELETE, POST), using JSON-P for writing JSON documents, and leveraging asynchronous benefits. I like the approach this book has taken of using four information-heavy chapters to introduce concepts and then devoting the entire final chapter to examples of how to integrate these concepts into realistic sample applications.

Miscellaneous Observations

The following are some miscellaneous observations I have made regarding Developing RESTful Services with JAX-RS 2.0, WebSockets, and JSON.

• Covers a lot of material in a relatively small number of pages.
• Has some interesting and useful emphasized side notes.
• Lacks a lot of color in the graphics and screen snapshots, meaning the printed book probably does not lose much in way of presentation when compared to the electronic versions.
• There are some type-setting issues, especially in code samples, where some spaces are missing that would normally separate types, variable names, and so forth.
• Although Maven and GlassFish are used in the book, many of the examples could be tweaked to build with a Ant, Gradle, or other build system and to be deployed to an application server other than GlassFish.
• Some experience with Java EE, HTML, and REST/HTTP concepts is assumed. More experience in these areas will obviously make the book more approachable, but only basic familiarity is needed to understand the concepts in this book.

Conclusion

This book is what its title and its preface describe: a book that details how to develop RESTful services with JAX-RS 2.0, WebSockets, JSON, and more. As the authors state in the Preface, this best is best suited for developers with at least minimal Java EE knowledge as there is some assumed knowledge in a book that covers this much in a little over 100 pages.