Hibernate OGM Reference Guide
Total Page:16
File Type:pdf, Size:1020Kb
Hibernate OGM Reference Guide Emmanuel Bernard Sanne Grinovero Gunnar Morling Davide D'Alto Guillaume Scheibel Mark Paluch Hibernate OGM Reference Guide by Emmanuel Bernard, Sanne Grinovero, Gunnar Morling, Davide D'Alto, Guillaume Scheibel, and Mark Paluch 5.0.4.Final Preface ............................................................................................................................ vii 1. Goals ................................................................................................................... vii 2. What we have today ............................................................................................. ix 3. Experimental features ............................................................................................ ix 4. Use cases ............................................................................................................. x 1. How to get help and contribute on Hibernate OGM ..................................................... 1 1.1. How to get help .................................................................................................. 1 1.2. How to contribute ............................................................................................... 1 1.2.1. How to build Hibernate OGM .................................................................... 1 1.2.2. How to contribute code effectively ............................................................. 2 1.3. How to build support for a data store ................................................................... 3 1.3.1. DataStore providers ................................................................................. 3 1.3.2. Dialects ................................................................................................... 4 1.3.3. Entities .................................................................................................... 5 1.3.4. Associations ............................................................................................ 6 1.3.5. Configuration ........................................................................................... 6 1.3.6. Types ...................................................................................................... 7 1.3.7. Tests ....................................................................................................... 7 2. Getting started with Hibernate OGM ............................................................................ 9 3. Architecture ............................................................................................................... 14 3.1. General architecture .......................................................................................... 14 3.2. How is data persisted ....................................................................................... 16 3.3. Id generation using sequences .......................................................................... 22 3.4. How is data queried .......................................................................................... 22 4. Configure and start Hibernate OGM .......................................................................... 25 4.1. Bootstrapping Hibernate OGM ........................................................................... 25 4.1.1. Using JPA ............................................................................................. 25 4.1.2. Using Hibernate ORM native APIs .......................................................... 26 4.2. Environments .................................................................................................... 27 4.2.1. In a Java EE container ........................................................................... 27 4.2.2. In a standalone JTA environment ............................................................ 28 4.2.3. Without JTA ........................................................................................... 30 4.3. Configuration options ........................................................................................ 30 4.4. Configuring Hibernate Search ............................................................................ 30 4.5. How to package Hibernate OGM applications for WildFly 10 ................................ 31 4.5.1. Packaging Hibernate OGM applications for WildFly 10 .............................. 31 4.5.2. Configure your persistence.xml to use your choice of persistence provider ... 32 4.5.3. Enabling both the Hibernate Search and Hibernate OGM modules ............. 32 4.5.4. Using the Hibernate OGM modules with Infinispan ................................... 33 5. Map your entities ....................................................................................................... 35 5.1. Supported entity mapping .................................................................................. 35 5.2. Supported Types .............................................................................................. 36 5.3. Supported association mapping ......................................................................... 37 6. Hibernate OGM APIs .................................................................................................. 38 iii Hibernate OGM Reference Guide 6.1. Bootstrap Hibernate OGM ................................................................................. 38 6.2. JPA and native Hibernate ORM APIs ................................................................. 38 6.2.1. Accessing the OgmSession API ............................................................... 39 6.3. On flush and transactions .................................................................................. 39 6.3.1. Acting upon errors during application of changes ...................................... 41 6.4. SPIs ................................................................................................................. 43 7. Query your entities .................................................................................................... 44 7.1. Using JP-QL ..................................................................................................... 44 7.2. Using the native query language of your NoSQL ................................................. 48 7.3. Using Hibernate Search .................................................................................... 49 7.4. Using the Criteria API ....................................................................................... 51 8. NoSQL datastores ..................................................................................................... 52 8.1. Using a specific NoSQL datastore ..................................................................... 52 9. Infinispan ................................................................................................................... 54 9.1. Configure Infinispan .......................................................................................... 54 9.1.1. Adding Infinispan dependencies .............................................................. 54 9.1.2. Infinispan specific configuration properties ............................................... 55 9.1.3. Cache names used by Hibernate OGM ................................................... 56 9.2. Manage data size ............................................................................................. 57 9.3. Clustering: store data on multiple Infinispan nodes .............................................. 58 9.4. Storage principles ............................................................................................. 61 9.4.1. Properties and built-in types .................................................................... 61 9.4.2. Identifiers ............................................................................................... 62 9.4.3. Entities .................................................................................................. 66 9.4.4. Associations ........................................................................................... 70 9.5. Transactions ..................................................................................................... 83 9.6. Storing a Lucene index in Infinispan .................................................................. 84 10. Ehcache ................................................................................................................... 86 10.1. Configure Ehcache .......................................................................................... 86 10.1.1. Adding Ehcache dependencies ............................................................. 86 10.1.2. Ehcache specific configuration properties ............................................... 87 10.1.3. Cache names used by Hibernate OGM .................................................. 87 10.2. Storage principles ........................................................................................... 88 10.2.1. Properties and built-in types .................................................................. 88 10.2.2. Identifiers ............................................................................................. 89 10.2.3. Entities ................................................................................................ 93 10.2.4. Associations ......................................................................................... 97 10.3. Transactions ................................................................................................