This book is a code-centric tour through the APIs and implementation technologies that support web services under Java. The tour has taken seven chapters. To set up an answer to the question posed in this section’s title, it may be useful to review the stops along the way.
This chapter narrows the focus to the various APIs and API implementations available for programming and delivering REST-style services in Java. The main APIs are:
HttpServlet classes along with JSP and other scripts that become, at runtime, instances of HttpServlet.
JAX-WS with its relatively low-level @WebServiceProvider and XML-centric API that gets the programmer close to the
metal.
This chapter looks at various ways of generating both XML and JSON payloads, particularly given the rising
popularity of JSON as a data-interchange format. Java offers a range of options for XML generation, from the
XMLEncoder class to the rich assortment of classes in the JAX-B packages. The code samples adhere to RESTful
principles such as honoring the intended meaning of each CRUD verb, using intuitive URIs to name resources, and
taking full advantage of HTTP status codes to signal the fate of a request against a REST-style service.
Chapter 2 and later chapters also explore, for publishing these RESTful services, production-grade web servers such as Tomcat
and Jetty together with
development-level publishers such as Endpoint, HttpsServer, and the Restlet Component. All of the APIs are quite good, on
the service side and on the client side, at
adhering to the separation-of-concerns principle: the programming of a web service is one thing and its publication is another—and
independent—thing.
This chapter turns from the service side to the client side. There are clients based upon the
grizzled but trusty URLConnection class and upon REST-specific client-side APIs such as JAX-RS.
As proof of concept for interoperability, clients are written in different languages. For instance, there are Perl and jQuery clients
against Java services and Java clients against services whose implementation language is unknown.
The code samples explore
the various possibilities for dealing with XML and JSON payloads, in particular with the standard JAX-B and the third-party
utilities such as XStream for automating the transformation of XML documents in particular into native Java objects.
Most modern RESTful services furnish at least an XML Schema for the service, and Java has utilities such as xjc that covert
an XML Schema or comparable XML-based grammar into Java types. The chapter has clients against real-world services. For
instance, there are two sample clients against Amazon’s E-Commerce service as well as clients against the Twitter and Chicago Transit Authority
RESTful services.
The chapter pays special attention to the growing importance of JavaScript clients against RESTful services, in particular JavaScript clients embedded in HTML documents. The JavaScript clients are written in the widely used jQuery dialect, and these clients highlight ways in which JSON payloads can be treated as native JavaScript objects. This chapter also illustrates how web services can be composed or orchestrated, that is, built out of other web services.
These chapters turn from REST-style to SOAP-based web services, in particular to the JAX-WS API and its @WebService annotation.
Chapter 4 focuses on the application level in SOAP-based services,
a level at which SOAP, an XML dialect, remains transparent. Chapter 5 studies the handler level at which the entire SOAP message or
the payload in the SOAP body are exposed for inspection and manipulation. This chapter also looks at the transport level, which provides
access to HTTP(S) transport in particular. The handler level and the transport level are especially important for security, the
topic of Chapter 6.
In terms of popularity, SOAP-based services have lost ground in recent years to REST-style ones; indeed, REST-style services can be seen as a reaction against the creeping complexity of SOAP-based frameworks and services. Yet if SOAP-based services are delivered over HTTP(S), then such services can be seen as a programmer-friendly variant of REST-style services. The programmer-friendliness comes from the fact that SOAP hides the XML payloads, allowing programmers on either the service side or the client side to deal with familiar native data types.
SOAP effectively and fully automates the transformation between native language types and XML types: there is no reason, at the application level, ever to create manually or to parse an XML document. The basic profile of SOAP remains uncomplicated, and this profile promotes interoperability through its powerful, high-level API. Furthermore, dynamically generated service contracts—the WSDL documents—are ubiquitous in the SOAP world. Major SOAP frameworks such as Java and DotNet furnish utilities (in Java, wsimport) that can generate client-support code from the document. Although WSDLs could be used in the RESTful world, they typically are not; nothing in the RESTful world quite matches the ease of writing a client against a SOAP-based service. In short, SOAP-based services still deserve serious consideration.
Chapters 4 and 5 also include clients against real-world services such as the Amazon’s E-Commerce service, and the chapters explore both synchronous and asynchronous clients. SOAP-based web services, like their REST-style cousins, usually work with text payloads—XML or JSON documents. Yet SOAP messages can include arbitrarily many binary attachments, which Chapter 5 shows with code examples. For the most part, the examples in Chapters 4 and 5 use the Metro implementation of JAX-WS. However, there is also an example of an Axis2 service and an Axis2 client. Axis2 remains a popular, alternative implementation of JAX-WS.
This chapter covers security, a core issue that cuts across SOAP and REST. The chapter opens with a study of wire-level security and services that a transport protocol such as HTTPS offers: peer authentication, message confidentiality, and message integrity. Underlying technologies like message digest, message encryption and decryption, digital certificate, certificate authority, and cipher suite are clarified in due course. The concepts are fleshed out in a series of examples, starting with a simple Java HTTPS client against the Google home site. Another example builds a very lightweight HTTPS server and an HTTPS client against a RESTful service published with this server. Wire-level security is, for services delivered over HTTP, required infrastructure for the next security level, commonly known as users/roles security. The relevant concepts are user authentication (that is, establishing a user’s true identity) and role authorization (that is, fine-tuning the access permissions for an authenticated user).
Managing users/roles security at the service level is tricky; for one thing, this approach does not scale well. The recommended approach is container-managed security: the user authentication and role authorization are handed off from the web service to the (servlet) container. The configuration is relatively easy and the responsibility then shifts from the web service to the publisher such as Tomcat or Jetty. Indeed, a chief benefit of using a production-grade web server is that it can handle both wire-level security (typically in the form of HTTPS) and users/roles security.
For users/roles security, client access to the transport level is critical because an identity such as username and a credential such as a password typically are expected, on the service side, to be inside the HTTP request header. Various ways of injecting header blocks in an HTTP request are thus covered with examples. Wire-level and users/roles security are equally pertinent in REST-style and SOAP-based services. By contrast, WS-Security is a relevant only in SOAP-based services and represents an effort to provide end-to-end security at the SOAP level rather than at the transport (that is, HTTPS) or container (that is, Tomcat or Jetty) level. The WS-* initiatives, which promote the goals of transport-neutral and container-neutral messaging, are what make SOAP complicated. The chapter ends with a WS-Security example, which provides a first look at SOAP beyond the basic profile.
The current chapter considers the trade-offs in deploying web services with a JAS rather than
with a standalone web server such
as Tomcat or Jetty. Various JASes are available: IBM WebSphere, Oracle WebLogic, Red Hat JBoss, Apache Geronimo, GlassFish, and
Apache TomEE. This chapter begins
with an overview of the components and resources that are bundled into a JAS. Among these are a web container, an EJB container, a
message-oriented middleware provider, a naming service, a security service, and usually a database management system. A web service, REST-style
or SOAP-based, that can be published with a standalone web server such as Tomcat can be published, essentially as is, with a JAS. Such services
are described as servlet-based because the service itself either executes as an HttpServlet instance or relies upon such an
instance (e.g., the WSServlet that comes with Metro) as an intermediary between the client and web service. A JAS offers, as an alternative,
an EJB-based service, which could be REST-style or SOAP-based.
Of particular interest
is that a @Stateless Session EJB becomes a SOAP-based web service if annotated as a @WebService. The
EJB’s public methods become service operations if annotated with @WebMethod. An EJB-based service, unlike a servlet-based one, is
thread-safe because the EJB container bestows thread safety on the components therein. This chapter also
covers some miscellaneous topics
such as the interaction of a GlassFish-hosted website and a Tomcat-hosted web service; the chapter revisits the JAX-WS client-side
API with a sample client against a Restlet service. The main example is a SOAP-based service that uses JPA to
persist data in a backend database. GlassFish and TomEE are contrasted as two modern JASes.
In summary, the book explores Java-based web services with code examples that cover a range of APIs and implementations. The code examples themselves are meant to highlight the pluses and minuses. Nonetheless, this code-driven exploration invites an obvious question: Where is the best place to be with respect to Java web services? Which API is superior to the rest? Which implementation should be preferred over the others? These questions, natural as they are, overlook a principal reason for using Java in the first place. To be sure, the Java language and the JVM runtime are major players in the world of software development and deployment, and the runtime is best-in-breed among production-grade virtual machines. From the start, however, Java has been renowned for its options. There is no single IDE for Java or even a single library for, say, parsing XML, making network connections, or implementing users/roles security. There is now growing variety among the languages that compile to JVM byte-codes and are able to reference the huge number of runtime libraries, standard and third party, available in the JVM. There is even choice about which Java runtime to use.
A sensible principle in software development is to pick the least complicated toolset that is up to the task at hand.
The toolkit for Java web services is rich in tools. It makes no sense to declare a winner among, for example, the
HttpServlet, JAX-RS/Restlet, and @WebServiceProvider APIs for REST-style services. These APIs differ and in this
difference are to be found choices for addressing specific programming and deployment challenges. For SOAP-based services,
even the JAX-WS API has
at least two excellent implementations, Metro and Axis2; Axis2 adds features to JAX-WS for those who require such
extensions. For publishing web services, the choices are likewise varied, from development and testing environments through staging and up to
production-level publishing. Tomcat and Jetty are excellent standalone
web servers that include first-rate servlet containers. It is hard to make a bad choice here. The next step up, in complexity
but also in features, is where the Java Application Servers are. Even here there are choices. WebSphere and Oracle WebLogic have been in
the game for a long time, and their for-free counterparts such as Geronimo, GlassFish, JBoss, and TomEE are likewise fine pieces
of software. Over the past decade, the Java EE API has become simpler and, therefore, more attractive. JPA is an API that deserves a
special pat on the back. At the implementation level, the thread safety that comes with an EJB container is enticing.
Where is the best place to be in Java web services? The answer depends on the challenges in place and resources at hand. Java comes with first-rate options for programming and publishing web services, REST-style and SOAP-based. This means that the question has more than one good answer. Let the task at hand and the resources in place decide the matter.