Keith Schincariol JPA 2 Companion eBook Av ailable Pro Java™ EE 6 compliant this print for content only—size & color not accurate   CYAN   MAGENTA   YELLOW   BLACK   PANTONE 123 C BOOKS FOR PROFESSIONALS BY PROFESSIONALS ® Pro JPA 2: Mastering the Java ™ Persistence API Dear R eader, It’s hard to believe that over 3 years have gone by since the initial 1.0 release of the Java™ Persistence API. In that time we have seen it go from fledgling API to mainstream persistence standard. Along the way, many of you cut your JPA teeth using the first edition of this book, and we’re happy we were there to help! JPA 2.0 includes a host of new features, such as additional object-relational mappings, more object modeling flexibility, typed queries, and a brand-new criteria API, to name a few. With so much to talk about, we were excited to update the book and explain all the new features, but we also included some hints and tips to help you use the API in practice. If you already have experience with JPA 1.0 then you should benefit from the version tips that point out when a feature was added in 2.0. These tips were also designed to help users who are writing to a JPA 1.0 implementation, and are not yet able to make use of the 2.0 features. Those of you that are new to JPA can rest assured that you were not for- gotten. We have remained true to our original intent to take someone from having no JPA knowledge all the way to being an advanced JPA’er. You should be able to quickly learn in the first two chapters what you need to know to get started. (Veteran JPA programmers might want to start at Chapter 3!) Finally, we want to thank you for making the previous edition of this book such a suc- cess. We are pleased that it has become the primary resource for JPA develop- ers, and hope that you will find this edition equally valuable. Mike Keith, JPA 2.0 Expert Group Member, and Merrick Schincariol Authors of Pro EJB™ 3: Ja va™ Persistence API US $49.99 Shelve in Java Programming User level: Intermediate www.apr ess.com SOURCE CODE ONLINE Companion eBook See last page for details on $10 eBook version ISBN 978-1-4302-1956-9 9 78 1430 219569 5 49 9 9 RELATED TITLES Pro JPA 2 Mastering the Ja v a ™ Persistence API Mike Keith and Merrick Schincariol Foreword by Linda DeMichiel, JPA Specification Lead Create robust, data-driven applications with this definitive guide to the new JPA 2 Java ™ EE 6 compliant THE EXPERT’ S  VOICE ®  IN JAV A ™  TECHNOLOGY Tr im: 7.5 x 9.25 spine = 1.0" 536 page count www.traintelco.com Keith Schincariol JPA 2 Companion eBook Av ailable Pro Java™ EE 6 compliant this print for content only—size & color not accurate   CYAN   MAGENTA   YELLOW   BLACK   PANTONE 123 C BOOKS FOR PROFESSIONALS BY PROFESSIONALS ® Pro JPA 2: Mastering the Java ™ Persistence API Dear R eader, It’s hard to believe that over 3 years have gone by since the initial 1.0 release of the Java™ Persistence API. In that time we have seen it go from fledgling API to mainstream persistence standard. Along the way, many of you cut your JPA teeth using the first edition of this book, and we’re happy we were there to help! JPA 2.0 includes a host of new features, such as additional object-relational mappings, more object modeling flexibility, typed queries, and a brand-new criteria API, to name a few. With so much to talk about, we were excited to update the book and explain all the new features, but we also included some hints and tips to help you use the API in practice. If you already have experience with JPA 1.0 then you should benefit from the version tips that point out when a feature was added in 2.0. These tips were also designed to help users who are writing to a JPA 1.0 implementation, and are not yet able to make use of the 2.0 features. Those of you that are new to JPA can rest assured that you were not for- gotten. We have remained true to our original intent to take someone from having no JPA knowledge all the way to being an advanced JPA’er. You should be able to quickly learn in the first two chapters what you need to know to get started. (Veteran JPA programmers might want to start at Chapter 3!) Finally, we want to thank you for making the previous edition of this book such a suc- cess. We are pleased that it has become the primary resource for JPA develop- ers, and hope that you will find this edition equally valuable. Mike Keith, JPA 2.0 Expert Group Member, and Merrick Schincariol Authors of Pro EJB™ 3: Ja va™ Persistence API US $49.99 Shelve in Java Programming User level: Intermediate www.apr ess.com SOURCE CODE ONLINE Companion eBook See last page for details on $10 eBook version ISBN 978-1-4302-1956-9 9 78 1430 219569 5 49 9 9 RELATED TITLES Pro JPA 2 Mastering the Ja v a ™ Persistence API Mike Keith and Merrick Schincariol Foreword by Linda DeMichiel, JPA Specification Lead Create robust, data-driven applications with this definitive guide to the new JPA 2 Java ™ EE 6 compliant THE EXPERT’ S  VOICE ®  IN JAV A ™  TECHNOLOGY Tr im: 7.5 x 9.25 spine = 1.0" 536 page count www.traintelco.com i Pro JPA 2 Mastering the Java™ Persistence API ■ ■ ■ Mike Keith and Merrick Schnicariol www.traintelco.com ii Pro JPA 2 Copyright © 2009 by Mike Keith and Merrick Schincariol All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage or retrieval system, without the prior written permission of the copyright owner and the publisher. ISBN-13 (pbk): 978-1-4302-1956-9 ISBN-13 (electronic): 978-1-4302-1957-6 Printed and bound in the United States of America 9 8 7 6 5 4 3 2 1 Trademarked names may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark. President and Publisher: Paul Manning Lead Editor: Steve Anglin, Tom Welsh Technical Reviewer: Jim Farley Editorial Board: Clay Andres, Steve Anglin, Mark Beckner, Ewan Buckingham, Tony Campbell, Gary Cornell, Jonathan Gennick, Michelle Lowman, Matthew Moodie, Jeffrey Pepper, Frank Pohlmann, Ben Renow-Clarke, Dominic Shakeshaft, Matt Wade, Tom Welsh Coordinating Editor: Mary Tobin Copy Editor: Nancy Sixsmith Compositor: MacPS, LLC Indexer: BIM Indexers and e-Services Artist: April Milne Cover Designer: Anna Ishchenko Distributed to the book trade worldwide by Springer-Verlag New York, Inc., 233 Spring Street, 6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax 201-348-4505, e-mail orders-ny@springer- sbm.com, or visit http://www.springeronline.com. For information on translations, please e-mail info@apress.com, or visit http://www.apress.com. Apress and friends of ED books may be purchased in bulk for academic, corporate, or promotional use. eBook versions and licenses are also available for most titles. For more information, reference our Special Bulk Sales–eBook Licensing web page at http://www.apress.com/info/bulksales. The information in this book is distributed on an “as is” basis, without warranty. Although every precaution has been taken in the preparation of this work, neither the author(s) nor Apress shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the information contained in this work. The source code for this book is available to readers at http://www.apress.com. You will need to answer questions pertaining to this book in order to successfully download the code. www.traintelco.com iii To the memory of my father, who selflessly offered all that he had, and to my wife Darleen who has devoted her life to helping children.—Mike To Anthony, whose boundless creativity continues to inspire me. To Evan, whose boisterous enthusiasm motivates me to take on new challenges. To Kate, who proves that size is no object when you have the right attitude. I love you all.—Merrick www.traintelco.com iv Contents at a Glance ■ Contents at a Glance iv ■ Contents v ■ Foreword xx ■ About the Author xxi ■ About the Technical Reviewer xxii ■ Acknowledgments xxiii ■ Preface xiv ■ Chapter 1: Introduction 1 ■ Chapter 2: Getting Started 17 ■ Chapter 3: Enterprise Applications 33 ■ Chapter 4: Object-Relational Mapping 69 ■ Chapter 5: Collection Mapping 107 ■ Chapter 6: Entity Manager 131 ■ Chapter 7: Using Queries 179 ■ Chapter 8: Query Language 207 ■ Chapter 9: Criteria API 239 ■ Chapter 10: Advanced Object-Relational Mapping 273 ■ Chapter 11: Advanced Topics 315 ■ Chapter 12: XML Mapping Files 371 ■ Chapter 13: Packaging and Deployment 407 ■ Chapter 14: Testing 429 ■ Chapter 15: Migration 457 ■ Index 481 www.traintelco.com v Contents ■ Contents at a Glance iv ■ Contents v ■ Foreword xx ■ About the Author xxi ■ About the Technical Reviewer xxii ■ Acknowledgments xxiii ■ Preface xxiv ■ Chapter 1: Introduction 1 Object-Relational Mapping 2 The Impedance Mismatch 3 Class Representation 3 Relationships 5 Inheritance 7 Java Support for Persistence 9 Proprietary Solutions 9 JDBC 9 Enterprise JavaBeans 10 Java Data Objects 10 Why Another Standard? 11 The Java Persistence API 12 History of the Specification 12 EJB 3.0 and JPA 1.0 12 JPA 2.0 13 JPA and You 13 Overview 13 POJO Persistence 13 Nonintrusiveness 14 Object Queries 14 www.traintelco.com ■ CONTENTS vi Mobile Entities 14  Simple Configuration 15 Integration and Testability 15 Summary 15 ■ Chapter 2: Getting Started 17 Entity Overview 17 Persistability 17 Identity 18 Transactionality 18 Granularity 18 Entity Metadata 19 Annotations 19 XML 19 Configuration by Exception 19 Creating an Entity 20 Entity Manager 22 Obtaining an Entity Manager 23 Persisting an Entity 24 Finding an Entity 24 Removing an Entity 25 Updating an Entity 26 Transactions 26 Queries 27 Putting It All Together 28 Packaging It Up 30 Persistence Unit 30 Persistence Archive 31 Summary 32 ■ Chapter 3: Enterprise Applications 33 Application Component Models 33 Session Beans 34 Stateless Session Beans 35 Defining a Stateless Session Bean 35 Lifecycle Callbacks 37 Remote Business Interfaces 38 www.traintelco.com ■ CONTENTS vii Stateful Session Beans 39  Defining a Stateful Session Bean 39 Lifecycle Callbacks 40 Singleton Session Beans 42 Defining a Singleton Session Bean 42 Lifecycle Callbacks 43 Singleton Concurrency 43 Message-Driven Beans 45 Defining a Message-Driven Bean 45 Servlets 46 Dependency Management 47 Dependency Lookup 47 Dependency Injection 49 Field Injection 49 Setter Injection 50 Declaring Dependencies 51 Referencing a Persistence Context 51 Referencing a Persistence Unit 52 Referencing Enterprise JavaBeans 52 Referencing Server Resources 53 Transaction Management 53 Transaction Review 54 Enterprise Transactions in Java 54 Transaction Demarcation 55 Container-Managed Transactions 56 Bean-Managed Transactions 58 Using Java EE Components 60 Using a Stateless Session Bean 60 Using a Stateful Session Bean 60 Using a Singleton Session Bean 62 Using a Message-Driven Bean 62 Adding the Entity Manager 63 Putting It All Together 64 Defining the Component 64 Defining the User Interface 66 Packaging It Up 66 www.traintelco.com ■ CONTENTS viii Summary 67 ■ Chapter 4: Object-Relational Mapping 69 Persistence Annotations 69 Accessing Entity State 70 Field Access 70 Property Access 71 Mixed Access 71 Mapping to a Table 73 Mapping Simple Types 74 Column Mappings 75 Lazy Fetching 76 Large Objects 77 Enumerated Types 78 Temporal Types 80 Transient State 80 Mapping the Primary Key 81 Overriding the Primary Key Column 81 Primary Key Types 81 Identifier Generation 82 Automatic Id Generation 82 Id Generation Using a Table 83 Id Generation Using a Database Sequence 85 Id Generation Using Database Identity 86 Relationships 87 Relationship Concepts 87 Roles 87 Directionality 87 Cardinality 88 Ordinality 89 Mappings Overview 90 Single-Valued Associations 90 Many-to-One Mappings 90 Using Join Columns 91 One-to-One Mappings 93 Bidirectional One-to-One Mappings 94 Collection-Valued Associations 95 www.traintelco.com [...]... Form 22 3 xi www.traintelco.com ■ CONTENTS BETWEEN Expressions 22 4 LIKE Expressions 22 4 Subqueries 22 5 IN Expressions 22 6 Collection Expressions 22 7 EXISTS Expressions .22 8 ANY, ALL, and SOME Expressions 22 8 Scalar Expressions 22 8 Literals 22 9 Function Expressions... 26 5 The Metamodel API 26 5 Strongly Typed API Overview .26 7 The Canonical Metamodel 26 8 Using the Canonical Metamodel 26 9 Generating the Canonical Metamodel 27 0 Choosing the Right Type of Query 27 1 Summary 27 1 ■Chapter 10: Advanced Object-Relational Mapping 27 3 Table and Column Names 27 3... Specification Lead, Java Persistence 2. 0 Sun Microsystems Santa Clara, California xx www.traintelco.com ■ CONTENTS About the Author ■ Mike Keith was the co-specification lead for JPA 1.0 and an active member of the JPA 2. 0 expert group He sits on a number of other Java Community Process expert groups, including JSR 316, the Java EE 6 platform specification, and the Enterprise Expert Group (EEG) in the OSGi Alliance... 421 Data Source 421 Providers . 422 xvii www.traintelco.com ■ CONTENTS Listing the Entities 422 Specifying Properties at Runtime 423 System Classpath 423 Schema Generation 423 Unique Constraints 424 Null Constraints 425 String-Based Columns . 425 Floating Point... 23 7 Summary 23 8 ■Chapter 9: Criteria API 23 9 Overview 23 9 The Criteria API 24 0 Parameterized Types 24 1 Dynamic Queries 24 1 Building Criteria API Queries 24 4 Creating a Query Definition 24 4 Basic Structure 24 6 Criteria Objects and Mutability 24 6 Query... and column data into objects, or found themselves tied to proprietary frameworks that tried to hide the database from them Fortunately, a standard solution, the Java Persistence API (JPA) , was introduced into the platform to bridge the gap between object-oriented domain models and relational database systems In this book we will introduce the Java Persistence API and explore everything that it has... representation of the experience of the enterprise community The Impedance Mismatch Advocates of object-relational mapping often describe the difference between the object model and the relational model as the impedance mismatch between the two This is an apt description because the challenge of mapping one to the other lies not in the similarities between the two, but in the concepts in each for which there is... complete an API as many of the products and projects which provided its first implementations The task of JPA 2. 0 has been to solidify the standard, to expand its scope, and thus to provide developers with greater portability for both simple and sophisticated applications Like JPA 1.0, it has been driven by experience from technology already in the field and steered by the requests from members of the community... comprehensive guide to the Java Persistence API As authors, they bring a depth of experience in O/R mapping technology that is rarely equaled, as well as—in Mike’s case—years of experience in shaping JPA itself This book covers all aspects of the Java Persistence API It is both thorough and accessible, and both entertaining and exacting It not only introduces the reader to all aspects of the API and discusses... Clause 25 4 Building Expressions 25 4 Predicates .25 7 Literals 25 8 Parameters 25 8 Subqueries 25 8 In Expressions .26 1 Case Expressions 26 2 Function Expressions 26 4 The ORDER BY Clause 26 4 The GROUP BY and HAVING Clauses 26 5 Strongly Typed Query . Expressions 22 4  LIKE Expressions 22 4 Subqueries 22 5 IN Expressions 22 6 Collection Expressions 22 7 EXISTS Expressions 22 8 ANY, ALL, and SOME Expressions 22 8 Scalar Expressions 22 8 Literals 22 9 Function. Data Objects 10 Why Another Standard? 11 The Java Persistence API 12 History of the Specification 12 EJB 3.0 and JPA 1.0 12 JPA 2. 0 13 JPA and You 13 Overview 13 POJO Persistence 13 Nonintrusiveness. PANTONE  123  C BOOKS FOR PROFESSIONALS BY PROFESSIONALS ® Pro JPA 2: Mastering the Java ™ Persistence API Dear R eader, It’s hard to believe that over 3 years have gone by since the initial 1.0 release of the Java Persistence API.