NHibernate Reference Documentation
Version: 1.2.0
Table of Contents
Preface ...........................................................................................................................................vii
1. Quickstart with IIS and Microsoft SQL Server ...........................................................................1
1.1. Getting started with NHibernate ..........................................................................................1
1.2. First persistent class ...........................................................................................................2
1.3. Mapping the cat .................................................................................................................3
1.4. Playing with cats ................................................................................................................4
1.5. Finally ............................................................................................................................... 6
2. Architecture ................................................................................................................................ 7
2.1. Overview ...........................................................................................................................7
2.2. Instance states .................................................................................................................... 9
2.3. Contextual Sessions ............................................................................................................9
3. ISessionFactory Configuration .................................................................................................. 11
3.1. Programmatic Configuration ............................................................................................. 11
3.2. Obtaining an ISessionFactory ............................................................................................ 12
3.3. User provided ADO.NET connection ................................................................................ 12
3.4. NHibernate provided ADO.NET connection ...................................................................... 12
3.5. Optional configuration properties ...................................................................................... 14
3.5.1. SQL Dialects ......................................................................................................... 16
3.5.2. Outer Join Fetching ............................................................................................... 17
3.5.3. Custom ICacheProvider ......................................................................................... 17
3.5.4. Query Language Substitution ................................................................................. 18
3.6. Logging ........................................................................................................................... 18
3.7. Implementing an INamingStrategy .................................................................................... 18
3.8. XML Configuration File ................................................................................................... 18
4. Persistent Classes ...................................................................................................................... 20
4.1. A simple POCO example .................................................................................................. 20
4.1.1. Declare accessors and mutators for persistent fields ................................................. 21
4.1.2. Implement a default constructor ............................................................................. 21
4.1.3. Provide an identifier property (optional) .................................................................. 21
4.1.4. Prefer non-sealed classes and virtual methods (optional) .......................................... 21
4.2. Implementing inheritance ................................................................................................. 22
4.3. Implementing Equals() and GetHashCode() ....................................................................... 22
4.4. Lifecycle Callbacks .......................................................................................................... 23
4.5. IValidatable callback ........................................................................................................ 24
5. Basic O/R Mapping ................................................................................................................... 25
5.1. Mapping declaration ......................................................................................................... 25
5.1.1. XML Namespace .................................................................................................. 25
5.1.2. hibernate-mapping ................................................................................................. 26
5.1.3. class ..................................................................................................................... 26
5.1.4. id .......................................................................................................................... 28
5.1.4.1. generator .................................................................................................... 28
5.1.4.2. Hi/Lo Algorithm ......................................................................................... 30
5.1.4.3. UUID Hex Algorithm ................................................................................. 30
5.1.4.4. UUID String Algorithm .............................................................................. 30
5.1.4.5. GUID Algorithms ....................................................................................... 30
5.1.4.6. Identity columns and Sequences .................................................................. 30
5.1.4.7. Assigned Identifiers .................................................................................... 31
5.1.5. composite-id ......................................................................................................... 31
NHibernate 1.2.0 ii
5.1.6. discriminator ......................................................................................................... 32
5.1.7. version (optional) .................................................................................................. 32
5.1.8. timestamp (optional) .............................................................................................. 33
5.1.9. property ................................................................................................................ 33
5.1.10. many-to-one ........................................................................................................ 36
5.1.11. one-to-one ........................................................................................................... 37
5.1.12. component, dynamic-component .......................................................................... 38
5.1.13. subclass .............................................................................................................. 39
5.1.14. joined-subclass .................................................................................................... 39
5.1.15. map, set, list, bag ................................................................................................. 40
5.1.16. import ................................................................................................................. 40
5.2. NHibernate Types ............................................................................................................ 41
5.2.1. Entities and values ................................................................................................. 41
5.2.2. Basic value types ................................................................................................... 41
5.2.3. Custom value types ............................................................................................... 43
5.2.4. Any type mappings ................................................................................................ 44
5.3. SQL quoted identifiers ...................................................................................................... 45
5.4. Modular mapping files ...................................................................................................... 45
5.5. Generated Properties ........................................................................................................ 46
5.6. Auxiliary Database Objects ............................................................................................... 46
6. Collection Mapping ................................................................................................................... 48
6.1. Persistent Collections ....................................................................................................... 48
6.2. Mapping a Collection ....................................................................................................... 49
6.3. Collections of Values and Many-To-Many Associations ..................................................... 50
6.4. One-To-Many Associations .............................................................................................. 52
6.5. Lazy Initialization ............................................................................................................ 53
6.6. Sorted Collections ............................................................................................................ 54
6.7. Using an <idbag> ............................................................................................................. 55
6.8. Bidirectional Associations ................................................................................................ 55
6.9. Ternary Associations ........................................................................................................ 56
6.10. Heterogeneous Associations ............................................................................................ 57
6.11. Collection examples ....................................................................................................... 57
7. Component Mapping ................................................................................................................ 60
7.1. Dependent objects ............................................................................................................ 60
7.2. Collections of dependent objects ....................................................................................... 61
7.3. Components as IDictionary indices .................................................................................... 62
7.4. Components as composite identifiers ................................................................................. 62
7.5. Dynamic components ....................................................................................................... 64
8. Inheritance Mapping ................................................................................................................. 65
8.1. The Three Strategies ......................................................................................................... 65
8.2. Limitations ...................................................................................................................... 67
9. Manipulating Persistent Data .................................................................................................... 69
9.1. Creating a persistent object ............................................................................................... 69
9.2. Loading an object ............................................................................................................. 69
9.3. Querying ......................................................................................................................... 70
9.3.1. Scalar queries ........................................................................................................ 71
9.3.2. The IQuery interface .............................................................................................. 72
9.3.3. Filtering collections ............................................................................................... 73
9.3.4. Criteria queries ...................................................................................................... 73
9.3.5. Queries in native SQL ............................................................................................ 73
9.4. Updating objects .............................................................................................................. 74
9.4.1. Updating in the same ISession ................................................................................ 74
NHibernate - Relational Persistence for Idiomatic .NET
NHibernate 1.2.0 iii
9.4.2. Updating detached objects ...................................................................................... 74
9.4.3. Reattaching detached objects .................................................................................. 75
9.5. Deleting persistent objects ................................................................................................ 76
9.6. Flush ............................................................................................................................... 76
9.7. Ending a Session .............................................................................................................. 77
9.7.1. Flushing the Session .............................................................................................. 77
9.7.2. Committing the database transaction ....................................................................... 77
9.7.3. Closing the ISession .............................................................................................. 77
9.8. Exception handling ........................................................................................................... 78
9.9. Lifecyles and object graphs ............................................................................................... 78
9.10. Interceptors .................................................................................................................... 79
9.11. Metadata API ................................................................................................................. 81
10. Transactions And Concurrency ............................................................................................... 82
10.1. Configurations, Sessions and Factories ............................................................................ 82
10.2. Threads and connections ................................................................................................. 82
10.3. Considering object identity ............................................................................................. 82
10.4. Optimistic concurrency control ........................................................................................ 83
10.4.1. Long session with automatic versioning ................................................................ 83
10.4.2. Many sessions with automatic versioning .............................................................. 83
10.4.3. Customizing automatic versioning ........................................................................ 84
10.4.4. Application version checking ............................................................................... 84
10.5. Session disconnection ..................................................................................................... 85
10.6. Pessimistic Locking ........................................................................................................ 86
10.7. Connection Release Modes ............................................................................................. 87
11. HQL: The Hibernate Query Language .................................................................................... 88
11.1. Case Sensitivity .............................................................................................................. 88
11.2. The from clause .............................................................................................................. 88
11.3. Associations and joins .................................................................................................... 88
11.4. The select clause ............................................................................................................ 89
11.5. Aggregate functions ....................................................................................................... 90
11.6. Polymorphic queries ....................................................................................................... 90
11.7. The where clause ............................................................................................................ 91
11.8. Expressions .................................................................................................................... 92
11.9. The order by clause ........................................................................................................ 94
11.10. The group by clause ...................................................................................................... 95
11.11. Subqueries ................................................................................................................... 95
11.12. HQL examples ............................................................................................................. 96
11.13. Tips & Tricks ............................................................................................................... 97
12. Criteria Queries ...................................................................................................................... 99
12.1. Creating an ICriteria instance .......................................................................................... 99
12.2. Narrowing the result set .................................................................................................. 99
12.3. Ordering the results ...................................................................................................... 100
12.4. Associations ................................................................................................................. 100
12.5. Dynamic association fetching ........................................................................................ 100
12.6. Example queries ........................................................................................................... 101
12.7. Projections, aggregation and grouping ........................................................................... 101
12.8. Detached queries and subqueries ................................................................................... 102
13. Native SQL ............................................................................................................................ 104
13.1. Using an ISQLQuery .................................................................................................... 104
13.1.1. Scalar queries .................................................................................................... 104
13.1.2. Entity queries .................................................................................................... 104
13.1.3. Handling associations and collections ................................................................. 105
NHibernate - Relational Persistence for Idiomatic .NET
NHibernate 1.2.0 iv
13.1.4. Returning multiple entities ................................................................................. 105
13.1.4.1. Alias and property references ................................................................... 106
13.1.5. Returning non-managed entities .......................................................................... 107
13.1.6. Handling inheritance .......................................................................................... 107
13.1.7. Parameters ........................................................................................................ 107
13.2. Named SQL queries ..................................................................................................... 107
13.2.1. Using return-property to explicitly specify column/alias names ............................. 108
13.2.2. Using stored procedures for querying .................................................................. 109
13.2.2.1. Rules/limitations for using stored procedures ............................................ 110
13.3. Custom SQL for create, update and delete ...................................................................... 110
13.4. Custom SQL for loading ............................................................................................... 111
14. Filtering data ......................................................................................................................... 113
14.1. NHibernate filters ......................................................................................................... 113
15. Improving performance ........................................................................................................ 115
15.1. Fetching strategies ........................................................................................................ 115
15.1.1. Working with lazy associations .......................................................................... 115
15.1.2. Tuning fetch strategies ....................................................................................... 116
15.1.3. Single-ended association proxies ........................................................................ 117
15.1.4. Initializing collections and proxies ...................................................................... 118
15.1.5. Using batch fetching .......................................................................................... 119
15.1.6. Using subselect fetching ..................................................................................... 120
15.2. The Second Level Cache ............................................................................................... 120
15.2.1. Cache mappings ................................................................................................ 120
15.2.2. Strategy: read only ............................................................................................. 121
15.2.3. Strategy: read/write ............................................................................................ 121
15.2.4. Strategy: nonstrict read/write .............................................................................. 121
15.3. Managing the caches .................................................................................................... 122
15.4. The Query Cache ......................................................................................................... 122
15.5. Understanding Collection performance .......................................................................... 123
15.5.1. Taxonomy ......................................................................................................... 123
15.5.2. Lists, maps, idbags and sets are the most efficient collections to update ................. 124
15.5.3. Bags and lists are the most efficient inverse collections ........................................ 124
15.5.4. One shot delete .................................................................................................. 124
15.6. Batch updates ............................................................................................................... 125
15.7. Multi Query ................................................................................................................. 125
16. Toolset Guide ........................................................................................................................ 127
16.1. Schema Generation ....................................................................................................... 127
16.1.1. Customizing the schema ..................................................................................... 127
16.1.2. Running the tool ................................................................................................ 128
16.1.3. Properties .......................................................................................................... 129
16.1.4. Using Ant ......................................................................................................... 129
16.2. Code Generation .......................................................................................................... 130
16.2.1. The config file (optional) ................................................................................... 130
16.2.2. The meta attribute .............................................................................................. 131
16.2.3. Basic finder generator ........................................................................................ 133
16.2.4. Velocity based renderer/generator ....................................................................... 134
16.3. Mapping File Generation .............................................................................................. 134
16.3.1. Running the tool ................................................................................................ 135
17. Example: Parent/Child .......................................................................................................... 137
17.1. A note about collections ................................................................................................ 137
17.2. Bidirectional one-to-many ............................................................................................. 137
17.3. Cascading lifecycle ....................................................................................................... 138
NHibernate - Relational Persistence for Idiomatic .NET
NHibernate 1.2.0 v
