Pro EJB 3: Java Persistence API (Expert's Voice in Java)

Enterprise JavaBeans 3.0 (EJB 3.0) is a vital component of the new Java Enterprise Edition 5 platform (previously called J2EE). They are used for the development and deployment of component-based enterprise business applications. Ever since its first release, EJB has been the subject of much media attention and no little controversy. EJBs represent a sophisticated and powerful technology and EJB-based applications can support high numbers of transactions and users, with maximum security. However, previous incarnations of EJB have come to be regarded by many as an overly complex technology that can lead to costly and time-consuming solutions that are difficult to build, implement and maintain. EJB 3 is set to change all that. It has made huge advances in ease of development, and its drastically simplified programming model has been widely acclaimed and embraced. At the heart of the new EJB 3 spec is a massive reduction in the complexity of the EJB persistence and object-relational mapping mechanisms (essentially the entity beans portion of the specification). This book provides the definitive guide to the EJB 3 persistence technology. The lead author, Mike Keith, is a co-lead on the EJB 3.0 expert group (under JSR 220) and provides unparalleled insight and expertise on this topic. He and his co-authors dissect and explain the new EJB 3 persistence specification in full detail, describing how to use this sophisticated technology to its full potential. Assuming a basic knowledge of Java, SQL, JDBC and some J2EE experience, this book teaches you EJB 3 persistence from the ground up. It provides the reader with a complete and in-depth understanding of the EJB 3.0 Persistence API and how to use it in practice. Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv About the Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii About the Technical Reviewers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii ■CHAPTER 1 Introduction ................................................1 Java Support for Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Enterprise JavaBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Java Data Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Why Another Standard? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Object-Relational Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 The Impedance Mismatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 The Java Persistence API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 History of the Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Creating an Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Automatic State Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 vii ■C O N T E N T S viii Entity Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Obtaining an Entity Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Persisting an Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Finding an Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Removing an Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Updating an Entity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Putting It All Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Packaging It Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Persistence Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Persistence Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 ■CHAPTER 3 Enterprise Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Application Component Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Session Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Stateless Session Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Stateful Session Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Message-Driven Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Defining a Message-Driven Bean . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Dependency Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Dependency Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Dependency Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Declaring Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Transaction Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Enterprise Transactions in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Using Java EE Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Using a Stateless Session Bean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Using a Stateful Session Bean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Using a Message-Driven Bean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Adding the Entity Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Putting It All Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Defining the Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Defining the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Packaging It Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 ■C O N T E N T S ix ■CHAPTER 4 Object-Relational Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Persistence Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Accessing Entity State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Field Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Property Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Mapping to a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Mapping Simple Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Column Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Lazy Fetching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Enumerated Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Temporal Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Transient State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Mapping the Primary Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Identifier Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Relationship Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Mappings Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Single-Valued Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Collection-Valued Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Lazy Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 ■CHAPTER 5 Entity Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Persistence Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Entity Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Container-Managed Entity Managers . . . . . . . . . . . . . . . . . . . . . . . . 112 Application-Managed Entity Managers . . . . . . . . . . . . . . . . . . . . . . 117 Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 JTA Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Resource-Local Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Transaction Rollback and Entity State . . . . . . . . . . . . . . . . . . . . . . . 131 Choosing an Entity Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Entity Manager Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Persisting an Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Finding an Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Removing an Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Cascading Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Clearing the Persistence Context . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 ■C O N T E N T S x Synchronization with the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Detachment and Merging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Detachment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Merging Detached Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Working with Detached Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 ■CHAPTER 6 Using Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Java Persistence QL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Filtering Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Projecting Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Joins Between Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Aggregate Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Query Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Defining Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Dynamic Query Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Named Query Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Parameter Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Executing Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Working with Query Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 Query Paging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Queries and Uncommitted Changes . . . . . . . . . . . . . . . . . . . . . . . . . 180 Bulk Update and Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Using Bulk Update and Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Bulk Delete and Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Query Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Query Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Named Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Report Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Query Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Stateless Session Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Bulk Update and Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Provider Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 ■C O N T E N T S xi ■CHAPTER 7 Query Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Example Data Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Select Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 The SELECT Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 The FROM Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 The WHERE Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 The ORDER BY Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Aggregate Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Aggregate Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 The GROUP BY Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 The HAVING Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 Update Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Delete Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 ■CHAPTER 8 Advanced Object-Relational Mapping . . . . . . . . . . . . . . . . . . . 221 Embedded Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Sharing Embedded Object Classes . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Compound Primary Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 Id Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Embedded Id Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Advanced Mapping Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Read-Only Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Optionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 Advanced Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Compound Join Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Identifiers That Include a Relationship . . . . . . . . . . . . . . . . . . . . . . . 233 Mapping Relationship State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Multiple Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Class Hierarchies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Inheritance Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Mixed Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 ■C O N T E N T S xii ■CHAPTER 9 Advanced Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 SQL Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 Native Queries vs. JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 Defining and Executing SQL Queries . . . . . . . . . . . . . . . . . . . . . . . . 260 SQL Result Set Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Parameter Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 Lifecycle Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 Lifecycle Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 Callback Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 Entity Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 Inheritance and Lifecycle Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 Concurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Entity Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Entity Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Refreshing Entity State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 Optimistic Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 Additional Locking Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Recovering from Optimistic Failures . . . . . . . . . . . . . . . . . . . . . . . . . 290 Schema Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Unique Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Null Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 String-Based Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 Floating Point Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 Defining the Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 ■CHAPTER 10 XML Mapping Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 The Metadata Puzzle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 The Mapping File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 Disabling Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 Persistence Unit Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 Mapping File Defaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 Queries and Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 Managed Classes and Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 ■C O N T E N T S xiii ■CHAPTER 11 Packaging and Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Configuring Persistence Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Persistence Unit Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Transaction Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Persistence Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 Mapping Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 Managed Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 Adding Vendor Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 Building and Deploying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 Deployment Classpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 Packaging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 Persistence Unit Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 Outside the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 Configuring the Persistence Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 Specifying Properties at Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 System Classpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 ■CHAPTER 12 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Testing Enterprise Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 Testing Outside the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 Test Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 Unit Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 Testing Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 Testing Entities in Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 The Entity Manager in Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Integration Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 Using the Entity Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 Components and Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 ■C O N T E N T S xiv ■CHAPTER 13 Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 Migrating from CMP Entity Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 Scoping the Challenge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 Entity Bean Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 Migrating from JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 Migrating from Other ORM Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 Leveraging Design Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 Transfer Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 Session Façade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 Data Access Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 Business Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 Fast Lane Reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 Active Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 ■APPENDIX Quick Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 Metadata Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 Enumerated Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 Mapping File-Level Metadata Reference . . . . . . . . . . . . . . . . . . . . . . . . . 426 Persistence-Unit-Level Metadata Reference . . . . . . . . . . . . . . . . . . . . . . 427 EntityManager Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 Query Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 EntityManagerFactory Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 EntityTransaction Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 ■INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

EJB 3.0 sets a new precedent. It has made huge advances in ease of development, and its drastically simplified programming model has been widely acclaimed.

Mike Keith, EJB 3.0 co-specification lead, and Merrick Schinariol, reviewer of EJB 3.0, offer unparalleled insight and expertise on the new EJB 3.0 persistence specification, in this definitive guide to EJB 3.0 persistence technology. Expect full coverage and examination of the EJB 3.0 spec from these expert authors, including:

• The new EntityManager API


• The new features of EJB Query Language (EJB QL)


• Basic and advanced object-relational mapping


• Advanced topics like concurrency, locking, inheritance, and polymorphism

Assuming a basic knowledge of Java, SQL, JDBC, and some J2EE experience, Mike Keith and Merrick Schinariol will teach you EJB 3 persistence from the ground up. After reading it, you will have an in-depth understanding of the EJB 3.0 Persistence API and how to use it in your applications.

"Pro EJB 3.0 Persistence" deals with computers/software. EJB 3.0 sets a new precedent. It has made huge advances in ease of development, and its drastically simplified programming model has been widely acclaimed. This book is the definitive guide to EJB 3.0 persistence technology. The authors provide unparalleled insight and expertise on this topic, fully examining and explaining EJB 3.0 persistence specification. They describe how to use this sophisticated technology to its full potential, including The new EntityManager API The new features of EJB Query Language (EJB QL) Basic and advanced object-relational mapping Advanced topics like concurrency, locking, inheritance, and polymorphism Assuming a basic knowledge of Java, SQL, JDBC, and some J2EE experience, this book teaches you EJB 3 persistence from the ground up. After reading it, you will have an in-depth understanding of the EJB 3.0 Persistence API and how to use it in your applications EJB 3.0 sets a precedent. It has made huge advances in ease of development, and its drastically simplified programming model has been widely acclaimed. Mike Keith, EJB 3.0 co-specification lead, and Merrick Schinariol, reviewer of EJB 3.0, offer unparalleled insight and expertise on the EJB 3.0 persistence specification, in this definitive guide to EJB 3.0 persistence technology. Expect full coverage and examination of the EJB 3.0 spec from these expert authors, including: The EntityManager API The new features of EJB Query Language (EJB QL) Basic and advanced object-relational mapping Advanced topics like concurrency, locking, inheritance, and polymorphism Assuming a basic knowledge of Java, SQL, JDBC, and some J2EE experience, Keith and Schinariol will teach you EJB 3.0 persistence from the ground up. After reading it, you will have an in-depth understanding of the EJB 3.0 persistence API and how to use it in your applications. Pro EJB 3: Java Persistence API......Page 1 Contents......Page 8 CHAPTER 1 Introduction......Page 28 CHAPTER 2 Getting Started......Page 44 CHAPTER 3 Enterprise Applications......Page 62 CHAPTER 4 Object-Relational Mapping......Page 98 CHAPTER 5 Entity Manager......Page 138 CHAPTER 6 Using Queries......Page 190 CHAPTER 7 Query Language......Page 218 CHAPTER 8 Advanced Object-Relational Mapping......Page 248 CHAPTER 9 Advanced Topics......Page 284 CHAPTER 10 XML Mapping Files......Page 326 CHAPTER 11 Packaging and Deployment......Page 362 CHAPTER 12 Testing......Page 380 CHAPTER 13 Migration......Page 412 APPENDIX Quick Reference......Page 438 INDEX......Page 460 First EJB 3.0 book on the market and a definitive guide to the major innovation in EJB: the new persistence API Offers unparalleled insight and expertise: lead authored by the co-lead on the EJB 3.0 spec (Mike Keith)