Java Web Services: Up and Running

Preface

This is a book for programmers interested in developing Java web services and Java clients against web services, whatever the implementation language. The book is a code-driven introduction to JAX-WS (Java API for XML-Web Services), the framework of choice for Java web services, whether SOAP-based or REST-style. My approach is to interpret JAX-WS broadly and, therefore, to include leading-edge developments such as the Jersey project for REST-style web services, officially known as JAX-RS (Java API for XML-RESTful Web Services).

JAX-WS is bundled into the Metro Web Services Stack, or Metro for short. Metro is part of core Java, starting with Standard Edition 6 (hereafter, core Java 6). However, the Metro releases outpace the core Java releases. The current Metro release can be downloaded separately from https://wsit.dev.java.net. Metro is also integrated into the Sun application server, GlassFish. Given these options, this book’s examples are deployed in four different ways:

Core Java only

This is the low-fuss approach that makes it easy to get web services and their clients up and running. The only required software is the Java software development kit (SDK), core Java 6 or later. Web services can be deployed easily using the Endpoint, HttpServer, and HttpsServer classes. The early examples take this approach.

Core Java with the current Metro release

This approach takes advantage of Metro features not yet available in the core Java bundle. In general, each Metro release makes it easier to write web services and clients. The current Metro release also indicates where JAX-WS is moving. The Metro release also can be used with core Java 5 if core Java 6 is not an option.

Standalone Tomcat

This approach builds on the familiarity among Java programmers with standalone web containers such as Apache Tomcat, which is the reference implementation. Web services can be deployed using a web container in essentially the same way as are servlets, JavaServer Pages (JSP) scripts, and JavaServer Faces (JSF) scripts. A standalone web container such as Tomcat is also a good way to introduce container-managed security for web services.

GlassFish

This approach allows deployed web services to interact naturally with other enterprise components such as Java Message Service topics and queues, a JNDI (Java Naming and Directory Interface) provider, a backend database system and the @Entity instances that mediate between an application and the database system, and an EJB (Enterprise Java Bean) container. The EJB container is important because a web service can be deployed as a stateless Session EJB, which brings advantages such as container-managed thread safety. GlassFish works seamlessly with Metro, including its advanced features, and with popular IDEs (Integrated Development Environment) such as NetBeans and Eclipse.

An appealing feature of JAX-WS is that the API can be separated cleanly from deployment options. One and the same web service can be deployed in different ways to suit different needs. Core Java alone is good for learning, development, and even lightweight deployment. A standalone web container such as Tomcat provides additional support. A Java application server such as GlassFish promotes easy integration of web services with other enterprise technologies.

Code-Driven Approach

My code examples are short enough to highlight key features of JAX-WS but also realistic enough to show off the production-level capabilities that come with the JAX-WS framework. Each code example is given in full, including all of the import statements. My approach is to begin with a relatively sparse example and then to add and modify features. The code samples vary in length from a few statements to several pages of source. The code is deliberately modular. Whenever there is a choice between conciseness and clarity in coding, I try to opt for clarity.

The examples come with instructions for compiling and deploying the web services and for testing the service against sample clients. This approach presents the choices that JAX-WS makes available to the programmer but also encourages a clear and thorough analysis of the JAX-WS libraries and utilities. My goal is to furnish code samples that can serve as templates for commercial applications.

JAX-WS is a rich API that is explored best in a mix of overview and examples. My aim is to explain key features about the architecture of web services but, above all, to illustrate each major feature with code examples that perform as advertised. Architecture without code is empty; code without architecture is blind. My approach is to integrate the two throughout the book.

Web services are a modern, lightweight approach to distributed software systems, that is, systems such as email or the World Wide Web that require different software components to execute on physically distinct devices. The devices can range from large servers through personal desktop machines to handhelds of various types. Distributed systems are complicated because they are made up of networked components. There is nothing more frustrating than a distributed systems example that does not work as claimed because the debugging is tedious. My approach is thus to provide full, working examples together with short but precise instructions for getting the sample application up and running. All of the source code for examples is available from the book’s companion site, at http://www.oreilly.com/catalog/9780596521127. My email address is [e-mail]. Please let me know if you find any code errors.

Chapter-by-Chapter Overview

The book has seven chapters, the last of which is quite short. Here is a preview of each chapter:

Chapter 1, Java Web Services Quickstart

This chapter begins with a working definition of web services, including the distinction between SOAP-based and REST-style services. This chapter then focuses on the basics of writing, deploying, and consuming SOAP-based services in core Java. There are web service clients written in Perl, Ruby, and Java to underscore the language neutrality of web services. This chapter also introduces Java’s SOAP API and covers various ways to inspect web service traffic at the wire level. The chapter elaborates on the relationship between core Java and Metro.

Chapter 2, All About WSDLs

This chapter focuses on the service contract, which is a WSDL (Web Service Definition Language) document in SOAP-based services. This chapter covers the standard issues of web service style (document versus rpc) and encoding (literal versus encoded). This chapter also focuses on the popular but unofficial distinction between the wrapped and unwrapped variations of document style. All of these issues are clarified through examples, including Java clients against Amazon’s E-Commerce services. This chapter explains how the wsimport utility can ease the task of writing Java clients against commercial web services and how the wsgen utility figures in the distinction between document-style and rpc-style web services. The basics of JAX-B (Java API for XML-Binding) are also covered. This chapter, like the others, is rich in code examples.

Chapter 3, SOAP Handling

