Chapter-by-Chapter Overview

The second edition has seven chapters. The following list offers a summary of each chapter.

Chapter 1, Web Services Quickstart
This chapter begins the code-driven tour of web services with an overview of the differences—and the similarities—between REST and SOAP. Why are web services of any use? This question is addressed with examples: one example focuses on using web services to automate access to the data and functionality available on the Web; the other example focuses on web services as a way to integrate diverse software systems. The theme of interoperability is pursued throughout the book with examples. Chapter 1 includes a short history of web services, with emphasis on how the SOA approach to distributed systems differs significantly from the DOA approach that predates yet continues to compete with web services. The chapter then focuses on how HTTP itself is at the center of the RESTful way to web-based, distributed software systems. XML and JSON are introduced as document-exchange formats of special interest in RESTful services. The chapter includes code examples: a pair of Java HTTP clients used to illustrate key features of HTTP; and a first RESTful service, which consists of a JSP script and two backend POJO classes. The curl utility is used to make sample client calls, including failed ones, against the first service. The chapter covers practical matters such as installing the Tomcat web server and using the provided Ant script to compile, package, and deploy a web service.
Chapter 2, RESTful Web Services: The Service Side
This chapter introduces various APIs and implementations available for programming and delivering RESTful web services in Java. The HttpServlet, JAX-RS, Restlet, and JAX-WS @WebServiceProvider APIs are explored through full code examples. The chapter clarifies various ways of generating XML and JSON payloads, using both standard Java classes and different third-party ones. The code examples adhere to RESTful principles such as honoring the intended meaning of each CRUD verb; using intuitive URIs to name resources; relying upon MIME data types to describe resource representations; and taking full advantage of those HTTP status codes that report on the outcome of an HTTP request against a RESTful service. Chapter 2, along with later chapters, looks at options for publishing RESTful services. The options include standalone web servers such as Tomcat and Jetty together with command-line publishers such as Endpoint, HttpServer, and Restlet Component. The chapter goes into the technical details of multithreading and thread synchronization in services deployed with a web server such as Tomcat or Jetty. The installation and management of Jetty are also covered. Chapter 2 also takes a first look at the powerful JAX-B (Java API for XML-Binding) and JAX-P (Java API for XML-Processing) utilities, which are especially important in the Chapter 3 coverage of the client side in RESTful services.
Chapter 3, RESTful Web Services: The Client Side
This chapter shifts focus from the service to the client side of RESTful services. There are sample clients written with the weathered but still trusty URLConnection class and also clients written using REST-specific APIs. (JAX-RS, Restlet, and JAX-WS provide both service-side and client-side APIs.) As evidence of interoperability, the chapter offers jQuery and Perl clients against Java services and Java clients against commercial services whose implementation language is officially unknown. The code samples explore various possibilities for dealing with XML and JSON payloads, in particular the standard JAX-B packages and third-party contributions such as XStream. These utilities are especially useful in transforming XML documents into native Java objects, which obviates the need for explicit parsing. Most RESTful services now furnish a grammar, in the form of an XML Schema or equivalent, for the service; core Java has utilities such as xjc that convert an XML Schema into Java classes. Chapter 3 has clients against real-world RESTful services at Twitter, Amazon, and the Chicago Transit Authority. This chapter pays special attention to the growing importance of JavaScript clients, which are highlighted in several examples using jQuery. Finally, the chapter shows how distinct web services can be orchestrated to form a single, composite service.
Chapter 4, SOAP-Based Web Services
This chapter turns from REST-style to SOAP-based services, in particular to the JAX-WS API and its central annotation @WebService. The chapter opens by converting a REST-style service from earlier chapters to a SOAP-based service. The emphasis in this chapter is on the application level, a level in which the XML in SOAP-based messaging remains transparent. Indeed, a chief attraction of SOAP-based services is that neither the services nor their clients require any attention to the underlying XML: service operations are, in Java, public methods preferably annotated with @WebMethod, and remote clients invoke the operations straightforwardly. The data types of arguments and return values include all of the primitive types and their wrappers, the String and Calendar types, various other standard types, arrays of any acceptable type, and programmer-defined classes whose properties reduce ultimately to any of these. The chapter explains in detail the programmer-friendly wsimport utility, which generates client-side support code from the web service contract, the WSDL (Web Service Description Language) document. The structure, purpose, and various uses of the WSDL are clarified through coding examples. The role of XML Schema or equivalent in a WSDL document is given particular emphasis. The chapter includes two Java clients against the Amazon E-Commerce service together with C# and Perl clients against a Java service. These examples underscore that SOAP-based services, like their REST-style cousins, are language-neutral. The clients against the SOAP-based version of the Amazon E-Commerce service introduce but do not explore the handler level of SOAP-based services; these examples also provide a first look at security issues.
Chapter 5, SOAP Handlers and Faults
This chapter examines the handler and transport levels in SOAP messaging, levels at which the XML in a SOAP message comes to the fore for inspection and manipulation. The chapter begins with a look at the SOAP message architecture, which distinguishes among a message sender; an intermediary that should confine its activity to the SOAP header rather than the SOAP body or attachments in a message; and an ultimate receiver, which should have access to the entire SOAP message. The distinct parts of SOAP messages, the raw XML and any attachments, are accessible to SOAP handlers, which come in two flavors: message handlers have access to the entire SOAP message (header, body, and attachments), whereas logical handlers have access only to the payload in the body. WS-Security and related extensions of SOAP beyond the basic profile may use such access to inject or inspect security elements in SOAP headers. Handlers are akin to Filter instances in websites, although handlers are inherently bidirectional and can occur on either the client or the service side. The chapter covers both individual handlers and handler chains, in this case a chain consisting of a message and a logical handler. The handler chain example mimics the user authentication at work in Amazon’s web services. The chapter likewise examines the related topic of SOAP faults, special error messages that can be generated at either the application or the handler level. The chapter also looks at how SOAP messages can transport arbitrary binary data as attachments. A final topic is the transport level, usually HTTP; this level is especially useful in the users/roles security examined in Chapter 6.
Chapter 6, Web Services Security
This chapter covers security, a topic that cuts across the REST/SOAP boundary, at three levels: wire-level security of the type that HTTPS provides, users/roles security, and WS-Security in SOAP-based messaging. The chapter begins with wire-level security and its constituent services of peer authentication, message confidentiality, and message integrity. The clarification of these terms requires, in turn, an examination of concepts such as symmetric and asymmetric encryption/decryption, public key security, cryptographic hash function, and cryptographic suite. HTTPS is examined in detail through coding examples: two HTTPS clients against the Google site and a lightweight HTTPS server built with the HttpsServer class that comes with the core Java JDK. There is also a sample HTTPS client against a RESTful service. These and other coding examples clarify additional security artifacts such as the keystore and the truststore, digital certificates, and certificate authority. There is a section to explain how a web server such as Tomcat can be set up to handle and even to enforce HTTPS connections. Chapter 6 also covers container-managed users/roles security, again with coding examples that involve a production-grade web server such as Tomcat. The two-phased user authentication and roles authorization process is studied in detail and includes examples of HTTP BASIC and DIGEST authentication. The chapter ends with a code example focused on WS-Security and its end-to-end approach to security.
Chapter 7, Web Services and Java Application Servers
This chapter introduces the Java Application Server as an alternative to the standalone web server for deploying REST-style and SOAP-based services. The JAS as a service publisher also brings the option of deploying a web service as an EJB, in particular a web service as a @Stateless Session EJB. The chapter begins with a list of the popular JASes and then clarifies the core components and attendant functionalities of a JAS. There is a review of how sample services from previous chapters—from HttpServlet examples through JAX-RS, Restlet, @WebServiceProvider, and @WebService examples—can be ported to a JAS. In all cases, almost no change is required. Chapter 7 also motivates the option of a JAS, in particular the benefits that come with deploying a service in the thread-safe EJB container. A typical JAS is not only a publisher but also a development, testing, and management environment. This chapter has a further coding example of how web services and websites can interact, and the excellent JPA (Java Persistence API) is introduced with two coding examples that persist data in different databases: HSQLDB and Java Derby. The chapter introduces two JASes through code examples: GlassFish, which is the reference implementation, and TomEE, which is an emphatically lightweight option among JASes. Various sidebars explain installation and management details. The chapter ends with a review and a recommendation that programmers embrace the many excellent choices of API and implementation that Java offers in the area of web services.

Get Java Web Services: Up and Running, 2nd Edition now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.