Copyright 2003 O'Reilly & Associates, Inc.

Printed in the United States of America.

Published by O'Reilly & Associates, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472.

O'Reilly & Associates books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles ( For more information, contact our corporate/institutional sales department: (800) 998-9938 or

Nutshell Handbook, the Nutshell Handbook logo, and the O'Reilly logo are registered trademarks of O'Reilly & Associates, Inc. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries . O'Reilly & Associates, Inc. is independent of Sun Microsystems.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O'Reilly & Associates, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. The association between the image of a European ibex and the topic of Java Web Services is a trademark of O'Reilly & Associates, Inc.

While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.



This book is a desktop quick reference for programmers writing web services or web service clients using the Java programming language. Part I offers a fast-paced but comprehensive tutorial covering the web service APIs that are part of the J2EE 1.4 platform and the Java Web Services Developer Pack (JWSDP), both of which provide all of the software needed to develop and test web services using Sun's reference implementations of these technologies. These chapters are followed by a quick-reference section that details each class and interface in the web service APIs covered in the tutorial.

This book is intended to be used in conjunction with the best-selling O'Reilly titles Java in a Nutshell , by David Flanagan and Java Enterprise in a Nutshell , by William Crawford, Jim Farley, and David Flanagan. Java in a Nutshell introduces the Java programming language and provides an API quick reference for the core packages and classes of the Java 2 Standard Edition (J2SE) platform, while Java Enterprise in a Nutshell does the same for the APIs in the Java 2 Enterprise Edition (J2EE). Web services leverage technology that is provided by J2EE (including XML, servlets, and Enterprise JavaBeans ) and therefore at least a basic working knowledge of the Java programming language and its enterprise features is required in order to get the best from this book.


Contents of This Book

Part I, which is the first eight chapters of this book, provides an introduction to web services and tutorial material for the APIs and command-line tools that are provided by the J2EE 1.4 platform and the Java Web Services Developer Pack (JWSDP):

Chapter 1

This chapter is a short but practical introduction to web services in general and to the support provided for web services by both the JWSDP and the J2EE 1.4 platform. The second part of this chapter provides a quick overview of the JAX-RPC API and shows how you might use it to create a client that can browse through the books available at, using that company's store-browsing web service.

Chapter 2

For most web service developers, JAX-RPC is the most important of the APIs covered in this book. This chapter provides a basic introduction to JAX-RPC and shows you how to create a simple service and a client that can be used to access it, starting from a Java definition of the interface that the service provides. This chapter also discusses the use of both servlets and Enterprise JavaBeans (EJBs) to host JAX-RPC services and the tools that you need to build and deploy them.

Chapter 3

While JAX-RPC is probably the most commonly used web service API, the SOAP with Attachments API for Java (or SAAJ) is the API that appeals most to those who like to see and understand what goes on "under the hood." SAAJ provides the means to create and receive raw SOAP messages. It requires you to build and decode each message at the XML element level. This chapter covers all of the SAAJ API, including the use of MIME attachments, which allow you to transfer arbitrary content, such as images and sound files.

Chapter 4

JAXM is a development of SAAJ that provides asynchronous messaging and more reliable delivery. In this chapter, you'll see how to make use of these features and how to configure the reference implementation so that your JAXM clients can communicate with each other. This chapter also looks at the two SOAP message profiles, SOAP-RP and ebXML TRP, that are supported by the reference implementation.

Chapter 5

The Web Service Description Language (WSDL) is an application of XML that lets you describe the interface to a web service in implementation-independent terms. One of the most useful features of WSDL is that it can be both created and consumed easily by software tools; as a result, you can use it to publish the interface to a web service implemented in Java or a different programming language, and create from the WSDL definition artifacts that allow clients for that service to be written in any language on any platform that has support for web services. Chapter 5 looks at the grammar of a WSDL document, preparing the way for the application of WSDL in Chapter 6.

Chapter 6

This lengthy chapter starts by showing you how to use JAX-RPC to import a WSDL definition of a web service and then generate the Java interface and other classes required to let you build a client for that service. It goes on to demonstrate the wide range of powerful features that the JAX-RPC API provides, including support for both document- and RPC-based services, the use of MIME attachments with JAX-RPC web services, and SOAP message handlers, which let you process and extract data from or insert data into a SOAP message without modifying the code for the client or server that will generate or consume the message.

Chapter 7

This chapter covers the Java API for XML-based Registries (JAXR). Registries allow organizations to publish their services so that would-be clients can discover them, learn how to access them and, eventually, do business using them. The JAXR API supports both the UDDI and ebXML registries in such a way as to make it possible to write a registry client application that can work with either of them without requiring any registry-specific code, while still allowing applications that need access to features that are offered by only one registry or the other to be created.

Chapter 8

Both the JWSDP and J2EE 1.4 provide a number of tools that you need to use when creating web services. This chapter documents both the tools themselves and the configuration files that are required to control them.

Part II (Chapter 9 to Chapter 20) forms the API quick reference, which is a succinct but detailed API reference formatted for optimum ease of use. Please be sure to read How to Use This Quick Reference , which appears at the beginning of the reference section; it explains how to get the most out of these chapters.