XML Serialization
Total Page:16
File Type:pdf, Size:1020Kb
XML Serialization Preliminary February 1, 2003 Times is a trademark of Heidelberger Apple Computer, Inc. Druckmaschinen AG, available from © 2004 Apple Computer, Inc. Linotype Library GmbH. All rights reserved. Simultaneously published in the United States and Canada. No part of this publication may be Even though Apple has reviewed this manual, reproduced, stored in a retrieval system, or APPLE MAKES NO WARRANTY OR transmitted, in any form or by any means, REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, mechanical, electronic, photocopying, ITS QUALITY, ACCURACY, recording, or otherwise, without prior MERCHANTABILITY, OR FITNESS FOR A written permission of Apple Computer, Inc., PARTICULAR PURPOSE. AS A RESULT, THIS MANUAL IS SOLD ªAS IS,º AND YOU, THE with the following exceptions: Any person PURCHASER, ARE ASSUMING THE ENTIRE is hereby authorized to store documentation RISK AS TO ITS QUALITY AND ACCURACY. on a single computer for personal use only IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, and to print copies of documentation for OR CONSEQUENTIAL DAMAGES personal use provided that the RESULTING FROM ANY DEFECT OR documentation contains Apple’s copyright INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages. notice. THE WARRANTY AND REMEDIES SET The Apple logo is a trademark of Apple FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, Computer, Inc. EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any Use of the “keyboard” Apple logo modification, extension, or addition to this (Option-Shift-K) for commercial purposes warranty. without the prior written consent of Apple Some states do not allow the exclusion or may constitute trademark infringement and limitation of implied warranties or liability for incidental or consequential damages, so the unfair competition in violation of federal above limitation or exclusion may not apply to and state laws. you. This warranty gives you specific legal rights, and you may also have other rights which No licenses, express or implied, are granted vary from state to state. 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 or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Mac, Mac OS, and WebObjects are trademarks of Apple Computer, Inc., registered in the United States and other countries. Java and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. SPEC is a trademark of the Standard Performance Evaluation Corporation (SPEC). Contents Chapter 1 About This Document 9 What You Should Already Know 9 Contents 9 Related Documentation 10 Additional Resources 11 Chapter 2 Introduction to XML Serialization 13 XML Documents 13 XML Namespaces 16 Benefits of XML Serialization 18 Transforming XML Documents 18 Chapter 3 XML Serialization Essentials 19 Serialization Process 20 Deserialization Process 21 Secure Serialization 22 Validation of Deserialized Data 24 Multiple Class Version Support 25 Serialization With Keys 27 Application Security 27 Chapter 4 Serializing Objects and Data 29 Binary Serialization Example 29 Creating the Serialization Project 29 Adding the BinarySerializer Class 30 Serializing an NSArray of Strings 30 Serializing Primitive-Type Values 33 Serializing Custom Objects 35 XML Serialization Example 41 Adding the XMLSerializer Class 41 Serializing an NSArray of Strings to an XML Document 41 Serializing Primitive-Type Values to an XML Document 43 Serializing With Keys 46 Serializing Custom Objects to an XML Document 47 3 Preliminary © 2004 Apple Computer, Inc. All Rights Reserved. CONTENTS Formatting Serialized Output 49 Chapter 5 XML Transformation 51 Structure of Serialized Data in WebObjects 51 XSL Transformations 52 XML Parsers and XSLT Processors 54 Serialization and Transformation Performance 55 Chapter 6 Transforming XML Documents 57 The Transformation Process 57 Creating the Transformation Project 60 Transforming Primitive-Type Values Using Keys 61 Transforming an Array of Movies 62 Appendix A XML Schema and DTD Files 65 XML Schema File 65 DTD Document File 75 Appendix B Code Listings 85 BinarySerialization.java 85 XMLSerializer.java 89 SimpleTransformation.xsl 95 Document Revision History 99 Glossary 101 Index 103 4 Preliminary © 2004 Apple Computer, Inc. All Rights Reserved. Tables, Figures, and Listings Chapter 2 Introduction to XML Serialization 13 Figure 2-1 Graphical representation of the service-request document 15 Listing 2-1 Service-request document 13 Listing 2-2 Service-response document 16 Listing 2-3 Service-response document using namespaces 17 Listing 2-4 Service-response document using a default namespace for the provider entity 17 Chapter 3 XML Serialization Essentials 19 Listing 3-1 Example of a serialization method 20 Listing 3-2 Example of a deserialization method 21 Listing 3-3 Example of a secure class 22 Listing 3-4 Example of a class that disallows serialization and deserialization by throwing NotSerializableException 23 Listing 3-5 Example of a class that validates deserialized data 24 Listing 3-6 Security-manager policies required for XML serialization in WebObjects for Mac OS X 27 Listing 3-7 Security-manager policies required for XML serialization in WebObjects for Windows 28 Table 3-1 Compatible and incompatible changes for new class versions 26 Chapter 4 Serializing Objects and Data 29 Figure 4-1 Project Builder's Run pane when running the array-serialization example 32 Figure 4-2 BinaryTitles_data.binary file viewed through a text editor 32 Figure 4-3 Project Builder's Run pane when running the primitive-values serialization example 35 Figure 4-4 Project Builder's Run pane when running the Movie-object serialization example 39 Figure 4-5 Project Builder's Run pane when running the Movie-array serialization example 41 Figure 4-6 The element hierarchy of the BoolTitles_data.xml document 43 Listing 4-1 The serializeArray, deserializeArray, and arraySerialization methods in Application.java 31 Listing 4-2 The constructor in Application.java 31 Listing 4-3 The serializePrimitives, deserializePrimitives, and primitiveSerialization methods in Application.java 33 5 Preliminary © 2004 Apple Computer, Inc. All Rights Reserved. TABLES, FIGURES, AND LISTINGS Listing 4-4 Movie.java using binary serialization 35 Listing 4-5 The serializeMovie, deserializeMovie, and movieSerialization methods in Application.java 38 Listing 4-6 The serializeMovieArray, deserializeMovieArray, and movieArraySerialization methods of Application.java 39 Listing 4-7 The serializeArray and deserializeArray methods in Application.java using XML serialization 42 Listing 4-8 BookTitles_data.xml (serialized array of Strings) 42 Listing 4-9 The serializePrimitives, deserializePrimitives and primitiveSerialization methods in Application.java using XML serialization 44 Listing 4-10 The PrimitiveValues_data.xml file 45 Listing 4-11 The serializePrimitives method of Application.java using keys to identify elements in XML document 46 Listing 4-12 The PrimitiveValues_data.xml file with keys identifying each element 46 Listing 4-13 The writeObject method in Movie.java using XML serialization with keys 47 Listing 4-14 The Movies_data.xml file 48 Listing 4-15 Setting the indenting and encoding properties of an NSXMLOutputFormat object and applying them to an NSXMLOutputStream object 49 Table 4-1 Output-format properties accessible through NSXMLOutputFormat 49 Chapter 5 XML Transformation 51 Figure 5-1 Diagram of the schema for WebObjects XML serialization 52 Listing 5-1 Example of a target document 52 Listing 5-2 Section of SimpleTransformation.xsl that processes woxml:object elements 53 Chapter 6 Transforming XML Documents 57 Listing 6-1 The transformObject method in XMLSerializer .java 57 Listing 6-2 The openStream method in XMLSerializer.java 58 Listing 6-3 The initializeTransformer method in XMLSerializer.java 59 Listing 6-4 The transformPrimitives method in the Application class 61 Listing 6-5 The source document: produced by NSXMLOutputStream before transformation 62 Listing 6-6 The target document: PrimitivesTransformed.xml 62 Listing 6-7 The transformMovieArray method in Application.java 63 Listing 6-8 The MoviesTransformed.xml file 63 Appendix A XML Schema and DTD Files 65 Listing A-1 The woxml.xsd file 65 Listing A-2 The woxml.dtd file 75 6 Preliminary © 2004 Apple Computer, Inc. All Rights Reserved. TABLES, FIGURES, AND LISTINGS Appendix B Code Listings 85 Listing B-1 BinarySerializer.java class 85 Listing B-2 XMLSerializer.java class 89 Listing B-3 SimpleTransformation.xsl file 95 7 Preliminary © 2004 Apple Computer, Inc. All Rights Reserved. TABLES, FIGURES, AND LISTINGS 8 Preliminary © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 About This Document This document explains how to you can use XML serialization in your applications. Binary serialization is a simple and efficient way of serializing data. To see this appealing format, invoke the cat command on an executable file. Binary is a wonderful format for computers to use, but it's not