Hibernate OGM Reference Guide 4.1.3.Final by Emmanuel Bernard (Red Hat), Sanne Grinovero (Red Hat), Gunnar Morling (Red Hat), and Davide D'Alto (Red Hat) Preface ............................................................................................................................ vii 1. Goals .................................................................................................................. viii 2. What we have today ............................................................................................. ix 3. Experimental features ............................................................................................ x 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 2. Getting started with Hibernate OGM ............................................................................ 5 3. Architecture ............................................................................................................... 11 3.1. General architecture .......................................................................................... 11 3.2. How is data persisted ....................................................................................... 13 3.3. How is data queried .......................................................................................... 19 4. Configure and start Hibernate OGM .......................................................................... 23 4.1. Bootstrapping Hibernate OGM ........................................................................... 23 4.1.1. Using JPA ............................................................................................. 23 4.1.2. Using Hibernate ORM native APIs .......................................................... 24 4.2. Environments .................................................................................................... 25 4.2.1. In a Java EE container ........................................................................... 25 4.2.2. In a standalone JTA environment ............................................................ 26 4.2.3. Without JTA ........................................................................................... 27 4.3. Configuration options ........................................................................................ 28 4.4. Configuring Hibernate Search ............................................................................ 28 4.5. How to package Hibernate OGM applications for WildFly 8.2 ............................... 28 4.5.1. Packaging Hibernate OGM applications for WildFly 8.2 ............................. 29 4.5.2. Loading both the Hibernate Search and Hibernate OGM modules WildFly 8.2 .................................................................................................................. 30 5. Map your entities ....................................................................................................... 31 5.1. Supported entity mapping .................................................................................. 31 5.2. Supported Types .............................................................................................. 32 5.3. Supported association mapping ......................................................................... 32 6. Hibernate OGM APIs .................................................................................................. 35 6.1. Bootstrap Hibernate OGM ................................................................................. 35 6.2. JPA and native Hibernate ORM APIs ................................................................. 35 6.2.1. Accessing the OgmSession API .............................................................. 36 6.3. On flush and transactions .................................................................................. 36 6.4. SPIs ................................................................................................................. 37 7. Query your entities .................................................................................................... 39 7.1. Using JP-QL ..................................................................................................... 39 7.2. Using the native query language of your NoSQL ................................................. 42 7.3. Using Hibernate Search .................................................................................... 43 7.4. Using the Criteria API ....................................................................................... 44 iii Hibernate OGM Reference Guide 8. NoSQL datastores ..................................................................................................... 45 8.1. Using a specific NoSQL datastore ..................................................................... 45 9. Infinispan ................................................................................................................... 47 9.1. Configure Infinispan .......................................................................................... 47 9.1.1. Adding Infinispan dependencies .............................................................. 47 9.1.2. Infinispan specific configuration properties ............................................... 48 9.1.3. Cache names used by Hibernate OGM ................................................... 49 9.2. Manage data size ............................................................................................. 50 9.3. Clustering: store data on multiple Infinispan nodes .............................................. 51 9.4. Storage principles ............................................................................................. 54 9.4.1. Properties and built-in types .................................................................... 54 9.4.2. Identifiers ............................................................................................... 55 9.4.3. Entities .................................................................................................. 59 9.4.4. Associations ........................................................................................... 63 9.5. Transactions ..................................................................................................... 76 9.6. Storing a Lucene index in Infinispan .................................................................. 77 10. Ehcache ................................................................................................................... 79 10.1. Configure Ehcache .......................................................................................... 79 10.1.1. Adding Ehcache dependencies ............................................................. 79 10.1.2. Ehcache specific configuration properties ............................................... 79 10.1.3. Cache names used by Hibernate OGM .................................................. 80 10.2. Storage principles ........................................................................................... 81 10.2.1. Properties and built-in types .................................................................. 81 10.2.2. Identifiers ............................................................................................. 82 10.2.3. Entities ................................................................................................ 86 10.2.4. Associations ......................................................................................... 90 10.3. Transactions ................................................................................................. 103 11. MongoDB ............................................................................................................... 105 11.1. Configuring MongoDB ................................................................................... 105 11.1.1. Adding MongoDB dependencies .......................................................... 105 11.1.2. MongoDB specific configuration properties ........................................... 105 11.1.3. Annotation based configuration ............................................................ 108 11.1.4. Programmatic configuration ................................................................. 109 11.2. Storage principles ......................................................................................... 110 11.2.1. Properties and built-in types ................................................................ 110 11.2.2. Entities ............................................................................................... 113 11.2.3. Associations ....................................................................................... 126 11.3. Transactions ................................................................................................. 155 11.4. Optimistic Locking ........................................................................................