NHibernate Reference Documentation
Version: 3.3
Table of Contents
Preface ..........................................................................................................................................viii
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 .......................................................................................................... 10
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 ......................................................................................... 18
3.5.4. Query Language Substitution ................................................................................. 18
3.6. Logging ........................................................................................................................... 18
3.7. Implementing an INamingStrategy .................................................................................... 18
3.8. XML Configuration File ................................................................................................... 19
4. Persistent Classes ...................................................................................................................... 20
4.1. A simple POCO example .................................................................................................. 20
4.1.1. Declare properties for persistent fields .................................................................... 20
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 ................................................................................................. 21
4.3. Implementing Equals() and GetHashCode() ....................................................................... 21
4.4. Dynamic models .............................................................................................................. 22
4.5. Tuplizers ......................................................................................................................... 24
4.6. Lifecycle Callbacks .......................................................................................................... 25
4.7. IValidatable callback ........................................................................................................ 25
5. Basic O/R Mapping ................................................................................................................... 27
5.1. Mapping declaration ......................................................................................................... 27
5.1.1. XML Namespace .................................................................................................. 27
5.1.2. hibernate-mapping ................................................................................................. 28
5.1.3. class ..................................................................................................................... 28
5.1.4. id .......................................................................................................................... 30
5.1.4.1. generator .................................................................................................... 31
5.1.4.2. Hi/Lo Algorithm ......................................................................................... 32
5.1.4.3. UUID Hex Algorithm ................................................................................. 32
5.1.4.4. UUID String Algorithm .............................................................................. 33
5.1.4.5. GUID Algorithms ....................................................................................... 33
5.1.4.6. Identity columns and Sequences .................................................................. 33
NHibernate 3.3 ii
5.1.4.7. Assigned Identifiers .................................................................................... 33
5.1.5. composite-id ......................................................................................................... 33
5.1.6. discriminator ......................................................................................................... 34
5.1.7. version (optional) .................................................................................................. 35
5.1.8. timestamp (optional) .............................................................................................. 35
5.1.9. property ................................................................................................................ 36
5.1.10. many-to-one ........................................................................................................ 38
5.1.11. one-to-one ........................................................................................................... 39
5.1.12. natural-id ............................................................................................................ 41
5.1.13. component, dynamic-component .......................................................................... 41
5.1.14. properties ............................................................................................................ 42
5.1.15. subclass .............................................................................................................. 43
5.1.16. joined-subclass .................................................................................................... 43
5.1.17. union-subclass ..................................................................................................... 44
5.1.18. join ..................................................................................................................... 45
5.1.19. map, set, list, bag ................................................................................................. 46
5.1.20. import ................................................................................................................. 46
5.2. NHibernate Types ............................................................................................................ 46
5.2.1. Entities and values ................................................................................................. 46
5.2.2. Basic value types ................................................................................................... 46
5.2.3. Custom value types ............................................................................................... 49
5.2.4. Any type mappings ................................................................................................ 50
5.3. SQL quoted identifiers ...................................................................................................... 51
5.4. Modular mapping files ...................................................................................................... 51
5.5. Generated Properties ........................................................................................................ 51
5.6. Auxiliary Database Objects ............................................................................................... 52
6. Collection Mapping ................................................................................................................... 54
6.1. Persistent Collections ....................................................................................................... 54
6.2. Mapping a Collection ....................................................................................................... 55
6.3. Collections of Values and Many-To-Many Associations ..................................................... 56
6.4. One-To-Many Associations .............................................................................................. 58
6.5. Lazy Initialization ............................................................................................................ 59
6.6. Sorted Collections ............................................................................................................ 60
6.7. Using an <idbag> ............................................................................................................. 61
6.8. Bidirectional Associations ................................................................................................ 61
6.9. Ternary Associations ........................................................................................................ 62
6.10. Heterogeneous Associations ............................................................................................ 63
6.11. Collection examples ....................................................................................................... 63
7. Component Mapping ................................................................................................................ 66
7.1. Dependent objects ............................................................................................................ 66
7.2. Collections of dependent objects ....................................................................................... 67
7.3. Components as IDictionary indices .................................................................................... 68
7.4. Components as composite identifiers ................................................................................. 68
7.5. Dynamic components ....................................................................................................... 70
8. Inheritance Mapping ................................................................................................................. 71
8.1. The Three Strategies ......................................................................................................... 71
8.1.1. Table per class hierarchy ........................................................................................ 71
8.1.2. Table per subclass ................................................................................................. 72
8.1.3. Table per subclass, using a discriminator ................................................................. 72
8.1.4. Mixing table per class hierarchy with table per subclass ........................................... 73
8.1.5. Table per concrete class ......................................................................................... 73
8.1.6. Table per concrete class, using implicit polymorphism ............................................. 74
NHibernate - Relational Persistence for Idiomatic .NET
NHibernate 3.3 iii
8.1.7. Mixing implicit polymorphism with other inheritance mappings ............................... 74
8.2. Limitations ...................................................................................................................... 75
9. Manipulating Persistent Data .................................................................................................... 77
9.1. Creating a persistent object ............................................................................................... 77
9.2. Loading an object ............................................................................................................. 77
9.3. Querying ......................................................................................................................... 78
9.3.1. Scalar queries ........................................................................................................ 79
9.3.2. The IQuery interface .............................................................................................. 80
9.3.3. Filtering collections ............................................................................................... 81
9.3.4. Criteria queries ...................................................................................................... 81
9.3.5. Queries in native SQL ............................................................................................ 81
9.4. Updating objects .............................................................................................................. 82
9.4.1. Updating in the same ISession ................................................................................ 82
9.4.2. Updating detached objects ...................................................................................... 82
9.4.3. Reattaching detached objects .................................................................................. 83
9.5. Deleting persistent objects ................................................................................................ 84
9.6. Flush ............................................................................................................................... 84
9.7. Ending a Session .............................................................................................................. 85
9.7.1. Flushing the Session .............................................................................................. 85
9.7.2. Committing the database transaction ....................................................................... 85
9.7.3. Closing the ISession .............................................................................................. 85
9.8. Exception handling ........................................................................................................... 86
9.9. Lifecyles and object graphs ............................................................................................... 86
9.10. Interceptors .................................................................................................................... 87
9.11. Metadata API ................................................................................................................. 89
10. Read-only entities .................................................................................................................... 90
10.1. Making persistent entities read-only ................................................................................ 90
10.1.1. Entities of immutable classes ................................................................................ 91
10.1.2. Loading persistent entities as read-only ................................................................. 91
10.1.3. Loading read-only entities from an HQL query/criteria .......................................... 92
10.1.4. Making a persistent entity read-only ..................................................................... 93
10.2. Read-only affect on property type .................................................................................... 93
10.2.1. Simple properties ................................................................................................. 94
10.2.2. Unidirectional associations ................................................................................... 95
10.2.2.1. Unidirectional one-to-one and many-to-one ................................................ 95
10.2.2.2. Unidirectional one-to-many and many-to-many .......................................... 96
10.2.3. Bidirectional associations ..................................................................................... 96
10.2.3.1. Bidirectional one-to-one ............................................................................ 96
10.2.3.2. Bidirectional one-to-many/many-to-one ..................................................... 97
10.2.3.3. Bidirectional many-to-many ...................................................................... 97
11. Transactions And Concurrency ............................................................................................... 98
11.1. Configurations, Sessions and Factories ............................................................................ 98
11.2. Threads and connections ................................................................................................. 98
11.3. Considering object identity ............................................................................................. 98
11.4. Optimistic concurrency control ........................................................................................ 99
11.4.1. Long session with automatic versioning ................................................................ 99
11.4.2. Many sessions with automatic versioning .............................................................. 99
11.4.3. Customizing automatic versioning ...................................................................... 100
11.4.4. Application version checking ............................................................................. 100
11.5. Session disconnection ................................................................................................... 101
11.6. Pessimistic Locking ...................................................................................................... 102
11.7. Connection Release Modes ........................................................................................... 103
NHibernate - Relational Persistence for Idiomatic .NET
NHibernate 3.3 iv
12. Interceptors and events ......................................................................................................... 104
12.1. Interceptors .................................................................................................................. 104
12.2. Event system ................................................................................................................ 105
13. Batch processing .................................................................................................................... 107
13.1. Batch inserts ................................................................................................................ 107
13.2. The StatelessSession interface ....................................................................................... 107
13.3. DML-style operations ................................................................................................... 108
14. HQL: The Hibernate Query Language .................................................................................. 111
14.1. Case Sensitivity ............................................................................................................ 111
14.2. The from clause ............................................................................................................ 111
14.3. Associations and joins .................................................................................................. 111
14.4. The select clause .......................................................................................................... 112
14.5. Aggregate functions ..................................................................................................... 113
14.6. Polymorphic queries ..................................................................................................... 113
14.7. The where clause .......................................................................................................... 114
14.8. Expressions .................................................................................................................. 115
14.9. The order by clause ...................................................................................................... 117
14.10. The group by clause .................................................................................................... 118
14.11. Subqueries ................................................................................................................. 118
14.12. HQL examples ........................................................................................................... 119
14.13. Tips & Tricks ............................................................................................................. 120
15. Criteria Queries .................................................................................................................... 122
15.1. Creating an ICriteria instance ........................................................................................ 122
15.2. Narrowing the result set ................................................................................................ 122
15.3. Ordering the results ...................................................................................................... 123
15.4. Associations ................................................................................................................. 123
15.5. Dynamic association fetching ........................................................................................ 123
15.6. Example queries ........................................................................................................... 124
15.7. Projections, aggregation and grouping ........................................................................... 124
15.8. Detached queries and subqueries ................................................................................... 125
16. QueryOver Queries ............................................................................................................... 127
16.1. Structure of a Query ..................................................................................................... 127
16.2. Simple Expressions ...................................................................................................... 127
16.3. Additional Restrictions ................................................................................................. 129
16.4. Associations ................................................................................................................. 129
16.5. Aliases ......................................................................................................................... 130
16.6. Projections ................................................................................................................... 130
16.7. Projection Functions ..................................................................................................... 132
16.8. Subqueries ................................................................................................................... 132
17. Native SQL ............................................................................................................................ 133
17.1. Using an ISQLQuery .................................................................................................... 133
17.1.1. Scalar queries .................................................................................................... 133
17.1.2. Entity queries .................................................................................................... 133
17.1.3. Handling associations and collections ................................................................. 134
17.1.4. Returning multiple entities ................................................................................. 134
17.1.4.1. Alias and property references ................................................................... 135
17.1.5. Returning non-managed entities .......................................................................... 136
17.1.6. Handling inheritance .......................................................................................... 136
17.1.7. Parameters ........................................................................................................ 136
17.2. Named SQL queries ..................................................................................................... 136
17.2.1. Using return-property to explicitly specify column/alias names ............................. 138
17.2.2. Using stored procedures for querying .................................................................. 138
NHibernate - Relational Persistence for Idiomatic .NET
NHibernate 3.3 v
