manual - Apache OpenJPA - The Apache Software Foundation!

415 Pages·2012·4.19 MB·English

Apache OpenJPA 2.2 User's Guide
Apache OpenJPA 2.2 User's Guide
Built from OpenJPA version revision 1396819.
Publication date Last updated on October 10, 2012 at 6:40 PM.
Copyright © 2006-2012 The Apache Software Foundation
1. Introduction ..................................................................................................................................................... 1
1. About ..................................................................................................................................................... 3
2. Legal ...................................................................................................................................................... 4
2.1. License ........................................................................................................................................ 4
2.2. Notice .......................................................................................................................................... 4
2.3. Copyrights .................................................................................................................................... 4
2.3.1. Apache .............................................................................................................................. 4
2.3.2. Serp .................................................................................................................................. 4
2.3.3. Sun ................................................................................................................................... 4
2.3.4. Other ................................................................................................................................. 5
2. Java Persistence API ......................................................................................................................................... 6
1. Introduction ........................................................................................................................................... 11
1.1. Intended Audience ........................................................................................................................ 11
1.2. Lightweight Persistence ................................................................................................................. 11
2. Why JPA? ............................................................................................................................................. 12
3. Java Persistence API Architecture .............................................................................................................. 14
3.1. JPA Exceptions ............................................................................................................................ 15
4. Entity ................................................................................................................................................... 17
4.1. Restrictions on Persistent Classes .................................................................................................... 18
4.1.1. Default or No-Arg Constructor ............................................................................................. 18
4.1.2. Final ................................................................................................................................ 19
4.1.3. Identity Fields ................................................................................................................... 19
4.1.4. Version Field .................................................................................................................... 19
4.1.5. Inheritance ........................................................................................................................ 19
4.1.6. Persistent Fields ................................................................................................................ 20
4.1.7. Conclusions ...................................................................................................................... 21
4.2. Entity Identity .............................................................................................................................. 21
4.2.1. Identity Class .................................................................................................................... 22
4.2.1.1. Identity Hierarchies ................................................................................................. 23
4.3. Lifecycle Callbacks ...................................................................................................................... 24
4.3.1. Callback Methods .............................................................................................................. 24
4.3.2. Using Callback Methods ..................................................................................................... 25
4.3.3. Using Entity Listeners ........................................................................................................ 26
4.3.4. Entity Listeners Hierarchy ................................................................................................... 27
4.4. Conclusions ................................................................................................................................. 27
5. Metadata ............................................................................................................................................... 28
5.1. Class Metadata ............................................................................................................................ 29
5.1.1. Entity .............................................................................................................................. 29
5.1.2. Id Class ........................................................................................................................... 30
5.1.3. Mapped Superclass ............................................................................................................ 30
5.1.4. Embeddable ...................................................................................................................... 30
5.1.5. EntityListeners .................................................................................................................. 31
5.1.6. Example ........................................................................................................................... 31
5.2. Field and Property Metadata .......................................................................................................... 33
5.2.1. Explicit Access .................................................................................................................. 33
5.2.2. Transient .......................................................................................................................... 35
5.2.3. Id .................................................................................................................................... 35
5.2.4. Generated Value ................................................................................................................ 35
5.2.5. Embedded Id ..................................................................................................................... 36
5.2.6. Version ............................................................................................................................ 36
5.2.7. Basic ............................................................................................................................... 36
5.2.7.1. Fetch Type ............................................................................................................. 37
5.2.8. Embedded ........................................................................................................................ 37
5.2.9. Many To One ................................................................................................................... 37
iii
Apache OpenJPA 2.2 User's Guide
5.2.9.1. Cascade Type ......................................................................................................... 38
5.2.10. One To Many .................................................................................................................. 39
5.2.10.1. Bidirectional Relations ............................................................................................ 40
5.2.11. One To One .................................................................................................................... 40
5.2.12. Many To Many ................................................................................................................ 41
5.2.13. Order By ........................................................................................................................ 42
5.2.14. Map Key ........................................................................................................................ 42
5.2.15. Persistent Field Defaults .................................................................................................... 42
5.3. XML Schema .............................................................................................................................. 43
5.4. Conclusion .................................................................................................................................. 65
6. Persistence ............................................................................................................................................. 68
6.1. persistence.xml ............................................................................................................................ 68
6.2. Non-EE Use ................................................................................................................................ 74
7. EntityManagerFactory .............................................................................................................................. 75
7.1. Obtaining an EntityManagerFactory ................................................................................................. 75
7.2. Obtaining EntityManagers .............................................................................................................. 75
7.3. Persistence Context ....................................................................................................................... 76
7.3.1. Transaction Persistence Context ........................................................................................... 76
7.3.2. Extended Persistence Context ............................................................................................... 77
7.4. Retrieving Properties Information .................................................................................................... 78
7.5. Closing the EntityManagerFactory ................................................................................................... 78
7.6. PersistenceUnitUtil ....................................................................................................................... 79
8. EntityManager ........................................................................................................................................ 80
8.1. Transaction Association ................................................................................................................. 80
8.2. Entity Lifecycle Management ......................................................................................................... 81
8.3. Lifecycle Examples ...................................................................................................................... 83
8.4. Entity Identity Management ........................................................................................................... 85
8.5. Cache Management ...................................................................................................................... 86
8.6. Query Factory .............................................................................................................................. 87
8.7. Entity Locking ............................................................................................................................. 87
8.8. Retrieving Properties Information .................................................................................................... 88
8.9. Closing ....................................................................................................................................... 89
9. Transaction ............................................................................................................................................ 90
9.1. Transaction Types ........................................................................................................................ 90
9.2. The EntityTransaction Interface ...................................................................................................... 91
10. JPA Query ........................................................................................................................................... 93
10.1. JPQL API ................................................................................................................................. 93
10.1.1. Query Basics ................................................................................................................... 93
10.1.2. Relation Traversal ............................................................................................................ 96
10.1.3. Embeddable Traversal ....................................................................................................... 97
10.1.4. Fetch Joins ...................................................................................................................... 97
10.1.5. JPQL Functions ............................................................................................................... 98
10.1.6. Polymorphic Queries ....................................................................................................... 100
10.1.7. Query Parameters ........................................................................................................... 100
10.1.8. Query Hints ................................................................................................................... 101
10.1.8.1. Locking Hints ...................................................................................................... 101
10.1.8.2. Lock Timeout Hint ............................................................................................... 102
10.1.8.3. Query Timeout Hint ............................................................................................. 102
10.1.8.4. Result Set Size Hint ............................................................................................. 102
10.1.8.5. Isolation Level Hint .............................................................................................. 102
10.1.8.6. Other Fetchplan Hints ........................................................................................... 102
10.1.8.7. Database-Specific Hints ......................................................................................... 102
10.1.8.8. Named Query Hints .............................................................................................. 102
10.1.8.9. Handling of Multiple Similar Query Hints ................................................................ 103
iv
Apache OpenJPA 2.2 User's Guide
10.1.9. Ordering ....................................................................................................................... 103
10.1.10. Aggregates ................................................................................................................... 103
10.1.11. Named Queries ............................................................................................................. 104
10.1.12. Delete By Query ........................................................................................................... 104
10.1.13. Update By Query .......................................................................................................... 105
10.2. JPQL Language Reference .......................................................................................................... 105
10.2.1. JPQL Statement Types .................................................................................................... 105
10.2.1.1. JPQL Select Statement .......................................................................................... 106
10.2.1.2. JPQL Update and Delete Statements ........................................................................ 106
10.2.2. JPQL Abstract Schema Types and Query Domains ............................................................... 106
10.2.2.1. JPQL Entity Naming ............................................................................................ 107
10.2.2.2. JPQL Schema Example ......................................................................................... 107
10.2.3. JPQL FROM Clause and Navigational Declarations .............................................................. 108
10.2.3.1. JPQL FROM Identifiers ........................................................................................ 108
10.2.3.2. JPQL Identification Variables ................................................................................. 111
10.2.3.3. JPQL Range Declarations ...................................................................................... 112
10.2.3.4. JPQL Path Expressions ......................................................................................... 112
10.2.3.5. JPQL Joins ......................................................................................................... 114
10.2.3.5.1. JPQL Inner Joins (Relationship Joins) ........................................................... 115
10.2.3.5.2. JPQL Outer Joins ...................................................................................... 116
10.2.3.5.3. JPQL Fetch Joins ...................................................................................... 116
10.2.3.6. JPQL Collection Member Declarations ..................................................................... 116
10.2.3.7. JPQL FROM Clause and SQL ................................................................................ 117
10.2.3.8. JPQL Polymorphism ............................................................................................. 117
10.2.4. JPQL WHERE Clause ..................................................................................................... 117
10.2.5. JPQL Conditional Expressions .......................................................................................... 118
10.2.5.1. JPQL Literals ...................................................................................................... 118
10.2.5.2. JPQL Identification Variables ................................................................................. 118
10.2.5.3. JPQL Path Expressions ......................................................................................... 119
10.2.5.4. JPQL Input Parameters ......................................................................................... 119
10.2.5.4.1. JPQL Positional Parameters ......................................................................... 119
10.2.5.4.2. JPQL Named Parameters ............................................................................ 119
10.2.5.5. JPQL Conditional Expression Composition ............................................................... 119
10.2.5.6. JPQL Operators and Operator Precedence ................................................................. 120
10.2.5.7. JPQL Comparison Expressions ............................................................................... 120
10.2.5.8. JPQL Between Expressions .................................................................................... 121
10.2.5.9. JPQL In Expressions ............................................................................................ 122
10.2.5.10. JPQL Like Expressions ....................................................................................... 122
10.2.5.11. JPQL Null Comparison Expressions ....................................................................... 123
10.2.5.12. JPQL Empty Collection Comparison Expressions ..................................................... 123
10.2.5.13. JPQL Collection Member Expressions .................................................................... 124
10.2.5.14. JPQL Exists Expressions ..................................................................................... 124
10.2.5.15. JPQL All or Any Expressions ............................................................................... 124
10.2.5.16. JPQL Subqueries ................................................................................................ 125
10.2.6. JPQL Scalar Expressions ................................................................................................. 126
10.2.6.1. Arithmetic Expressions ......................................................................................... 126
10.2.6.2. String, Arithmetic, and Datetime Functional Expressions ............................................. 126
10.2.6.2.1. JPQL String Functions ................................................................................ 126
10.2.6.2.2. JPQL Arithmetic Functions ......................................................................... 127
10.2.6.2.3. JPQL Datetime Functions ............................................................................ 127
10.2.6.3. Case Expressions ................................................................................................. 127
10.2.6.4. Entity Type Expressions ........................................................................................ 128
10.2.7. JPQL GROUP BY, HAVING ........................................................................................... 129
10.2.8. JPQL SELECT Clause .................................................................................................... 130
v
Apache OpenJPA 2.2 User's Guide
10.2.8.1. JPQL Result Type of the SELECT Clause ................................................................ 131
10.2.8.2. JPQL Constructor Expressions ................................................................................ 132
10.2.8.3. JPQL Null Values in the Query Result ..................................................................... 132
10.2.8.4. JPQL Embeddables in the Query Result ................................................................... 132
10.2.8.5. JPQL Aggregate Functions .................................................................................... 133
10.2.8.5.1. JPQL Aggregate Examples .......................................................................... 134
10.2.8.5.2. JPQL Numeric Expressions in the SELECT Clause .......................................... 134
10.2.9. JPQL ORDER BY Clause ................................................................................................ 134
10.2.10. JPQL Bulk Update and Delete ........................................................................................ 136
10.2.11. JPQL Null Values ......................................................................................................... 137
10.2.12. JPQL Equality and Comparison Semantics ........................................................................ 137
10.2.13. JPQL BNF ................................................................................................................... 137
11. JPA Criteria ....................................................................................................................................... 142
11.1. Constructing a CriteriaQuery ....................................................................................................... 142
11.2. Executing a CriteriaQuery .......................................................................................................... 143
11.3. Extension to Criteria API ........................................................................................................... 143
11.4. Generation of Canonical MetaModel classes .................................................................................. 143
12. SQL Queries ....................................................................................................................................... 145
12.1. Creating SQL Queries ................................................................................................................ 145
12.2. Retrieving Persistent Objects with SQL ........................................................................................ 145
13. Mapping Metadata ............................................................................................................................... 147
13.1. Table ...................................................................................................................................... 148
13.2. Unique Constraints .................................................................................................................... 150
13.3. Column ................................................................................................................................... 150
13.4. Identity Mapping ...................................................................................................................... 151
13.5. Generators ............................................................................................................................... 154
13.5.1. Sequence Generator ........................................................................................................ 154
13.5.2. Table Generator ............................................................................................................. 154
13.5.3. Example ........................................................................................................................ 155
13.6. Inheritance ............................................................................................................................... 157
13.6.1. Single Table .................................................................................................................. 157
13.6.1.1. Advantages ......................................................................................................... 158
13.6.1.2. Disadvantages ...................................................................................................... 158
13.6.2. Joined ........................................................................................................................... 158
13.6.2.1. Advantages ......................................................................................................... 160
13.6.2.2. Disadvantages ...................................................................................................... 161
13.6.3. Table Per Class .............................................................................................................. 161
13.6.3.1. Advantages ......................................................................................................... 162
13.6.3.2. Disadvantages ...................................................................................................... 162
13.6.4. Putting it All Together .................................................................................................... 162
13.7. Discriminator ........................................................................................................................... 165
13.8. Field Mapping .......................................................................................................................... 168
13.8.1. Basic Mapping ............................................................................................................... 168
13.8.1.1. LOBs ................................................................................................................. 168
13.8.1.2. Enumerated ......................................................................................................... 168
13.8.1.3. Temporal Types ................................................................................................... 169
13.8.1.4. The Updated Mappings ......................................................................................... 169
13.8.2. Secondary Tables ........................................................................................................... 171
13.8.3. Embedded Mapping ........................................................................................................ 172
13.8.4. Direct Relations ............................................................................................................. 175
13.8.5. Join Table ..................................................................................................................... 179
13.8.6. Bidirectional Mapping ..................................................................................................... 182
13.8.7. Map Mapping ................................................................................................................ 182
13.9. The Complete Mappings ............................................................................................................ 183
vi
Apache OpenJPA 2.2 User's Guide
14. Conclusion ......................................................................................................................................... 187
3. Reference Guide ........................................................................................................................................... 188
1. Introduction .......................................................................................................................................... 196
1.1. Intended Audience ...................................................................................................................... 196
2. Configuration ....................................................................................................................................... 197
2.1. Introduction ............................................................................................................................... 197
2.2. Runtime Configuration ................................................................................................................ 197
2.3. Command Line Configuration ....................................................................................................... 197
2.3.1. Code Formatting .............................................................................................................. 198
2.4. Plugin Configuration ................................................................................................................... 199
2.5. OpenJPA Properties .................................................................................................................... 200
2.5.1. openjpa.AutoClear ............................................................................................................ 200
2.5.2. openjpa.AutoDetach .......................................................................................................... 200
2.5.3. openjpa.BrokerFactory ...................................................................................................... 201
2.5.4. openjpa.BrokerImpl .......................................................................................................... 201
2.5.5. openjpa.Callbacks ............................................................................................................. 201
2.5.6. openjpa.ClassResolver ....................................................................................................... 201
2.5.7. openjpa.Compatibility ....................................................................................................... 202
2.5.8. openjpa.ConnectionDriverName .......................................................................................... 202
2.5.9. openjpa.Connection2DriverName ........................................................................................ 202
2.5.10. openjpa.ConnectionFactory ............................................................................................... 202
2.5.11. openjpa.ConnectionFactory2 ............................................................................................. 203
2.5.12. openjpa.ConnectionFactoryName ....................................................................................... 203
2.5.13. openjpa.ConnectionFactory2Name ..................................................................................... 203
2.5.14. openjpa.ConnectionFactoryMode ....................................................................................... 203
2.5.15. openjpa.ConnectionFactoryProperties ................................................................................. 204
2.5.16. openjpa.ConnectionFactory2Properties ................................................................................ 204
2.5.17. openjpa.ConnectionPassword ............................................................................................ 204
2.5.18. openjpa.Connection2Password .......................................................................................... 204
2.5.19. openjpa.ConnectionProperties ........................................................................................... 205
2.5.20. openjpa.Connection2Properties .......................................................................................... 205
2.5.21. openjpa.ConnectionURL .................................................................................................. 205
2.5.22. openjpa.Connection2URL ................................................................................................ 205
2.5.23. openjpa.ConnectionUserName ........................................................................................... 206
2.5.24. openjpa.Connection2UserName ......................................................................................... 206
2.5.25. openjpa.ConnectionRetainMode ........................................................................................ 206
2.5.26. openjpa.DataCache ......................................................................................................... 206
2.5.27. openjpa.DataCacheManager .............................................................................................. 206
2.5.28. openjpa.DataCacheMode .................................................................................................. 207
2.5.29. openjpa.DataCacheTimeout .............................................................................................. 207
2.5.30. openjpa.DetachState ........................................................................................................ 207
2.5.31. openjpa.DynamicDataStructs ............................................................................................ 207
2.5.32. openjpa.DynamicEnhancementAgent .................................................................................. 208
2.5.33. openjpa.FetchBatchSize ................................................................................................... 208
2.5.34. openjpa.EncryptionProvider .............................................................................................. 208
2.5.35. openjpa.FetchGroups ....................................................................................................... 209
2.5.36. openjpa.FlushBeforeQueries ............................................................................................. 209
2.5.37. openjpa.IgnoreChanges .................................................................................................... 209
2.5.38. openjpa.Id ..................................................................................................................... 209
2.5.39. openjpa.InitializeEagerly .................................................................................................. 209
2.5.40. openjpa.Instrumentation ................................................................................................... 210
2.5.41. openjpa.InverseManager ................................................................................................... 210
2.5.42. openjpa.LockManager ..................................................................................................... 210
2.5.43. openjpa.LockTimeout ...................................................................................................... 211
vii
Apache OpenJPA 2.2 User's Guide
2.5.44. openjpa.Log ................................................................................................................... 211
2.5.45. openjpa.ManagedRuntime ................................................................................................ 211
2.5.46. openjpa.Mapping ............................................................................................................ 211
2.5.47. openjpa.MaxFetchDepth ................................................................................................... 212
2.5.48. openjpa.MetaDataFactory ................................................................................................. 212
2.5.49. openjpa.MetaDataRepository ............................................................................................ 212
2.5.50. openjpa.Multithreaded ..................................................................................................... 212
2.5.51. openjpa.Optimistic .......................................................................................................... 213
2.5.52. openjpa.OptimizeIdCopy .................................................................................................. 213
2.5.53. openjpa.OrphanedKeyAction ............................................................................................ 213
2.5.54. openjpa.NontransactionalRead ........................................................................................... 213
2.5.55. openjpa.NontransactionalWrite .......................................................................................... 214
2.5.56. openjpa.ProxyManager .................................................................................................... 214
2.5.57. openjpa.PostLoadOnMerge ............................................................................................... 214
2.5.58. openjpa.QueryCache ....................................................................................................... 214
2.5.59. openjpa.QueryCompilationCache ....................................................................................... 215
2.5.60. openjpa.ReadLockLevel ................................................................................................... 215
2.5.61. openjpa.RemoteCommitProvider ........................................................................................ 215
2.5.62. openjpa.RestoreState ....................................................................................................... 215
2.5.63. openjpa.RetainState ......................................................................................................... 216
2.5.64. openjpa.RetryClassRegistration ......................................................................................... 216
2.5.65. openjpa.RuntimeUnenhancedClasses .................................................................................. 216
2.5.66. openjpa.SavepointManager ............................................................................................... 217
2.5.67. openjpa.Sequence ........................................................................................................... 217
2.5.68. openjpa.Specification ....................................................................................................... 217
2.5.69. openjpa.TransactionMode ................................................................................................. 217
2.5.70. openjpa.WriteLockLevel .................................................................................................. 218
2.6. OpenJPA JDBC Properties ........................................................................................................... 218
2.6.1. openjpa.jdbc.ConnectionDecorators ..................................................................................... 218
2.6.2. openjpa.jdbc.DBDictionary ................................................................................................ 218
2.6.3. openjpa.jdbc.DriverDataSource ........................................................................................... 219
2.6.4. openjpa.jdbc.EagerFetchMode ............................................................................................ 219
2.6.5. openjpa.jdbc.FetchDirection ............................................................................................... 219
2.6.6. openjpa.jdbc.JDBCListeners ............................................................................................... 219
2.6.7. openjpa.jdbc.LRSSize ....................................................................................................... 220
2.6.8. openjpa.jdbc.MappingDefaults ............................................................................................ 220
2.6.9. openjpa.jdbc.MappingFactory ............................................................................................. 220
2.6.10. openjpa.jdbc.QuerySQLCache ........................................................................................... 220
2.6.11. openjpa.jdbc.ResultSetType .............................................................................................. 221
2.6.12. openjpa.jdbc.Schema ....................................................................................................... 221
2.6.13. openjpa.jdbc.SchemaFactory ............................................................................................. 221
2.6.14. openjpa.jdbc.Schemas ...................................................................................................... 221
2.6.15. openjpa.jdbc.SQLFactory ................................................................................................. 222
2.6.16. openjpa.jdbc.SubclassFetchMode ....................................................................................... 222
2.6.17. openjpa.jdbc.SynchronizeMappings .................................................................................... 222
2.6.18. openjpa.jdbc.TransactionIsolation ...................................................................................... 222
2.6.19. openjpa.jdbc.UpdateManager ............................................................................................ 223
2.6.20. Compatibility with Specification ....................................................................................... 223
3. Logging and Auditing ............................................................................................................................ 224
3.1. Logging Channels ....................................................................................................................... 224
3.2. OpenJPA Logging ...................................................................................................................... 225
3.3. Disabling Logging ...................................................................................................................... 226
3.4. Log4J ....................................................................................................................................... 226
3.5. Apache Commons Logging .......................................................................................................... 227
viii
Apache OpenJPA 2.2 User's Guide
3.5.1. JDK java.util.logging ........................................................................................................ 227
3.6. SLF4J ....................................................................................................................................... 227
3.7. Custom Log ............................................................................................................................... 228
3.8. OpenJPA Audit .......................................................................................................................... 228
3.8.1. Configuration .................................................................................................................. 229
3.8.2. Developing custom auditing ............................................................................................... 229
4. JDBC .................................................................................................................................................. 231
4.1. Using the OpenJPA DataSource .................................................................................................... 231
4.1.1. Optional Connection Pooling .............................................................................................. 231
4.1.2. Configuring the OpenJPA DataSource ................................................................................. 231
4.1.3. Configuring Apache Commons DBCP ................................................................................. 232
4.2. Using a Third-Party DataSource .................................................................................................... 232
4.2.1. Managed and XA DataSources ........................................................................................... 233
4.2.2. Setting the DataSource at runtime ....................................................................................... 233
4.2.2.1. Using different DataSources for each EntityManager .................................................... 234
4.2.2.1.1. Benefits ..................................................................................................... 234
4.2.2.1.2. Limitations ................................................................................................. 234
4.2.2.1.3. Error handling ............................................................................................ 235
4.3. Runtime Access to DataSource ..................................................................................................... 235
4.4. Database Support ........................................................................................................................ 236
4.4.1. DBDictionary Properties .................................................................................................... 237
4.4.2. FirebirdDictionary Properties .............................................................................................. 246
4.4.3. MySQLDictionary Properties ............................................................................................. 246
4.4.4. OracleDictionary Properties ............................................................................................... 246
4.4.5. SybaseDictionary Properties ............................................................................................... 247
4.4.6. DB2 Properties ................................................................................................................ 247
4.4.7. Delimited Identifiers Support ............................................................................................. 247
4.5. Setting the Transaction Isolation .................................................................................................... 248
4.6. Setting the SQL Join Syntax ......................................................................................................... 248
4.7. Accessing Multiple Databases ....................................................................................................... 249
4.8. Configuring the Use of JDBC Connections ..................................................................................... 249
4.9. Statement Batching ..................................................................................................................... 251
4.10. Large Result Sets ...................................................................................................................... 252
4.11. Default Schema ........................................................................................................................ 253
4.12. Schema Reflection .................................................................................................................... 254
4.12.1. Schemas List ................................................................................................................. 254
4.12.2. Schema Factory .............................................................................................................. 254
4.13. Schema Tool ............................................................................................................................ 255
4.14. XML Schema Format ................................................................................................................ 258
5. Persistent Classes .................................................................................................................................. 260
5.1. Persistent Class List .................................................................................................................... 260
5.2. Enhancement ............................................................................................................................. 260
5.2.1. Enhancing at Build Time ................................................................................................... 261
5.2.2. Enhancing JPA Entities on Deployment ............................................................................... 262
5.2.3. Enhancing at Runtime ....................................................................................................... 262
5.2.4. Enhancing Dynamically at Runtime ..................................................................................... 262
5.2.5. Omitting the OpenJPA enhancer ......................................................................................... 263
5.3. Managed Interfaces ..................................................................................................................... 264
5.4. Object Identity ........................................................................................................................... 265
5.4.1. Datastore Identity ............................................................................................................. 265
5.4.2. Entities as Identity Fields .................................................................................................. 265
5.4.3. Application Identity Tool ................................................................................................... 267
5.4.4. Autoassign / Identity Strategy Caveats ................................................................................. 268
5.5. Managed Inverses ....................................................................................................................... 269
ix
Apache OpenJPA 2.2 User's Guide
5.6. Persistent Fields ......................................................................................................................... 270
5.6.1. Restoring State ................................................................................................................ 270
5.6.2. Typing and Ordering ........................................................................................................ 270
5.6.3. Calendar Fields and TimeZones .......................................................................................... 270
5.6.4. Proxies ........................................................................................................................... 270
5.6.4.1. Smart Proxies ........................................................................................................ 271
5.6.4.2. Large Result Set Proxies ......................................................................................... 271
5.6.4.3. Custom Proxies ..................................................................................................... 272
5.6.4.4. Serialization .......................................................................................................... 273
5.6.5. Externalization ................................................................................................................. 273
5.6.5.1. External Values ..................................................................................................... 276
5.7. Fetch Groups ............................................................................................................................. 276
5.7.1. Custom Fetch Groups ....................................................................................................... 276
5.7.2. Custom Fetch Group Configuration ..................................................................................... 278
5.7.3. Per-field Fetch Configuration ............................................................................................. 279
5.7.4. Implementation Notes ....................................................................................................... 280
5.8. Eager Fetching ........................................................................................................................... 280
5.8.1. Configuring Eager Fetching ............................................................................................... 281
5.8.2. Eager Fetching Considerations and Limitations ...................................................................... 282
6. Metadata .............................................................................................................................................. 283
6.1. Metadata Factory ........................................................................................................................ 283
6.2. Metadata Repository ................................................................................................................... 283
6.3. Additional JPA Metadata ............................................................................................................. 284
6.3.1. Datastore Identity ............................................................................................................. 284
6.3.2. Surrogate Version ............................................................................................................ 284
6.3.3. Persistent Field Values ...................................................................................................... 284
6.3.4. Persistent Collection Fields ................................................................................................ 285
6.3.5. Persistent Map Fields ........................................................................................................ 285
6.4. Metadata Extensions ................................................................................................................... 285
6.4.1. Class Extensions .............................................................................................................. 285
6.4.1.1. Fetch Groups ........................................................................................................ 286
6.4.1.2. Data Cache ........................................................................................................... 286
6.4.1.3. Detached State ...................................................................................................... 286
6.4.2. Field Extensions .............................................................................................................. 286
6.4.2.1. Dependent ............................................................................................................ 286
6.4.2.2. Load Fetch Group .................................................................................................. 287
6.4.2.3. LRS .................................................................................................................... 287
6.4.2.4. Inverse-Logical ...................................................................................................... 287
6.4.2.5. Read-Only ............................................................................................................ 287
6.4.2.6. Type .................................................................................................................... 287
6.4.2.7. Externalizer .......................................................................................................... 288
6.4.2.8. Factory ................................................................................................................ 288
6.4.2.9. External Values ..................................................................................................... 288
6.4.3. Example ......................................................................................................................... 288
6.4.4. XML extensions .............................................................................................................. 289
7. Mapping .............................................................................................................................................. 290
7.1. Forward Mapping ....................................................................................................................... 290
7.1.1. Using the Mapping Tool ................................................................................................... 291
7.1.2. Generating DDL SQL ....................................................................................................... 292
7.1.3. Runtime Forward Mapping ................................................................................................ 292
7.2. Reverse Mapping ........................................................................................................................ 293
7.2.1. Customizing Reverse Mapping ........................................................................................... 295
7.3. Meet-in-the-Middle Mapping ........................................................................................................ 297
7.4. Mapping Defaults ....................................................................................................................... 297
x