ÿØÿà Java™ Web Services in Nutshell By Kim Topley Publisher: O'Reilly Pub Date: June 2003 ISBN: 0-596-00399-4 Copyright Preface Contents of This Book Related Books Web Services Programming Resources Online Examples Online Conventions Used in This Book Request for Comments Acknowledgments Part I: Introduction to the Java Web Services API Chapter 1. Introduction Section 1.1. What Is a Web Service? Section 1.2. The SOAP Protocol Section 1.3. Describing and Discovering Web Services Section 1.4. J2EE Web Service APIs Section 1.5. An Example Web Service Chapter 2. JAX-RPC Section 2.1. JAX-RPC Overview Section 2.2. Programming with JAX-RPC Section 2.3. Using EJBs to Implement Web Services Chapter 3. SAAJ Section 3.1. Introduction to SAAJ Section 3.2. SAAJ Programming Section 3.3. SOAP Messages Section 3.4. SOAP Fault Handling Section 3.5. SOAP Messages and MIME Headers Section 3.6. SOAP with Attachments Section 3.7. SOAP Headers Section 3.8. Using SAAJ with Secure Connections Chapter 4. JAXM Section 4.1. JAXM Overview Section 4.2. Providers and Asynchronous Messaging Section 4.3. An Example JAXM Application Section 4.4. JAXM Configuration Section 4.5. The SOAP-RP Profile Section 4.6. The ebXML Profile Chapter 5. WSDL Section 5.1. WSDL Overview Section 5.2. WSDL Elements Chapter 6. Advanced JAX-RPC Section 6.1. Using WSDL with JAX-RPC Section 6.2. ServiceFactory and the Service Interface Section 6.3. The Dynamic Invocation Interface Section 6.4. JAX-RPC and J2EE 1.4 Application Clients Section 6.5. Using Attachments Section 6.6. RPC-Style and Document-Style JAX-RPC Section 6.7. Client and Server Context Handling Section 6.8. SOAP Header Processing Section 6.9. Serialization and Type Mappings Chapter 7. JAXR Section 7.1. UDDI and ebXML Registries Section 7.2. JAXR Architecture Section 7.3. Using the JAXR Examples Section 7.4. JAXR Registry Model Overview Section 7.5. JAXR Programming Chapter 8. Web Service Tools and Configuration Files Section 8.1. wscompile - JAX-RPC Stub and Tie Generation Utility Section 8.2. wsdeploy - JAX-RPC Deployable Web Archive Generation Utility Section 8.3. J2EEC - Utility for Creating Stubs and Ties for a JAX-RPC Web Service Section 8.4. J2EE Deploytool - Utility for Deploying Modules and Enterprise Applications Section 8.5. JAXM Client and Provider Configuration Section 8.6. J2EE 1.4 Web Services Configuration File Section 8.7. J2EE 1.4 JAX-RPC Mapping File Part II: API Quick Reference Chapter 9. The javax.xml.messaging Package Package javax.xml.messaging Endpoint JAXMException JAXMServlet OnewayListener ProviderConnection ProviderConnectionFactory ProviderMetaData ReqRespListener URLEndpoint Chapter 10. The javax.xml.namespace Package Package javax.xml.namespace QName Chapter 11. The javax.xml.registry Package Package javax.xml.registry BulkResponse BusinessLifeCycleManager BusinessQueryManager CapabilityProfile Connection ConnectionFactory DeclarativeQueryManager DeleteException FederatedConnection FindException FindQualifier InvalidRequestException JAXRException JAXRResponse LifeCycleManager Query QueryManager RegistryException RegistryService SaveException UnexpectedObjectException UnsupportedCapabilityException Chapter 12. The javax.xml.registry.infomodel Package Package javax.xml.registry.infomodel Association AuditableEvent Classification ClassificationScheme Concept EmailAddress ExtensibleObject ExternalIdentifier ExternalLink ExtrinsicObject InternationalString Key LocalizedString Organization PersonName PostalAddress RegistryEntry RegistryObject RegistryPackage Service ServiceBinding Slot SpecificationLink TelephoneNumber URIValidator User Versionable Chapter 13. The javax.xml.rpc Package Package javax.xml.rpc Call JAXRPCException NamespaceConstants ParameterMode Service ServiceException ServiceFactory Stub Chapter 14. The javax.xml.rpc.encoding Package Package javax.xml.rpc.encoding DeserializationContext Deserializer DeserializerFactory SerializationContext Serializer SerializerFactory TypeMapping TypeMappingRegistry XMLType Chapter 15. The javax.xml.rpc.handler Package Package javax.xml.rpc.handler GenericHandler Handler HandlerChain HandlerInfo HandlerRegistry MessageContext Chapter 16. The javax.xml.rpc.handler.soap Package Package javax.xml.rpc.handler.soap SOAPMessageContext Chapter 17. The javax.xml.rpc.holders Package Package javax.xml.rpc.holders BigDecimalHolder BigIntegerHolder BooleanHolder BooleanWrapperHolder ByteArrayHolder ByteHolder ByteWrapperHolder CalendarHolder DoubleHolder DoubleWrapperHolder FloatHolder FloatWrapperHolder Holder IntegerWrapperHolder IntHolder LongHolder LongWrapperHolder ObjectHolder QNameHolder ShortHolder ShortWrapperHolder StringHolder Chapter 18. The javax.xml.rpc.server Package Package javax.xml.rpc.server ServiceLifecycle ServletEndpointContext Chapter 19. The javax.xml.rpc.soap Package Package javax.xml.rpc.soap SOAPFaultException Chapter 20. The javax.xml.soap Package Package javax.xml.soap AttachmentPart Detail DetailEntry MessageFactory MimeHeader MimeHeaders Name Node SOAPBody SOAPBodyElement SOAPConnection SOAPConnectionFactory SOAPConstants SOAPElement SOAPElementFactory SOAPEnvelope SOAPException SOAPFactory SOAPFault SOAPFaultElement SOAPHeader SOAPHeaderElement SOAPMessage SOAPPart Text Class, Method, and Field Index A-G H-X Part III: Appendix Appendix A. Appendix: WSDL Files for the Example Source Code Section A.1. WSDL File for the Book Web Service Section A.2. WSDL File for the Document-Style Book Web Service Colophon Index Top 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 (http://safari.oreilly.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or [email protected]. 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. Preface 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 Amazon.com, 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