Apache OpenJPA User's Guide Apache OpenJPA User's Guide 1. Introduction ............................................................................................................................................. 1 1. OpenJPA ......................................................................................................................................... 3 1.1. About This Document ............................................................................................................. 3 2. Java Persistence API ................................................................................................................................. 4 1. Introduction ..................................................................................................................................... 9 1.1. Intended Audience .................................................................................................................. 9 1.2. Lightweight Persistence ........................................................................................................... 9 2. Why JPA? ......................................................................................................................................10 3. Java Persistence API Architecture .......................................................................................................12 3.1. JPA Exceptions .....................................................................................................................13 4. Entity ............................................................................................................................................15 4.1. Restrictions on Persistent Classes .............................................................................................16 4.1.1. Default or No-Arg Constructor ......................................................................................16 4.1.2. Final ........................................................................................................................16 4.1.3. Identity Fields ............................................................................................................16 4.1.4. Version Field .............................................................................................................16 4.1.5. Inheritance ................................................................................................................17 4.1.6. Persistent Fields .........................................................................................................17 4.1.7. Conclusions ...............................................................................................................18 4.2. Entity Identity ......................................................................................................................18 4.2.1. Identity Class .............................................................................................................19 4.2.1.1. Identity Hierarchies ..........................................................................................20 4.3. Lifecycle Callbacks ...............................................................................................................21 4.3.1. Callback Methods .......................................................................................................21 4.3.2. Using Callback Methods ..............................................................................................22 4.3.3. Using Entity Listeners .................................................................................................22 4.3.4. Entity Listeners Hierarchy ............................................................................................23 4.4. Conclusions .........................................................................................................................24 5. Metadata ........................................................................................................................................25 5.1. Class Metadata .....................................................................................................................26 5.1.1. Entity .......................................................................................................................26 5.1.2. Id Class .....................................................................................................................27 5.1.3. Mapped Superclass .....................................................................................................27 5.1.4. Embeddable ...............................................................................................................27 5.1.5. EntityListeners ...........................................................................................................28 5.1.6. Example ...................................................................................................................28 5.2. Field and Property Metadata ....................................................................................................29 5.2.1. Transient ...................................................................................................................30 5.2.2. Id .............................................................................................................................31 5.2.3. Generated Value .........................................................................................................31 5.2.4. Embedded Id .............................................................................................................32 5.2.5. Version .....................................................................................................................32 5.2.6. Basic ........................................................................................................................32 5.2.6.1. Fetch Type ......................................................................................................33 5.2.7. Embedded .................................................................................................................33 5.2.8. Many To One .............................................................................................................34 5.2.8.1. Cascade Type ..................................................................................................34 5.2.9. One To Many .............................................................................................................35 5.2.9.1. Bidirectional Relations ......................................................................................36 5.2.10. One To One .............................................................................................................37 5.2.11. Many To Many .........................................................................................................37 5.2.12. Order By .................................................................................................................38 5.2.13. Map Key .................................................................................................................38 5.2.14. Persistent Field Defaults .............................................................................................38 5.3. XML Schema .......................................................................................................................39 5.4. Conclusion ...........................................................................................................................55 6. Persistence .....................................................................................................................................60 6.1. persistence.xml .....................................................................................................................60 iv Apache OpenJPA User's Guide 6.2. Non-EE Use .........................................................................................................................62 7. EntityManagerFactory ......................................................................................................................63 7.1. Obtaining an EntityManagerFactory ..........................................................................................63 7.2. Obtaining EntityManagers ......................................................................................................63 7.3. Persistence Context ...............................................................................................................64 7.3.1. Transaction Persistence Context ....................................................................................64 7.3.2. Extended Persistence Context ........................................................................................65 7.4. Closing the EntityManagerFactory ............................................................................................66 8. EntityManager ................................................................................................................................67 8.1. Transaction Association ..........................................................................................................67 8.2. Entity Lifecycle Management ..................................................................................................68 8.3. Lifecycle Examples ...............................................................................................................71