Java Web Services: Up and Running, 2nd Edition

What’s Next?

RESTful services are rich enough to warrant two dedicated chapters. Accordingly, the next chapter focuses on the service side by exploring options for implementing and publishing RESTful services. The web service APIs include:

• HttpServlet and its equivalents (e.g., JSP scripts)
• JAX-RS, which has various implementations
• Restlet, which is similar in style to JAX-RS
• JAX-WS @WebServiceProvider, which is a relatively low-level API

Web services using any of these APIs can be published with a production-grade web server such as Tomcat or Jetty; there are even command-line options for such publication, although these options vary significantly in ease of use. There are trade-offs among the APIs, and the next chapter highlights the pluses and minuses of each API.

The servlet approach represents a base-level API in that servlets have been a part of Java since the late 1990s, and they remain the foundation for websites written in Java. The servlet API is close to the HTTP metal in that, for example, an HttpServletRequest is a thin but likewise convenient wrapper around an HTTP request; in similar fashion, an HttpServletResponse is a thin and equally convenient wrapper around an HTTP response. At the same time, servlets provide high-level filtering of HTTP requests, and a data structure such as the HttpServletRequest collapses the distinction between the key/value pairs in a query string of a GET or DELETE request and the key/value pairs in the body of a POST or PUT request. All such pairs occur, without distinction, in the HttpServletRequest map. Servlets may seem old hat, but they are a hat worth trying on for REST-style services. The remaining APIs build upon what servlets offer and, in this sense, represent a layering on top of servlets.

JAX-RS and Restlet are roughly peers, although this comparison might stir heated denials from either camp. Both of these APIs emphasize the use of Java annotations to describe the RESTful access to a particular CRUD operation. For example, methods that handle GET requests are annotated with @GET or @Get, those that handle POST requests are annotated with @POST or @Post, and so on. In both frameworks there are symbolic constants to specify MIME types and status codes. Further, each framework supports the automated generation of XML and JSON payloads. These frameworks have a contemporary look and feel, but each represents, at the implementation level, a layer above the servlet layer. When published with a web server such as Tomcat or Jetty, JAX-RS and Restlet provide servlet interceptors that mediate between the client and the web service. The details are explored in Chapter 2.

JAW-WS is an API used mostly for SOAP-based services but can be used for REST-style services as well. In the latter case, the @WebServiceProvider annotation is central. The @WebServiceProvider interface is sufficiently flexible that it can be used to annotate either a SOAP-based or a REST-style service; however, JAX-WS provides a related but higher level annotation, @WebService, for SOAP-based services. The @WebServiceProvider API is deliberately lower level than the servlet, JAX-RS, and Restlet APIs, and the @WebServiceProvider API is targeted at XML-based services. For programmers who need a low-level API, Java supports the @WebServiceProvider option. JAX-RS, Restlet, and @WebServiceProvider have both service-side and client-side APIs that can be used independently of one another. For example, a Restlet client could make calls against a JAX-RS service or vice versa.

In summary, Chapter 2 focuses on the server side of RESTful services. Chapter 3 shifts the focus to the client or consumer side of such services. The chapter includes client code against commercial RESTful services such as Amazon, Twitter, and the Chicago Transit Authority. The chapter also focuses on how the standard JAX-B (Java API for XML-Binding) packages and third-party libraries such as XStream can be put to good use by hiding the XML in the consumption of RESTful services. A dominant trend in contemporary web services is the occurrence of JavaScript clients against RESTful services. Such clients may be written in JavaScript or a dialect such as jQuery. In any case, these clients are usually embedded in HTML documents so that the clients execute in the context of a browser. JavaScript clients in general prefer JSON over XML payloads for the obvious reason that a JSON document is the text representation of a JavaScript object, even a JavaScript function. Chapter 3 also looks at various Java options for generating JSON as well as XML and plain-text responses, and the chapter explores different ways in which JavaScript clients can process the JSON payloads.