This chapter introduces SOAP and logical handlers, which give the service-side and client-side programmer direct access to either the entire SOAP message or just its payload. The structure of a SOAP message and the distinction between SOAP 1.1 and SOAP 1.2 are covered. The messaging architecture of a SOAP-based service is discussed. Various code examples illustrate how SOAP messages can be processed in support of application logic. This chapter also explains how transport-level messages (for instance, the typical HTTP messages that carry SOAP payloads in SOAP-based web services) can be accessed and manipulated in JAX-WS. This chapter concludes with a section on JAX-WS support for transporting binary data, with emphasis on MTOM (Message Transmission Optimization Mechanism).

Chapter 4, RESTful Web Services

This chapter opens with a technical analysis of what constitutes a REST-style service and moves quickly to code examples. The chapter surveys various approaches to delivering a Java-based RESTful service: WebServiceProvider, HttpServlet, Jersey Plain Old Java Object (POJO), and restlet among them. The use of a WADL (Web Application Definition Language) document as a service contract is explored through code examples. The JAX-P (Java API for XML-Processing) packages, which facilitate XML processing, are also covered. This chapter offers several examples of Java clients against real-world REST-style services, including services hosted by Yahoo!, Amazon, and Tumblr.

Chapter 5, Web Services Security

This chapter begins with an overview of security requirements for real-world web services, SOAP-based and REST-style. The overview covers central topics such as mutual challenge and message confidentiality, users-roles security, and WS-Security. Code examples clarify transport-level security, particularly under HTTPS. Container-managed security is introduced with examples deployed in the standalone Tomcat web container. The security material introduced in this chapter is expanded in the next chapter.

Chapter 6, JAX-WS in Java Application Servers

This chapter starts with a survey of what comes with a Java Application Server (JAS): an EJB container, a messaging system, a naming service, an integrated database system, and so on. This chapter has a variety of code examples: a SOAP-based service implemented as a stateless Session EJB, WebService and WebServiceProvider instances deployed through embedded Tomcat, a web service deployed together with a traditional website application, a web service integrated with JMS (Java Message Service), a web service that uses an @Entity to read and write from the Java DB database system included in GlassFish, and a WS-Security application under GlassFish.

Chapter 7, Beyond the Flame Wars

This is a very short chapter that looks at the controversy surrounding SOAP-based and REST-style web services. My aim is to endorse both approaches, either of which is superior to what came before. This chapter traces modern web services from DCE/RPC in the early 1990s through CORBA and DCOM up to the Java EE and .NET frameworks. This chapter explains why either approach to web services is better than the distributed-object architecture that once dominated in distributed software systems.

Freedom of Choice: The Tools/IDE Issue

Java programmers have a wide choice of productivity tools such as Ant and Maven for scripting and IDEs such as Eclipse, NetBeans, and IntelliJ IDEA. Scripting tools and IDEs increase productivity by hiding grimy details. In a production environment, such tools and IDEs are the sensible way to go. In a learning environment, however, the goal is to understand the grimy details so that this understanding can be brought to good use during the inevitable bouts of debugging and application maintenance. Accordingly, my book is neutral with respect to scripting tools and IDEs. Please feel free to use whichever tools and IDE suit your needs. My how-to segments go over code compilation, deployment, and execution at the command line so that details such as classpath inclusions and compilation/execution flags are clear. Nothing in any example depends on a particular scripting tool or IDE.

Conventions Used in This Book

The following typographical conventions are used in this book:

Italic

Indicates new terms, URLs, filenames, file extensions, and emphasis.

Constant width

Used for program listings as well as within paragraphs to refer to program elements such as variable or method names, data types, environment variables, statements, and keywords.

Constant width bold

Used within program listings to highlight particularly interesting sections and in paragraphs to clarify acronyms.

Tip

This icon signifies a tip, suggestion, or general note.

Using Code Examples

This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Java Web Services: Up and Running, by Martin Kalin. Copyright 2009 Martin Kalin, 978-0-596-52112-7.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at [e-mail].

Safari^® Books Online

Note

When you see a Safari^® Books Online icon on the cover of your favorite technology book, that means the book is available online through the O’Reilly Network Safari Bookshelf.

Safari offers a solution that’s better than e-books. It’s a virtual library that lets you easily search thousands of top tech books, cut and paste code samples, download chapters, and find quick answers when you need the most accurate, current information. Try it for free at http://safari.oreilly.com.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

O’Reilly Media, Inc.

1005 Gravenstein Highway North

Sebastopol, CA 95472

800-998-9938 (in the United States or Canada)

707-829-0515 (international or local)

707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at:

http://www.oreilly.com/catalog/9780596521127/

To comment or ask technical questions about this book, send email to:

[e-mail]

For more information about our books, conferences, Resource Centers, and the O’Reilly Network, see our website at:

http://www.oreilly.com/

Acknowledgments

Christian A. Kenyeres, Greg Ostravich, Igor Polevoy, and Ken Yu were kind enough to review this book and to offer insightful suggestions for its improvement. They made the book better than it otherwise would have been. I thank them heartily for the time and effort that they invested in this project. The remaining shortcomings are mine alone, of course.

I’d also like to thank Mike Loukides, my first contact at O’Reilly Media, for his role in shepherding my initial proposal through the process that led to its acceptance. Julie Steele, my editor, has provided invaluable support and the book would not be without her help. My thanks go as well to the many behind-the-scenes people at O’Reilly Media who worked on this project.

This book is dedicated to Janet.