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:
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
HttpsServer classes. The early examples
take this approach.
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.
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.
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
@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.
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
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 firstname.lastname@example.org. Please let me know if you find any code errors.
The book has seven chapters, the last of which is quite short. Here is a preview of each chapter:
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.
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 (
rpc) and encoding (
encoded). This chapter also focuses on
the popular but unofficial distinction between the
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
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
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).
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:
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,
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.
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,
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
read and write from the Java DB database system included in
GlassFish, and a WS-Security application under GlassFish.
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.
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.
The following typographical conventions are used in this book:
Indicates new terms, URLs, filenames, file extensions, and emphasis.
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.
This icon signifies a tip, suggestion, or general note.
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 email@example.com.
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.
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)|
We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at:
To comment or ask technical questions about this book, send email to:
For more information about our books, conferences, Resource Centers, and the O’Reilly Network, see our website at:
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.