Java Persistence Wikibooks.org March 18, 2013 On the 28th of April 2012 the contents of the English as well as German Wikibooks and Wikipedia projects were licensed under Creative Commons Attribution-ShareAlike 3.0 Unported license. An URI to this license is given in the list of figures on page 283. If this document is a derived work from the contents of one of these projects and the content was still licensed by the project under this license at the time of derivation this document has to be licensed under the same, a similar or a compatible license, as stated in section 4b of the license. The list of contributors is included in chapter Contributors on page 281. The licenses GPL, LGPL and GFDL are included in chapter Licenses on page 287, since this book and/or parts of it may or may not be licensed under one or more of these licenses, and thus require inclusion of these licenses. The licenses of the figures are given in the list of figures on page 283. This PDF was generated by the LATEX typesetting software. The LATEX source code is included as an attachment (source.7z.txt) in this PDF file. To extract the source from the PDF file, we recommend the use of http://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/ utility or clicking the paper clip attachment symbol on the lower left of your PDF Viewer, selecting Save Attachment. After extracting it from the PDF file you have to rename it to source.7z. To uncompress the resulting archive we recommend the use of http://www.7-zip.org/. The LATEX source itself was generated by a program written by Dirk Hünniger, which is freely available under an open source license from http://de.wikibooks.org/wiki/Benutzer:Dirk_Huenniger/wb2pdf. This distribution also contains a configured version of the pdflatex compiler with all necessary packages and fonts needed to compile the LATEX source included in this PDF file. Contents 1 Preface 3 2 What is Java persistence? 5 3 What is Java? 7 3.1 Google Trends . 7 3.2 See also . 7 4 What is a database? 9 5 What is JPA? 11 6 What is new in JPA 2.0? 13 7 Other Persistence Specs 15 8 Why use JPA or ORM? 17 9 Persistence Products 19 9.1 Existing Persistence Products . 19 10 EclipseLink 23 11 TopLink 25 12 Hibernate 27 13 TopLink Essentials 29 14 Kodo 31 15 Open JPA 33 16 Ebean 35 16.1 Index . 35 17 Mapping 37 18 Mapping 39 18.1 Access Type . 42 18.2 Common Problems . 43 19 Tables 45 III Contents 20 Advanced 47 20.1 Multiple tables . 47 20.2 Multiple tables with foreign keys . 49 20.3 Multiple table joins . 50 20.4 Multiple table outer joins . 51 20.5 Tables with special characters and mixed case . 52 20.6 Table qualifiers, schemas, or creators . 52 21 Identity 55 22 Sequencing 57 22.1 Sequence Strategies . 57 23 Advanced 65 23.1 Composite Primary Keys . 65 23.2 Primary Keys through OneToOne and ManyToOne Relationships . 69 23.3 Advanced Sequencing . 73 23.4 Primary Keys through Triggers . 74 23.5 Primary Keys through Events . 75 23.6 No Primary Key . 75 23.7 Single Table Inheritance . 77 23.8 Joined, Multiple Table Inheritance . 79 24 Advanced 83 24.1 Table Per Class Inheritance . 83 24.2 Mapped Superclasses . 84 25 Embeddables 89 26 Advanced 93 26.1 Sharing . 93 26.2 Embedded Ids . 94 26.3 Nulls . 94 26.4 Nesting . 95 26.5 Inheritance . 96 26.6 Relationships . 96 26.7 Collections . 97 26.8 Querying . 98 27 Locking 99 27.1 Optimistic Locking . 99 27.2 Advanced . 104 28 Basics 111 28.1 Common Problems . 113 29 Advanced 115 29.1 Temporal, Dates, Times, Timestamps and Calendars . 115 29.2 Enums . 117 IV Contents 29.3 LOBs, BLOBs, CLOBs and Serialization . 118 29.4 Lazy Fetching . 119 29.5 Optional . 119 29.6 Column Definition and Schema Generation . 120 29.7 Insertable, Updatable / Read Only Fields / Returning . 121 29.8 Conversion . 122 29.9 Custom Types . 122 30 Relationships 125 30.1 Lazy Fetching . 126 30.2 Cascading . 129 30.3 Orphan Removal (JPA 2.0) . 130 30.4 Target Entity . 131 30.5 Collections . 132 30.6 Common Problems . 135 31 Advanced 139 31.1 Advanced Relationships . 139 31.2 Maps . 140 31.3 Join Fetching . 145 31.4 Batch Fetching . 147 31.5 Filtering, Complex Joins . 148 31.6 Variable and Heterogeneous Relationships . 148 31.7 Nested Collections, Maps and Matrices . 149 32 OneToOne 151 32.1 Inverse Relationships, Target Foreign Keys and Mapped By . 154 32.2 See Also . 155 32.3 Common Problems . 155 33 Advanced 157 33.1 Target Foreign Keys, Primary Key Join Columns, Cascade Primary Keys 157 33.2 Mapping a OneToOne Using a Join Table . 161 34 ManyToOne 165 34.1 See Also . 167 34.2 Common Problems . 167 35 Advanced 169 35.1 Target Foreign Keys, Primary Key Join Columns, Cascade Primary Keys 169 36 OneToMany 171 36.1 Join Table . 174 36.2 See Also . 176 36.3 Common Problems . 176 37 Advanced 177 37.1 Undirectional OneToMany, No Inverse ManyToOne, No Join Table (JPA 2.0 ONLY) ................................... 177 V Contents 38 ManyToMany 179 38.1 Bi-directional Many to Many . 180 38.2 See Also . 181 38.3 Common Problems . 182 39 Advanced 183 39.1 Mapping a Join Table with Additional Columns . 183 40 ElementCollection 187 40.1 Embedded Collections . 188 40.2 Basic Collections . 189 40.3 See Also . 191 40.4 Common Problems . 191 41 Advanced Topics 193 41.1 Events . 193 41.2 Views . 196 41.3 Interfaces . 197 41.4 Stored Procedures . 198 41.5 Structured Object-Relational Data Types . 199 41.6 XML Data Types . 200 41.7 Filters . 201 41.8 History . 202 41.9 Logical Deletes . 203 41.10 Auditing . 203 41.11 Replication . 203 41.12 Partitioning . 204 41.13 Data Integration . 204 41.14 NoSQL (and EIS, legacy, XML, and non-relational data) . 204 41.15 Multi-Tenancy . 205 41.16 Dynamic Data . 205 42 Runtime 207 43 Entity Manager 209 43.1 Java Standard Edition . ..