WebObjects Web Services Programming Guide (Legacy) 2007-07-11 MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS Apple Inc. PROVIDED “AS IS,” AND YOU, THE READER, ARE © 2002, 2007 Apple Inc. ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. All rights reserved. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR No part of this publication may be reproduced, CONSEQUENTIAL DAMAGES RESULTING FROM ANY stored in a retrieval system, or transmitted, in DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. any form or by any means, mechanical, THE WARRANTY AND REMEDIES SET FORTH ABOVE electronic, photocopying, recording, or ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL otherwise, without prior written permission of OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make Apple Inc., with the following exceptions: Any any modification, extension, or addition to this person is hereby authorized to store warranty. documentation on a single computer for Some states do not allow the exclusion or limitation personal use only and to print copies of of implied warranties or liability for incidental or consequential damages, so the above limitation or documentation for personal use provided that exclusion may not apply to you. This warranty gives the documentation contains Apple’s copyright you specific legal rights, and you may also have notice. other rights which vary from state to state. The Apple logo is a trademark of Apple Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Finder, Mac, Mac OS, WebObjects, and Xcode are trademarks of Apple Inc., registered in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. Times is a registered trademark of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. Simultaneously published in the United States and Canada. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, Contents Introduction Introduction to WebObjects Web Services Programming Guide 7 Organization of This Document 7 See Also 7 Chapter 1 Web Services Overview 9 What Are Web Services? 9 Web Service Discovery 10 Web Services and SOAP 10 Ingredients of a SOAP Message 11 Web Service Description 14 SOAP Engine 15 The Axis SOAP Engine 16 Serialization and Deserialization of Objects 18 Chapter 2 Security in Web Services 21 Web Services Security 22 Digital Signatures 22 Encryption 24 Canonical XML Documents 24 Chapter 3 Developing Web Service Applications 27 Providing a Web Service 27 Consuming a Web Service 28 Using Sessions in Web Services 30 Accessing the WOContext Object 35 Adding Security to Web Services 35 Web Service Deployment Descriptors 36 Adding Web Service Support to Existing Projects 38 Chapter 4 Developing Direct to Web Services Applications 39 The Data Model 39 Creating a Direct to Web Services Application Project 41 Web Services Assistant 42 Adding a Web Service 43 Adding an Operation 44 Testing an Operation 46 Using WODefaultWebService Operations 47 3 Legacy Document | 2007-07-11 | © 2002, 2007 Apple Inc. All Rights Reserved. CONTENTS Observing SOAP Messages Using TCPMonitor 51 Freezing Operations 52 Unfreezing Operations 57 Component-Based Operations 58 Operations Derived From Fetch Specifications 59 Using Transactions 59 Using Global IDs 59 Default Return Values of Operations 61 Creating a Custom Rule File 62 Rule Editor Keys 62 Document Revision History 65 Glossary 67 4 Legacy Document | 2007-07-11 | © 2002, 2007 Apple Inc. All Rights Reserved. Figures, Tables, and Listings Chapter 1 Web Services Overview 9 Figure 1-1 Structure of a SOAP message 12 Figure 1-2 Organization of a WSDL document 15 Figure 1-3 The SOAP Message processing cycle 16 Figure 1-4 Web service processing—provider view 17 Figure 1-5 Web service processing—consumer view 18 Table 1-1 The elements of a SOAP message 13 Table 1-2 Attributes defined in the SOAP specification 14 Table 1-3 Serializers and deserializers provided in WebObjects 18 Listing 1-1 Example of an RPC SOAP message 12 Listing 1-2 Example of a document-style SOAP message 12 Chapter 2 Security in Web Services 21 Figure 2-1 Structure of a digital signature element 23 Table 2-1 Features provided by the major security approaches 21 Listing 2-1 Example SOAP message using a digital signature 23 Listing 2-2 Person elements 24 Chapter 3 Developing Web Service Applications 27 Figure 3-1 A possible user interface to the Calculator Web service 30 Listing 3-1 Calculator.java class in Calculator project 27 Listing 3-2 CalculatorClient.java class in Calculator_Client project 28 Listing 3-3 Session_Client project—Application.java file 31 Listing 3-4 Session_Client project—SessionClient.java file 31 Listing 3-5 Session project—LogIn.java file 34 Listing 3-6 Session project—AccessData.java file 34 Listing 3-7 Accessing the WOContext object from a Web service class 35 Listing 3-8 The server.wsdd file of a Web service provider project 36 Listing 3-9 The client.wsdd file of a Web service consumer project 37 Chapter 4 Developing Direct to Web Services Applications 39 Figure 4-1 Listing entity defined in the RealEstate data model 40 Figure 4-2 ListingAddress entity defined in the RealEstate data model 41 Figure 4-3 Connect dialog of Web Services Assistant 42 Figure 4-4 The Web Services Assistant main window 43 Figure 4-5 The New Operation dialog 45 Figure 4-6 The findHouseByAskingPrice operation of the HouseSearch Web service 45 5 Legacy Document | 2007-07-11 | © 2002, 2007 Apple Inc. All Rights Reserved. FIGURES, TABLES, AND LISTINGS Figure 4-7 The test window of the findHouseByAskingPrice operation 47 Figure 4-8 TCPMonitor window 52 Figure 4-9 The FindHouseByCity component—the frozen version of the findHouseByCity operation 54 Figure 4-10 Relationship between Author entity and Book entity 60 Figure 4-11 Definition of the addBook operation 61 Table 4-1 Default return values of operations 61 Table 4-2 Direct to Web Services rule keys 62 Listing 4-1 Properties file of the HousesForSale project 42 Listing 4-2 The WSDL document of the frozen findHouseByCity operation—the HTML file of the FindHouseByCity component 54 Listing 4-3 addBookForAuthor method 60 Listing 4-4 addAuthor and addBooks methods 60 6 Legacy Document | 2007-07-11 | © 2002, 2007 Apple Inc. All Rights Reserved. INTRODUCTION Introduction to WebObjects Web Services Programming Guide Important: The following tools are deprecated and no longer supported in WebObjects 5.4 and later: EOModeler, RuleEditor, WebObjects Builder, WOALauncher, and Java Client. WebObjects templates are not available for creating new projects in Xcode on Mac OS X v10.5 and later. Important: The information in this document is obsolete and should not be used for new development. Links to downloads and other resources may no longer be valid. Note: This document was previously titled Web Services . Web services SOAP Organization of This Document This document has the following chapters: ■ “Web Services Overview” (page 9) ■ “Security in Web Services” (page 21) ■ “Developing Web Service Applications” (page 27) ■ “Developing Direct to Web Services Applications” (page 39) ■ “Document Revision History” (page 65) See Also The following list itemizes resources you can use to increase your Web services knowledge. ■ The AmazonClient project in /Developer/Examples/JavaWebObjects/AmazonClient is an implementation of a client for Amazon.com Web services. ■ Building Web Services with Java: Making Sense of XML, SOAP, WSDL, and UDDI (Sams) gives great detail on the elements of Web-service development and deployment. ■ Architecting Web Services (Apress) provides a high-level view of Web-service development. Organization of This Document 7 Legacy Document | 2007-07-11 | © 2002, 2007 Apple Inc. All Rights Reserved. INTRODUCTION Introduction to WebObjects Web Services Programming Guide ■ Java & XML (O'Reilly) introduces you to XML and processing XML documents using SAX (Simple API for XML). ■ Web Services Routing Protocol (WS-Routing) (http://msdn.microsoft.com/library/en-us/dnglobspec/html/ws- routing.asp ). ■ Simple Object Access Protocol (SOAP) 1.1 (http://www.w3.org/TR ). ■ Axis (http://xml.apache.org/axis ) is the SOAP implementation used in WebObjects. ■ Web Services Security Core Specification at http://www.oasis-open.org/committees/wss . ■ Canonical XML Version 1.0 (http://www.w3.org/TR ). ■ Exclusive XML Canonicalization Version 1.0 (http://www.w3.org/TR ). ■ Web Services Description Language (1.1) (http://www.w3.org/TR/wsdl ). In this document, SOAP (Simple Object Access Protocol) refers to SOAP version 1.1 of the specification. 8 See Also Legacy Document | 2007-07-11 | © 2002, 2007 Apple Inc. All Rights Reserved. CHAPTER 1 Web Services Overview You can think of Web services as distributed applications. Instead of creating an instance of a class and invoking its methods, a Web service consumer locates a Web service and invokes the operations it provides. The Web service provider (the application implementing the Web service) can be on the same Java virtual machine as the one using it, or it can be thousands of miles away.