Java Web Services: Up and Running, 2nd Edition

Web Service APIs and Publication Options

In the first edition, the JAX-WS APIs and their Metro implementation were dominant. In this edition, the two are important but less dominant. For REST-style services, the book has examples based on the following APIs:

HttpServlet

The HttpServlet is well designed for REST-style services because the API is so close to the HTTP metal. Servlet instances encapsulate callbacks such as doPost, doGet, doPut, and doDelete, which cover the familiar CRUD operations: create (POST), read (GET), update (PUT), and delete (DELETE). There are symbolic versions of HTTP status codes to signal the outcome of an HTTP request, support for MIME types, utilities to access HTTP headers and bodies, and so on. JSP and other Java-based scripts execute as servlet instances and, therefore, fall under the servlet umbrella. The HttpServlet is grizzled but hardly obsolete. Servlets are still an excellent way to deliver REST-style services.

JAX-RS

This is a relatively recent and increasingly popular API for delivering REST-style services. The API centers on annotations such as @GET and @POST to route HTTP requests to particular Java methods. There is likewise a convenient @Path annotation to identify the particular resource targeted in a request. JAX-RS can be configured to automatically generate XML and JSON responses. This API, like the Restlet API described next, has a contemporary look and feel. At the implementation level, JAX-RS represents a layering atop servlets. The same options for publishing servlet-based services are available for their JAX-RS cousins.

Restlet

This API is similar in style to JAX-RS, although the claim is likely to upset proponents of both. The Restlet API also centers on annotations for routing HTTP requests to designated Java methods and for generating payloads. Restlet encourages interplay with other APIs. It is possible, for example, to use JAX-RS annotations in a Restlet-based service. Restlet offers an easy-to-use publisher for development and testing. Restlet services, like their JAX-RS counterparts, represent an implementation level on top of servlets. Programmers should be able to move easily between the JAX-RS and Restlet APIs.

JAX-WS @WebServiceProvider

This is a deliberately XML-centric and low-level API that could be used for either SOAP-based or REST-style services. However, JAX-WS has the @WebService annotation precisely for SOAP-based services; hence, the most obvious use of the @WebServiceProvider annotation is for XML-based REST-style services. This API is well suited for services that require granular control over XML generation and processing.

For SOAP-based services, most of the examples use the reference implementation of JAX-WS, which is Metro. However, this edition now covers Axis2 as well. Axis2 implements JAX-WS but has additional features.

The Publication Options

Each of these APIs, whether for REST-style or SOAP-based services, honors the separation-of-concerns principle with respect to publishing a web service. The web service is one concern; its publication is quite another concern. Services developed with any of these APIs can be published with a standalone web server such as Tomcat, a Java Application Server (JAS) such as GlassFish, or even with a simple command-line utility such as the standard Endpoint publisher. To underscore the separation-of-concerns principle and to emphasize the production-grade options, my examples are published in the following ways:

Standalone web servers

The two obvious choices in Java are Tomcat and Jetty, although other choices are available. The aforementioned Ant script automatically compiles and packages web services, REST-style and SOAP-based alike, for publication. Although the Ant script is tailored for Tomcat publication, a generated WAR file can be deployed, as is, to Jetty, Tomcat, or one of the many JASes. Tomcat and Jetty provide the usual services such as wire-level and users/roles security, logging/debugging, and administration that one expects from a production-grade web server.

Java Application Servers

The reference implementation is still GlassFish, which is part of the community-based Metro project. GlassFish can be used to publish either servlet-based services, which are the type that Tomcat and Jetty can publish, or EJB-based services, which are @Stateless Session Enterprise JavaBeans. TomEE, which is essentially Tomcat7 with OpenEJB extensions, is an emphatically lightweight publisher of both servlet-based and EJB-based services. Under TomEE, even an EJB-based service can be deployed as a standard WAR (Web ARchive) file. TomEE includes an implementation of JAX-RS.

Command-line publishers

Examples are the standard Endpoint utility class and the Restlet Component class. These publishers are useful for development, testing, and even low-volume production.

Java in general draws strength from the many options that the language and the run-time offer; this strength carries over to web services as well. There are many ways to program web services and web service clients in Java, and there are various attractive options for publishing such services. There is no need to claim any particular way in web services as the best way. My aim is to examine and clarify the choices so that in the end, the API, implementation, and method of publication can be determined by what is best suited for the service.