Java and XML Data Binding

More Java developers today want to work with XML, the technology that enables data to be transported intact over the Internet, but they don't have time to become XML experts. If this describes you, then you'll appreciate data binding, the new way of converting XML documents into Java objects, so those documents can be worked on and manipulated like any other Java object, then converted back to XML This new title provides an in-depth technical look at XML Data Binding. The book offers complete documentation of all features in both the Sun Microsystems JAXB API and popular open source alternative implementations (Enhydra Zeus, Exolabs Castor and Quick). It also gets into significant detail about when data binding is appropriate to use, and provides numerous practical examples of using data binding in applications. As Author Brett McLaughlin says "Too many books are written about technologies by people who barely understand them. I've already written two data binding implementations (Zeus, and a previous one for IBM DeveloperWorks.) I've actually used data binding for longer than the official specification has been in existence, and I've really been able to dig into what it takes to code an effective data biding implementation, as well as use one correctly. This book is part user guide, part under-the-hood manual, and part use-case. It's a powerful combination, and one I think people need." This title provides an in-depth technical look at XML Data Binding, offering complete documentation of all features in both the Sun Microsystems API and popular open source alternative implementations. Table of Content 3 Organization 6 Conventions Used in This Book 8 Comments and Questions 8 Acknowledgments 9 1.1 Low-Level APIs 10 1.1.1 Streamed Data 12 1.1.2 Modeled Data 12 1.1.3 Abstracted Data 13 1.2 High-Level APIs 13 1.2.1 Mapped Data 15 1.2.2 Messaged Data 15 1.3 What Is Data Binding? 16 1.3.1 Class Generation 16 1.3.2 Unmarshalling 17 1.3.3 Marshalling 17 1.3.4 Binding Schemas 18 1.4 What You'll Need 18 1.4.1 Packages 18 1.4.2 Tools 19 Chapter 2. Theory and Concepts 21 2.1 Foundational APIs 21 2.1.1 SAX 21 Example 2-1. The EnhydraErrorHandler class 22 Example 2-2. Using an EntityResolver for Sun EJB DTDs 24 2.1.2 DOM 25 2.2 Dependent APIs 26 2.2.1 SOAP 26 2.2.2 UDDI 27 2.3 Constraint-Modeled Data 28 2.3.1 DTDs 28 Figure 2-1. Developing data before modeling constraints 30 Figure 2-2. Modeling constraints before data 30 2.3.2 XML Schema 30 2.3.3 And More ... 31 2.4 API Transparence 33 2.4.1 Independence 33 2.4.1.1 API independence 34 2.4.1.2 Version independence 34 2.4.2 Integration 35 2.4.3 Interoperation 35 Chapter 3. Generating Classes 37 3.1 Process Flow 37 3.1.1 Constraints 37 3.1.2 Binding Schema 38 3.1.3 Generation 39 3.1.4 Source Code 40 Figure 3-1. Class generation process flow 40 3.2 Creating the Constraints 40 3.2.1 JAXB and DTDs 41 Example 3-1. Movie database DTD 41 Example 3-2. Sample movie database 42 3.2.2 Deterministic Modeling 42 3.2.3 Simple Elements 43 3.2.4 Constraint Naming 45 3.3 Binding Schema Basics 46 3.3.1 The Minimum Binding Schema 46 Example 3-3. Binding schema for movie database 47 3.3.2 Global Options 47 Table?3-1. Global binding schema options 47 Example 3-4. Modified binding schema for movies database 48 3.4 Generating Java Source Files 50 3.4.1 Getting Set Up 50 Example 3-5. Batch file for class generation using JAXB 50 3.4.2 Supplying Output 51 Figure 3-2. Filesystem layout 52 3.4.3 Verifying Output 53 Chapter 4. Unmarshalling 55 4.1 Process Flow 55 4.1.1 XML Data 55 4.1.2 Java Conversion 56 4.1.3 Result Objects 57 Figure 4-1. Object instance tree for movie database 57 Figure 4-2. Unmarshalling process flow 58 4.2 Creating the XML 59 4.2.1 Authoring an Instance Document 59 Figure 4-3. Editing XML with XML Spy 59 4.2.2 Validation 61 Example 4-1. Sample movie database 61 Example 4-2. Simple validation program 62 4.3 Converting to Java 64 4.3.1 XML Input 64 4.3.2 Java Output 65 4.3.3 Intermediate Objects 67 Figure 4-4. The JAXB unmarshalling process in detail 68 4.4 Using the Results 68 4.4.1 Business Objects 68 Example 4-3. The MoviesServlet class 69 Figure 4-5. The MoviesServlet viewing the database 71 4.4.2 Data Objects 72 Example 4-4. The connection DTD 73 Example 4-5. The connection binding schema 73 Example 4-6. My connection data 74 Example 4-7. The MovieClient class 74 Chapter 5. Marshalling 79 5.1 Process Flow 79 5.1.1 Java Objects 79 5.1.2 XML Conversion 80 5.1.3 Resultant XML 81 Figure 5-1. The marshalling process flow 81 5.2 Validating Java Objects 81 5.2.1 Java Validation 82 Example 5-1. Errors from missing attributes 82 Figure 5-2. Validation exceptions in JAXB 84 Example 5-2. Illegal XML not caught by JAXB 85 5.2.2 Non-JAXB Objects 87 5.3 Converting to XML 88 5.3.1 Java Input 88 5.3.1.1 The server 88 Table?5-1. Allowed parameters for the MoviesServlet 89 5.3.1.2 The client 92 Example 5-3. The Arguments utility class 93 Example 5-4. The modified MovieClient class 94 5.3.2 XML Output 97 Example 5-5. Modified XML database 97 5.4 Process Loops 98 98 Figure 5-3. Process loops 98 Figure 5-4. Process loops in the movie database 98 5.4.1 Continuity 99 5.4.2 Equivalence 99 Chapter 6. Binding Schemas 101 6.1 The Basics 101 6.1.1 XML to Java 101 Figure 6-1. Class generation and class compilation 102 6.1.2 Intermediary Transformations 102 6.2 Structure and Global Options 103 6.2.1 Packaging 103 6.2.2 Collection Types 104 6.2.3 Properties 104 6.2.4 Marshalling and Unmarshalling 104 6.3 Elements and Attributes 105 6.3.1 Elements 105 6.3.2 Content Specification 107 6.3.2.1 Element references 108 6.3.2.2 Choices 110 6.3.2.3 Sequences 111 6.3.2.4 Rests 112 6.3.3 Attributes 113 6.4 And More... 114 6.4.1 Enumerations 114 6.4.2 Conversions 117 Example 6-1. The DateConversion class 119 6.4.3 Constructors 120 6.4.4 Interfaces 121 Example 6-2. The Person interface 121 Chapter 7. Zeus 124 7.1 Process Flow 124 7.1.1 Class Generation 124 Figure 7-1. The Zeus process flow for class generation 125 7.1.2 Marshalling and Unmarshalling 126 7.2 Installation and Setup 126 7.3 Class Generation 127 7.3.1 DTDs 127 Example 7-1. A partial DTD for web.xml descriptors 128 7.3.2 Future Constraint Models 131 7.4 Unmarshalling and Marshalling 131 7.4.1 Unmarshalling 131 Example 7-2. A sample descriptor 132 Example 7-3. The WebAppUnmarshaller class 134 Example 7-4. A simple unmarshalling example with Zeus 135 7.4.2 Marshalling 136 7.5 Additional Features 139 7.5.1 Self-Containment 139 7.5.2 Ant Taskdef 141 Chapter 8. Castor 143 8.1 Process Flow 143 143 Figure 8-1. Class generation in Castor 143 Figure 8-2. Marshalling and unmarshalling in Castor 144 8.2 Installation and Setup 144 8.3 Class Generation 145 8.3.1 DTDs 145 8.3.2 XML Schema 146 Example 8-1. HR database constraint model 146 Table?8-1. Castor SourceGenerator options 148 8.4 Unmarshalling and Marshalling 149 149 Example 8-2. HR instance document 149 8.4.1 Unmarshalling 150 Example 8-3. Unmarshalling with Castor 150 8.4.2 Marshalling 152 8.4.3 Mapping Files 155 Example 8-4. A Castor mapping file for the HR classes 155 Example 8-5. EmployeeLister with mapping code 157 Example 8-6. Converted HR XML document 160 8.5 Additional Features 161 8.5.1 Database and Directory Server Mappings 162 8.5.2 JDO 162 Chapter 9. Quick 166 9.1 Process Flow 166 9.1.1 Quick Versus JAXB 166 Example 9-1. A confusing purchase order 166 Figure 9-1. Classes for an XML document 167 Example 9-2. A more readable purchase order 168 Figure 9-2. Data conversion using Quick 169 9.1.2 Performance Considerations 169 9.2 Installation and Setup 170 9.3 Unmarshalling and Marshalling 170 9.3.1 Unmarshalling 171 9.3.1.1 Have Java classes on hand 171 9.3.1.2 Converting DTDs to QDML 171 Example 9-3. DTD for Example 9-1 171 Example 9-4. QDML for Example 9-1 172 9.3.1.3 Converting QDML to QJML 173 Example 9-5. QJML for use in unmarshalling 174 9.3.1.4 More conversion 175 9.3.1.5 Unmarshalling 176 Example 9-6. Unmarshalling using Quick 176 Figure 9-3. Quick unmarshalling 178 9.3.2 Marshalling 179 Example 9-7. Output from PurchaseOrderviewer 181 9.3.3 Format Conversion 181 Example 9-8. Converting XML formats using QJML 181 9.4 Additional Features 183 9.4.1 Class Generation 183 9.4.2 QDML to DTD 184 Chapter 10. Looking Forward 185 10.1 JAXB 185 10.1.1 Final Release 185 10.1.2 Schema Support 186 10.2 Alternate Implementations 186 10.2.1 JAXB Conformance 186 10.2.2 Overlaying Functionality 187 10.3 J2EE 188 10.3.1 Data Binding in Enterprise Applications 188 10.3.2 Related APIs 189 Table?10-1. The current JAX-pack 189 Appendix A. Tools Reference 191 A.1 JAXB 191 191 Table?A-1. JAXB xjc options 191 A.2 Zeus 191 191 Table?A-2. Zeus DTDSourceGenerator options 191 A.3 Castor 192 192 Table?A-3. Castor SourceGenerator options 192 A.4 Quick 193 A.4.1 cfgDtd2Qdml 193 Table?A-4. Quick cfgDtd2Qdml options 193 A.4.2 cfgQdml2Qjml 193 Table?A-5. Quick cfgQdml2Qjml options 193 A.4.3 cfgQjml2Java 194 Table?A-6. Quick cfgQjml2Java options 194 A.4.4 cfgQdml2Dtd 195 Table?A-7. Quick cfgQdml2Dtd options 195 Appendix B. Quick Source Files 196 196 196 Example B-1. The PurchaseOrder class 196 Example B-2. The order class 197 Example B-3. The stock class 198 Colophon 199 Table of Content......Page 3 Organization......Page 6 Comments and Questions......Page 8 Acknowledgments......Page 9 1.1 Low-Level APIs......Page 10 1.1.2 Modeled Data......Page 12 1.2 High-Level APIs......Page 13 1.2.2 Messaged Data......Page 15 1.3.1 Class Generation......Page 16 1.3.3 Marshalling......Page 17 1.4.1 Packages......Page 18 1.4.2 Tools......Page 19 2.1.1 SAX......Page 21 Example 2-1. The EnhydraErrorHandler class......Page 22 Example 2-2. Using an EntityResolver for Sun EJB DTDs......Page 24 2.1.2 DOM......Page 25 2.2.1 SOAP......Page 26 2.2.2 UDDI......Page 27 2.3.1 DTDs......Page 28 2.3.2 XML Schema......Page 30 2.3.3 And More .........Page 31 2.4.1 Independence......Page 33 2.4.1.2 Version independence......Page 34 2.4.3 Interoperation......Page 35 3.1.1 Constraints......Page 37 3.1.2 Binding Schema......Page 38 3.1.3 Generation......Page 39 3.2 Creating the Constraints......Page 40 Example 3-1. Movie database DTD......Page 41 3.2.2 Deterministic Modeling......Page 42 3.2.3 Simple Elements......Page 43 3.2.4 Constraint Naming......Page 45 3.3.1 The Minimum Binding Schema......Page 46 Table?3-1. Global binding schema options......Page 47 Example 3-4. Modified binding schema for movies database......Page 48 Example 3-5. Batch file for class generation using JAXB......Page 50 3.4.2 Supplying Output......Page 51 Figure 3-2. Filesystem layout......Page 52 3.4.3 Verifying Output......Page 53 4.1.1 XML Data......Page 55 4.1.2 Java Conversion......Page 56 Figure 4-1. Object instance tree for movie database......Page 57 Figure 4-2. Unmarshalling process flow......Page 58 Figure 4-3. Editing XML with XML Spy......Page 59 Example 4-1. Sample movie database......Page 61 Example 4-2. Simple validation program......Page 62 4.3.1 XML Input......Page 64 4.3.2 Java Output......Page 65 4.3.3 Intermediate Objects......Page 67 4.4.1 Business Objects......Page 68 Example 4-3. The MoviesServlet class......Page 69 Figure 4-5. The MoviesServlet viewing the database......Page 71 4.4.2 Data Objects......Page 72 Example 4-5. The connection binding schema......Page 73 Example 4-7. The MovieClient class......Page 74 5.1.1 Java Objects......Page 79 5.1.2 XML Conversion......Page 80 5.2 Validating Java Objects......Page 81 Example 5-1. Errors from missing attributes......Page 82 Figure 5-2. Validation exceptions in JAXB......Page 84 Example 5-2. Illegal XML not caught by JAXB......Page 85 5.2.2 Non-JAXB Objects......Page 87 5.3.1.1 The server......Page 88 Table?5-1. Allowed parameters for the MoviesServlet......Page 89 5.3.1.2 The client......Page 92 Example 5-3. The Arguments utility class......Page 93 Example 5-4. The modified MovieClient class......Page 94 Example 5-5. Modified XML database......Page 97 Figure 5-4. Process loops in the movie database......Page 98 5.4.2 Equivalence......Page 99 6.1.1 XML to Java......Page 101 6.1.2 Intermediary Transformations......Page 102 6.2.1 Packaging......Page 103 6.2.4 Marshalling and Unmarshalling......Page 104 6.3.1 Elements......Page 105 6.3.2 Content Specification......Page 107 6.3.2.1 Element references......Page 108 6.3.2.2 Choices......Page 110 6.3.2.3 Sequences......Page 111 6.3.2.4 Rests......Page 112 6.3.3 Attributes......Page 113 6.4.1 Enumerations......Page 114 6.4.2 Conversions......Page 117 Example 6-1. The DateConversion class......Page 119 6.4.3 Constructors......Page 120 Example 6-2. The Person interface......Page 121 7.1.1 Class Generation......Page 124 Figure 7-1. The Zeus process flow for class generation......Page 125 7.2 Installation and Setup......Page 126 7.3.1 DTDs......Page 127 Example 7-1. A partial DTD for web.xml descriptors......Page 128 7.4.1 Unmarshalling......Page 131 Example 7-2. A sample descriptor......Page 132 Example 7-3. The WebAppUnmarshaller class......Page 134 Example 7-4. A simple unmarshalling example with Zeus......Page 135 7.4.2 Marshalling......Page 136 7.5.1 Self-Containment......Page 139 7.5.2 Ant Taskdef......Page 141 Figure 8-1. Class generation in Castor......Page 143 8.2 Installation and Setup......Page 144 8.3.1 DTDs......Page 145 Example 8-1. HR database constraint model......Page 146 Table?8-1. Castor SourceGenerator options......Page 148 Example 8-2. HR instance document......Page 149 Example 8-3. Unmarshalling with Castor......Page 150 8.4.2 Marshalling......Page 152 Example 8-4. A Castor mapping file for the HR classes......Page 155 Example 8-5. EmployeeLister with mapping code......Page 157 Example 8-6. Converted HR XML document......Page 160 8.5 Additional Features......Page 161 8.5.2 JDO......Page 162 Example 9-1. A confusing purchase order......Page 166 Figure 9-1. Classes for an XML document......Page 167 Example 9-2. A more readable purchase order......Page 168 9.1.2 Performance Considerations......Page 169 9.3 Unmarshalling and Marshalling......Page 170 Example 9-3. DTD for Example 9-1......Page 171 Example 9-4. QDML for Example 9-1......Page 172 9.3.1.3 Converting QDML to QJML......Page 173 Example 9-5. QJML for use in unmarshalling......Page 174 9.3.1.4 More conversion......Page 175 Example 9-6. Unmarshalling using Quick......Page 176 Figure 9-3. Quick unmarshalling......Page 178 9.3.2 Marshalling......Page 179 Example 9-8. Converting XML formats using QJML......Page 181 9.4.1 Class Generation......Page 183 9.4.2 QDML to DTD......Page 184 10.1.1 Final Release......Page 185 10.2.1 JAXB Conformance......Page 186 10.2.2 Overlaying Functionality......Page 187 10.3.1 Data Binding in Enterprise Applications......Page 188 Table?10-1. The current JAX-pack......Page 189 Table?A-2. Zeus DTDSourceGenerator options......Page 191 Table?A-3. Castor SourceGenerator options......Page 192 Table?A-5. Quick cfgQdml2Qjml options......Page 193 Table?A-6. Quick cfgQjml2Java options......Page 194 Table?A-7. Quick cfgQdml2Dtd options......Page 195 Example B-1. The PurchaseOrder class......Page 196 Example B-2. The order class......Page 197 Example B-3. The stock class......Page 198 Colophon......Page 199 Java and XML Data Binding shows you how to put the new XML data binding APIs to work. XML is an excellent tool for representing data. Ultimately, though, it's not enough to represent data; we also need to work with it, and working directly with XML documents is awkward. You have to navigate through the document, working with XML constructs such as elements and attributes. Programming at this level is awakward and alien to many software developers. The XML data binding tools discussed in this book allow you to jump directly from an XML document to Java objects and back again. Once you're in Java, you can work with your objects simply and intuitively in business-specific ways. Instead of finding and modifying the name attribute of an employee element, you can just call employee.setName(). Generating XML output is as simple as writing a file. With data binding, you can finally work in Java, rather than in XML.This new book explains what data binding is, and then covers all the popular data binding toolkits: Sun's JAXB API, as well as three open source alternatives -- Zeus, Castor, and Quick. Along the way, the book gives you lots of practical information about how to use data binding effectively: what pitfalls to avoid, where to bend the rules, and how to make the various packages do what you want them to do. XML is becoming a larger part of application development every day, and thousands of developers are struggling to understand the various XML constructs and Java APIs that manipulate them. However, instead of having to learn an entirely new way of thinking, using data binding provides you with XML data in a Java format; data-centric information in a business-centric manner; and difficult semantics in well-understood, Java-based terms. Moving between XML and Java (and back again) becomes trivial, and you'll soon forget that you are even dealing with XML data. If you want to use XML productively without spending months trying to grasp entity references and ignorable whitespace, then Java and XML Data Binding is the book for you.