Nhibernate Reference

NHibernate Reference Documentation Version: 2.1.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 .......................................................................................................... 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 ......................................................................................... 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. Dynamic models .............................................................................................................. 23 4.5. Tuplizers ......................................................................................................................... 24 4.6. Lifecycle Callbacks .......................................................................................................... 25 4.7. IValidatable callback ........................................................................................................ 26 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 .................................................................................................... 30 5.1.4.2. Hi/Lo Algorithm ......................................................................................... 32 5.1.4.3. UUID Hex Algorithm ................................................................................. 32 5.1.4.4. UUID String Algorithm .............................................................................. 32 5.1.4.5. GUID Algorithms ....................................................................................... 32 5.1.4.6. Identity columns and Sequences .................................................................. 32 NHibernate 2.1.0

ii

NHibernate - Relational Persistence for Idiomatic .NET 5.1.4.7. Assigned Identifiers .................................................................................... 33 5.1.5. composite-id ......................................................................................................... 33 5.1.6. discriminator ......................................................................................................... 34 5.1.7. version (optional) .................................................................................................. 34 5.1.8. timestamp (optional) .............................................................................................. 35 5.1.9. property ................................................................................................................ 35 5.1.10. many-to-one ........................................................................................................ 38 5.1.11. one-to-one ........................................................................................................... 39 5.1.12. natural-id ............................................................................................................ 40 5.1.13. component, dynamic-component .......................................................................... 41 5.1.14. subclass .............................................................................................................. 41 5.1.15. joined-subclass .................................................................................................... 42 5.1.16. union-subclass ..................................................................................................... 43 5.1.17. join ..................................................................................................................... 43 5.1.18. map, set, list, bag ................................................................................................. 44 5.1.19. import ................................................................................................................. 44 5.2. NHibernate Types ............................................................................................................ 45 5.2.1. Entities and values ................................................................................................. 45 5.2.2. Basic value types ................................................................................................... 45 5.2.3. Custom value types ............................................................................................... 47 5.2.4. Any type mappings ................................................................................................ 48 5.3. SQL quoted identifiers ...................................................................................................... 49 5.4. Modular mapping files ...................................................................................................... 50 5.5. Generated Properties ........................................................................................................ 50 5.6. Auxiliary Database Objects ............................................................................................... 50 6. Collection Mapping ................................................................................................................... 52 6.1. Persistent Collections ....................................................................................................... 52 6.2. Mapping a Collection ....................................................................................................... 53 6.3. Collections of Values and Many-To-Many Associations ..................................................... 54 6.4. One-To-Many Associations .............................................................................................. 56 6.5. Lazy Initialization ............................................................................................................ 57 6.6. Sorted Collections ............................................................................................................ 58 6.7. Using an ............................................................................................................. 59 6.8. Bidirectional Associations ................................................................................................ 59 6.9. Ternary Associations ........................................................................................................ 60 6.10. Heterogeneous Associations ............................................................................................ 61 6.11. Collection examples ....................................................................................................... 61 7. Component Mapping ................................................................................................................ 64 7.1. Dependent objects ............................................................................................................ 64 7.2. Collections of dependent objects ....................................................................................... 65 7.3. Components as IDictionary indices .................................................................................... 66 7.4. Components as composite identifiers ................................................................................. 66 7.5. Dynamic components ....................................................................................................... 68 8. Inheritance Mapping ................................................................................................................. 69 8.1. The Three Strategies ......................................................................................................... 69 8.1.1. Table per class hierarchy ........................................................................................ 69 8.1.2. Table per subclass ................................................................................................. 70 8.1.3. Table per subclass, using a discriminator ................................................................. 70 8.1.4. Mixing table per class hierarchy with table per subclass ........................................... 71 8.1.5. Table per concrete class ......................................................................................... 71 8.1.6. Table per concrete class, using implicit polymorphism ............................................. 72 8.1.7. Mixing implicit polymorphism with other inheritance mappings ............................... 72

NHibernate 2.1.0

iii

NHibernate - Relational Persistence for Idiomatic .NET 8.2. Limitations ...................................................................................................................... 73 9. Manipulating Persistent Data .................................................................................................... 75 9.1. Creating a persistent object ............................................................................................... 75 9.2. Loading an object ............................................................................................................. 75 9.3. Querying ......................................................................................................................... 76 9.3.1. Scalar queries ........................................................................................................ 77 9.3.2. The IQuery interface .............................................................................................. 78 9.3.3. Filtering collections ............................................................................................... 79 9.3.4. Criteria queries ...................................................................................................... 79 9.3.5. Queries in native SQL ............................................................................................ 79 9.4. Updating objects .............................................................................................................. 80 9.4.1. Updating in the same ISession ................................................................................ 80 9.4.2. Updating detached objects ...................................................................................... 80 9.4.3. Reattaching detached objects .................................................................................. 81 9.5. Deleting persistent objects ................................................................................................ 82 9.6. Flush ............................................................................................................................... 82 9.7. Ending a Session .............................................................................................................. 83 9.7.1. Flushing the Session .............................................................................................. 83 9.7.2. Committing the database transaction ....................................................................... 83 9.7.3. Closing the ISession .............................................................................................. 83 9.8. Exception handling ........................................................................................................... 84 9.9. Lifecyles and object graphs ............................................................................................... 84 9.10. Interceptors .................................................................................................................... 85 9.11. Metadata API ................................................................................................................. 87 10. Transactions And Concurrency ............................................................................................... 88 10.1. Configurations, Sessions and Factories ............................................................................ 88 10.2. Threads and connections ................................................................................................. 88 10.3. Considering object identity ............................................................................................. 88 10.4. Optimistic concurrency control ........................................................................................ 89 10.4.1. Long session with automatic versioning ................................................................ 89 10.4.2. Many sessions with automatic versioning .............................................................. 89 10.4.3. Customizing automatic versioning ........................................................................ 90 10.4.4. Application version checking ............................................................................... 90 10.5. Session disconnection ..................................................................................................... 91 10.6. Pessimistic Locking ........................................................................................................ 92 10.7. Connection Release Modes ............................................................................................. 93 11. Interceptors and events ........................................................................................................... 94 11.1. Interceptors .................................................................................................................... 94 11.2. Event system .................................................................................................................. 95 12. Batch processing ...................................................................................................................... 97 12.1. Batch inserts .................................................................................................................. 97 12.2. The StatelessSession interface ......................................................................................... 97 12.3. DML-style operations ..................................................................................................... 98 13. HQL: The Hibernate Query Language .................................................................................. 101 13.1. Case Sensitivity ............................................................................................................ 101 13.2. The from clause ............................................................................................................ 101 13.3. Associations and joins .................................................................................................. 101 13.4. The select clause .......................................................................................................... 102 13.5. Aggregate functions ..................................................................................................... 103 13.6. Polymorphic queries ..................................................................................................... 103 13.7. The where clause .......................................................................................................... 104 13.8. Expressions .................................................................................................................. 105

NHibernate 2.1.0

iv

NHibernate - Relational Persistence for Idiomatic .NET 13.9. The order by clause ...................................................................................................... 107 13.10. The group by clause .................................................................................................... 108 13.11. Subqueries ................................................................................................................. 108 13.12. HQL examples ........................................................................................................... 109 13.13. Tips & Tricks ............................................................................................................. 110 14. Criteria Queries .................................................................................................................... 112 14.1. Creating an ICriteria instance ........................................................................................ 112 14.2. Narrowing the result set ................................................................................................ 112 14.3. Ordering the results ...................................................................................................... 113 14.4. Associations ................................................................................................................. 113 14.5. Dynamic association fetching ........................................................................................ 113 14.6. Example queries ........................................................................................................... 114 14.7. Projections, aggregation and grouping ........................................................................... 114 14.8. Detached queries and subqueries ................................................................................... 115 15. Native SQL ............................................................................................................................ 117 15.1. Using an ISQLQuery .................................................................................................... 117 15.1.1. Scalar queries .................................................................................................... 117 15.1.2. Entity queries .................................................................................................... 117 15.1.3. Handling associations and collections ................................................................. 118 15.1.4. Returning multiple entities ................................................................................. 118 15.1.4.1. Alias and property references ................................................................... 119 15.1.5. Returning non-managed entities .......................................................................... 120 15.1.6. Handling inheritance .......................................................................................... 120 15.1.7. Parameters ........................................................................................................ 120 15.2. Named SQL queries ..................................................................................................... 120 15.2.1. Using return-property to explicitly specify column/alias names ............................. 122 15.2.2. Using stored procedures for querying .................................................................. 122 15.2.2.1. Rules/limitations for using stored procedures ............................................ 123 15.3. Custom SQL for create, update and delete ...................................................................... 123 15.4. Custom SQL for loading ............................................................................................... 124 16. Filtering data ......................................................................................................................... 126 16.1. NHibernate filters ......................................................................................................... 126 17. Improving performance ........................................................................................................ 128 17.1. Fetching strategies ........................................................................................................ 128 17.1.1. Working with lazy associations .......................................................................... 128 17.1.2. Tuning fetch strategies ....................................................................................... 129 17.1.3. Single-ended association proxies ........................................................................ 130 17.1.4. Initializing collections and proxies ...................................................................... 131 17.1.5. Using batch fetching .......................................................................................... 132 17.1.6. Using subselect fetching ..................................................................................... 133 17.2. The Second Level Cache ............................................................................................... 133 17.2.1. Cache mappings ................................................................................................ 133 17.2.2. Strategy: read only ............................................................................................. 134 17.2.3. Strategy: read/write ............................................................................................ 134 17.2.4. Strategy: nonstrict read/write .............................................................................. 134 17.3. Managing the caches .................................................................................................... 135 17.4. The Query Cache ......................................................................................................... 135 17.5. Understanding Collection performance .......................................................................... 136 17.5.1. Taxonomy ......................................................................................................... 136 17.5.2. Lists, maps, idbags and sets are the most efficient collections to update ................. 137 17.5.3. Bags and lists are the most efficient inverse collections ........................................ 137 17.5.4. One shot delete .................................................................................................. 137

NHibernate 2.1.0

v

NHibernate - Relational Persistence for Idiomatic .NET 17.6. Batch updates ............................................................................................................... 138 17.7. Multi Query ................................................................................................................. 138 17.8. Multi Criteria ............................................................................................................... 139 18. Toolset Guide ........................................................................................................................ 141 18.1. Schema Generation ....................................................................................................... 141 18.1.1. Customizing the schema ..................................................................................... 141 18.1.2. Running the tool ................................................................................................ 142 18.1.3. Properties .......................................................................................................... 143 18.1.4. Using Ant ......................................................................................................... 143 18.2. Code Generation .......................................................................................................... 144 18.2.1. The config file (optional) ................................................................................... 144 18.2.2. The meta attribute .............................................................................................. 145 18.2.3. Basic finder generator ........................................................................................ 147 18.2.4. Velocity based renderer/generator ....................................................................... 148 18.3. Mapping File Generation .............................................................................................. 148 18.3.1. Running the tool ................................................................................................ 149 19. Example: Parent/Child .......................................................................................................... 151 19.1. A note about collections ................................................................................................ 151 19.2. Bidirectional one-to-many ............................................................................................. 151 19.3. Cascading lifecycle ....................................................................................................... 152 19.4. Using cascading Update() ............................................................................................. 153 19.5. Conclusion ................................................................................................................... 155 20. Example: Weblog Application ............................................................................................... 156 20.1. Persistent Classes ......................................................................................................... 156 20.2. Hibernate Mappings ..................................................................................................... 157 20.3. NHibernate Code .......................................................................................................... 158 21. Example: Various Mappings ................................................................................................. 161 21.1. Employer/Employee ..................................................................................................... 161 21.2. Author/Work ................................................................................................................ 162 21.3. Customer/Order/Product ............................................................................................... 164 22. Best Practices ........................................................................................................................ 167 I. NHibernateContrib Documentation ............................................................................................. 169 Preface ................................................................................................................................ clxx 23. NHibernate.Caches ....................................................................................................... 171 23.1. How to use a cache? ............................................................................................. 171 23.2. Prevalence Cache Configuration ............................................................................ 172 23.3. SysCache Configuration ....................................................................................... 172 23.4. SysCache2 Configuration ...................................................................................... 173 23.4.1. Table-based Dependency ........................................................................... 173 23.4.2. Command-Based Dependencies .................................................................. 174 23.4.3. Aggregate Dependencies ............................................................................ 175 23.4.4. Additional Settings .................................................................................... 176 23.4.5. Patches ..................................................................................................... 176 24. NHibernate.Mapping.Attributes ................................................................................... 177 24.1. What's new? ......................................................................................................... 177 24.2. How to use it? ...................................................................................................... 178 24.3. Tips ..................................................................................................................... 179 24.4. Know issues and TODOs ...................................................................................... 181 24.5. Developer Notes ................................................................................................... 181

NHibernate 2.1.0

vi

Preface Working with object-oriented software and a relational database can be cumbersome and time consuming in today's enterprise environments. NHibernate is an object/relational mapping tool for .NET environments. The term object/relational mapping (ORM) refers to the technique of mapping a data representation from an object model to a relational data model with a SQL-based schema. NHibernate not only takes care of the mapping from .NET classes to database tables (and from .NET data types to SQL data types), but also provides data query and retrieval facilities and can significantly reduce development time otherwise spent with manual data handling in SQL and ADO.NET. NHibernate's goal is to relieve the developer from 95 percent of common data persistence related programming tasks. NHibernate may not be the best solution for data-centric applications that only use stored-procedures to implement the business logic in the database, it is most useful with object-oriented domain models and business logic in the .NET-based middle-tier. However, NHibernate can certainly help you to remove or encapsulate vendor-specific SQL code and will help with the common task of result set translation from a tabular representation to a graph of objects. If you are new to NHibernate and Object/Relational Mapping or even .NET Framework, please follow these steps: 1.

Read Chapter 1, Quickstart with IIS and Microsoft SQL Server for a 30 minute tutorial, using Internet Information Services (IIS) web server.

2.

Read Chapter 2, Architecture to understand the environments where NHibernate can be used.

3.

Use this reference documentation as your primary source of information. Consider reading Hibernate in Action (http://www.manning.com/bauer/) or the work-in-progress NHibernate in Action (http://www.manning.com/kuate/) if you need more help with application design or if you prefer a stepby-step tutorial. Also visit http://nhibernate.sourceforge.net/NHibernateEg/ for NHibernate tutorial with examples.

4.

FAQs are answered on the NHibernate website [http://www.nhibernate.org/].

5.

Third party demos, examples and tutorials are linked on the NHibernate Resources page [http://www.hibernate.org/365.html].

6.

The Community Area on the NHibernate website is a good source for design patterns and various integration solutions (ASP.NET, Windows Forms).

If you have questions, use the NHibernate user forum [http://forum.hibernate.org/viewforum.php?f=25]. We also provide a JIRA issue trackings system [http://jira.nhibernate.org/] for bug reports and feature requests. If you are interested in the development of NHibernate, join the developer mailing list. If you are interested in translating this documentation into your language, contact us on the developer mailing list [http://sourceforge.net/mail/?group_id=29446].

NHibernate 2.1.0

vii

Chapter 1. Quickstart with IIS and Microsoft SQL Server 1.1. Getting started with NHibernate This tutorial explains a setup of NHibernate 2.1.0 within a Microsoft environment. The tools used in this tutorial are: 1.

Microsoft Internet Information Services (IIS) - web server supporting ASP.NET.

2.

Microsoft SQL Server 2005 - the database server. This tutorial uses the desktop edition (SQL-EXPRESS), a free download from Microsoft. Support for other databases is only a matter of changing the NHibernate SQL dialect and driver configuration.

3.

Microsoft Visual Studio .NET (at leats 2005) - the development environment.

First, we have to create a new Web project. We use the name QuickStart, the project web virtual directory will http://localhost/QuickStart. In the project, add a reference to NHibernate.dll. Visual Studio will automatically copy the library and its dependencies to the project output directory. If you are using a database other than SQL Server, add a reference to the driver assembly to your project. We now set up the database connection information for NHibernate. To do this, open the file Web.config automatically generated for your project and add configuration elements according to the listing below:

NHibernate.Dialect.MsSql2005Dialect NHibernate.Connection.DriverConnectionProviderServer=localhost\SQLEXPRESS;initial catalog= NHibernate.ByteCode.LinFu.ProxyFactoryFactory, ...

The element contains definitions of sections that follow and handlers to use to process their content. We declare the handler for the configuration section here. The section contains the configuration itself, telling NHibernate that we will use a Microsoft SQL Server 2000 database and connect to it through the specified connection string. The dialect is a required setting, databases differ in their NHibernate 2.1.0

1

Quickstart with IIS and Microsoft SQL Server interpretation of the SQL "standard". NHibernate will take care of the differences and comes bundled with dialects for several major commercial and open source databases. An ISessionFactory is NHibernate's concept of a single datastore, multiple databases can be used by creating multiple XML configuration files and creating multiple Configuration and ISessionFactory objects in your application. The last element of the section declares QuickStart as the name of an assembly containing class declarations and mapping files. The mapping files contain the metadata for the mapping of the POCO class to a database table (or multiple tables). We'll come back to mapping files soon. Let's write the POCO class first and then declare the mapping metadata for it.

1.2. First persistent class NHibernate works best with the Plain Old CLR Objects (POCOs, sometimes called Plain Ordinary CLR Objects) programming model for persistent classes. A POCO has its data accessible through the standard .NET property mechanisms, shielding the internal representation from the publicly visible interface: namespace QuickStart { public class Cat { private string private string private char private float

id; name; sex; weight;

public Cat() { } public virtual string Id { get { return id; } set { id = value; } } public virtual string Name { get { return name; } set { name = value; } } public virtual char Sex { get { return sex; } set { sex = value; } } public virtual float Weight { get { return weight; } set { weight = value; } } } }

NHibernate is not restricted in its usage of property types, all .NET types and primitives (like string, char and DateTime) can be mapped, including classes from the System.Collections namespace. You can map them as values, collections of values, or associations to other entities. The Id is a special property that represents the database identifier (primary key) of that class, it is highly recommended for entities like a Cat. NHibernate can use identifiers only internally, without having to declare them on the class, but we would lose some of the flexNHibernate 2.1.0

2

Quickstart with IIS and Microsoft SQL Server ibility in our application architecture. No special interface has to be implemented for persistent classes nor do we have to subclass from a special root persistent class. NHibernate also doesn't use any build time processing, such as IL manipulation, it relies solely on .NET reflection and runtime class enhancement (through Castle.DynamicProxy library). So, without any dependency in the POCO class on NHibernate, we can map it to a database table. For the above mentioned runtime class enhancement to work, NHibernate requires that all public properties of an entity class are declared as virtual.

1.3. Mapping the cat The Cat.hbm.xml mapping file contains the metadata required for the object/relational mapping. The metadata includes declaration of persistent classes and the mapping of properties (to columns and foreign key relationships to other entities) to database tables. Please note that the Cat.hbm.xml should be set to an embedded resource.

Every persistent class should have an identifer attribute (actually, only classes representing entities, not dependent value objects, which are mapped as components of an entity). This property is used to distinguish persistent objects: Two cats are equal if catA.Id.Equals(catB.Id) is true, this concept is called database identity. NHibernate comes bundled with various identifer generators for different scenarios (including native generators for database sequences, hi/lo identifier tables, and application assigned identifiers). We use the UUID generator (only recommended for testing, as integer surrogate keys generated by the database should be prefered) and also specify the column CatId of the table Cat for the NHibernate generated identifier value (as a primary key of the table). All other properties of Cat are mapped to the same table. In the case of the Name property, we mapped it with an explicit database column declaration. This is especially useful when the database schema is automatically generated (as SQL DDL statements) from the mapping declaration with NHibernate's SchemaExport tool. All other properties are mapped using NHibernate's default settings, which is what you need most of the time. The table Cat in the database looks like this: Column | Type | Modifiers --------+--------------+---------------------CatId | char(32) | not null, primary key

NHibernate 2.1.0

3

Quickstart with IIS and Microsoft SQL Server

Name | nvarchar(16) | not null Sex | nchar(1) | Weight | real |

You should now create the database and this table manually, and later read Chapter 18, Toolset Guide if you want to automate this step with the SchemaExport tool. This tool can create a full SQL DDL, including table definition, custom column type constraints, unique constraints and indexes. If you are using SQL Server, you should also make sure the ASPNET user has permissions to use the database.

1.4. Playing with cats We're now ready to start NHibernate's ISession. It is the persistence manager interface, we use it to store and retrieve Cats to and from the database. But first, we've to get an ISession (NHibernate's unit-of-work) from the ISessionFactory: ISessionFactory sessionFactory = new Configuration().Configure().BuildSessionFactory();

An ISessionFactory is responsible for one database and may only use one XML configuration file (Web.config or hibernate.cfg.xml). You can set other properties (and even change the mapping metadata) by accessing the Configuration before you build the ISessionFactory (it is immutable). Where do we create the ISessionFactory and how can we access it in our application? An ISessionFactory is usually only built once, e.g. at startup inside Application_Start event handler. This also means you should not keep it in an instance variable in your ASP.NET pages, but in some other location. Furthermore, we need some kind of Singleton, so we can access the ISessionFactory easily in application code. The approach shown next solves both problems: configuration and easy access to a ISessionFactory. We implement a NHibernateHelper helper class: using using using using

System; System.Web; NHibernate; NHibernate.Cfg;

namespace QuickStart { public sealed class NHibernateHelper { private const string CurrentSessionKey = "nhibernate.current_session"; private static readonly ISessionFactory sessionFactory; static NHibernateHelper() { sessionFactory = new Configuration().Configure().BuildSessionFactory(); } public static ISession GetCurrentSession() { HttpContext context = HttpContext.Current; ISession currentSession = context.Items[CurrentSessionKey] as ISession; if (currentSession == null) { currentSession = sessionFactory.OpenSession(); context.Items[CurrentSessionKey] = currentSession; } return currentSession; }

NHibernate 2.1.0

4

Quickstart with IIS and Microsoft SQL Server

public static void CloseSession() { HttpContext context = HttpContext.Current; ISession currentSession = context.Items[CurrentSessionKey] as ISession; if (currentSession == null) { // No current session return; } currentSession.Close(); context.Items.Remove(CurrentSessionKey); } public static void CloseSessionFactory() { if (sessionFactory != null) { sessionFactory.Close(); } } } }

This class does not only take care of the ISessionFactory with its static attribute, but also has code to remember the ISession for the current HTTP request. An ISessionFactory is threadsafe, many threads can access it concurrently and request ISessions. An ISession is a non-threadsafe object that represents a single unit-of-work with the database. ISessions are opened by an ISessionFactory and are closed when all work is completed: ISession session = NHibernateHelper.GetCurrentSession(); ITransaction tx = session.BeginTransaction(); Cat princess = new Cat(); princess.Name = "Princess"; princess.Sex = 'F'; princess.Weight = 7.4f; session.Save(princess); tx.Commit(); NHibernateHelper.CloseSession();

In an ISession, every database operation occurs inside a transaction that isolates the database operations (even read-only operations). We use NHibernate's ITransaction API to abstract from the underlying transaction strategy (in our case, ADO.NET transactions). Please note that the example above does not handle any exceptions. Also note that you may call NHibernateHelper.GetCurrentSession(); as many times as you like, you will always get the current ISession of this HTTP request. You have to make sure the ISession is closed after your unit-of-work completes, either in Application_EndRequest event handler in your application class or in a HttpModule before the HTTP response is sent. The nice side effect of the latter is easy lazy initialization: the ISession is still open when the view is rendered, so NHibernate can load unitialized objects while you navigate the graph. NHibernate has various methods that can be used to retrieve objects from the database. The most flexible way is using the Hibernate Query Language (HQL), which is an easy to learn and powerful object-oriented extension to SQL:

NHibernate 2.1.0

5

Quickstart with IIS and Microsoft SQL Server

ITransaction tx = session.BeginTransaction(); IQuery query = session.CreateQuery("select c from Cat as c where c.Sex = :sex"); query.SetCharacter("sex", 'F'); foreach (Cat cat in query.Enumerable()) { Console.Out.WriteLine("Female Cat: " + cat.Name); } tx.Commit();

NHibernate also offers an object-oriented query by criteria API that can be used to formulate type-safe queries. NHibernate of course uses IDbCommands and parameter binding for all SQL communication with the database. You may also use NHibernate's direct SQL query feature or get a plain ADO.NET connection from an ISession in rare cases.

1.5. Finally We only scratched the surface of NHibernate in this small tutorial. Please note that we don't include any ASP.NET specific code in our examples. You have to create an ASP.NET page yourself and insert the NHibernate code as you see fit. Keep in mind that NHibernate, as a data access layer, is tightly integrated into your application. Usually, all other layers depend on the persistence mechanism. Make sure you understand the implications of this design.

NHibernate 2.1.0

6

Chapter 2. Architecture 2.1. Overview A (very) high-level view of the NHibernate architecture:

This diagram shows NHibernate using the database and configuration data to provide persistence services (and persistent objects) to the application. We would like to show a more detailed view of the runtime architecture. Unfortunately, NHibernate is flexible and supports several approaches. We will show the two extremes. The "lite" architecture has the application provide its own ADO.NET connections and manage its own transactions. This approach uses a minimal subset of NHibernate's APIs:

NHibernate 2.1.0

7

Architecture

The "full cream" architecture abstracts the application away from the underlying ADO.NET APIs and lets NHibernate take care of the details.

Heres some definitions of the objects in the diagrams: ISessionFactory (NHibernate.ISessionFactory) A threadsafe (immutable) cache of compiled mappings for a single database. A factory for ISession and a client of IConnectionProvider. Might hold an optional (second-level) cache of data that is reusable NHibernate 2.1.0

8

Architecture between transactions, at a process- or cluster-level. ISession (NHibernate.ISession) A single-threaded, short-lived object representing a conversation between the application and the persistent store. Wraps an ADO.NET connection. Factory for ITransaction. Holds a mandatory (first-level) cache of persistent objects, used when navigating the object graph or looking up objects by identifier. Persistent Objects and Collections Short-lived, single threaded objects containing persistent state and business function. These might be ordinary POCOs, the only special thing about them is that they are currently associated with (exactly one) ISession. As soon as the Session is closed, they will be detached and free to use in any application layer (e.g. directly as data transfer objects to and from presentation). Transient Objects and Collections Instances of persistent classes that are not currently associated with a ISession. They may have been instantiated by the application and not (yet) persisted or they may have been instantiated by a closed ISession. ITransaction (NHibernate.ITransaction) (Optional) A single-threaded, short-lived object used by the application to specify atomic units of work. Abstracts application from underlying ADO.NET transaction. An ISession might span several ITransactions in some cases. IConnectionProvider (NHibernate.Connection.IConnectionProvider) (Optional) A factory for ADO.NET connections and commands. Abstracts application from the concrete vendor-specific implementations of IDbConnection and IDbCommand. Not exposed to application, but can be extended/implemented by the developer. IDriver (NHibernate.Driver.IDriver) (Optional) An interface encapsulating differences between ADO.NET providers, such as parameter naming conventions and supported ADO.NET features. ITransactionFactory (NHibernate.Transaction.ITransactionFactory) (Optional) A factory for ITransaction instances. Not exposed to the application, but can be extended/ implemented by the developer. Given a "lite" architecture, the application bypasses the ITransaction/ITransactionFactory and/or IConnectionProvider APIs to talk to ADO.NET directly.

2.2. Instance states An instance of a persistent classes may be in one of three different states, which are defined with respect to a persistence context. The NHibernate ISession object is the persistence context: transient The instance is not, and has never been associated with any persistence context. It has no persistent identity (primary key value). persistent The instance is currently associated with a persistence context. It has a persistent identity (primary key value) and, perhaps, a corresponding row in the database. For a particular persistence context, NHibernate guarantees that persistent identity is equivalent to CLR identity (in-memory location of the object).

NHibernate 2.1.0

9

Architecture

detached The instance was once associated with a persistence context, but that context was closed, or the instance was serialized to another process. It has a persistent identity and, perhaps, a corrsponding row in the database. For detached instances, NHibernate makes no guarantees about the relationship between persistent identity and CLR identity.

2.3. Contextual Sessions Most applications using NHibernate need some form of "contextual" sessions, where a given session is in effect throughout the scope of a given context. However, across applications the definition of what constitutes a context is typically different; and different contexts define different scopes to the notion of current. Starting with version 1.2, NHibernate added the ISessionFactory.GetCurrentSession() method. The processing behind ISessionFactory.GetCurrentSession() is pluggable. An extension interface (NHibernate.Context.ICurrentSessionContext) and a new configuration parameter (hibernate.current_session_context_class) have been added to allow pluggability of the scope and context of defining current sessions. See the API documentation for the NHibernate.Context.ICurrentSessionContext interface for a detailed discussion of its contract. It defines a single method, CurrentSession(), by which the implementation is responsible for tracking the current contextual session. Out-of-the-box, NHibernate 1.2.1 comes with several implementations of this interface: •

NHibernate.Context.ManagedWebSessionContext

- current sessions are tracked by HttpContext. However, you are responsible to bind and unbind an ISession instance with static methods on this class, it never opens, flushes, or closes an ISession itself.

•

NHibernate.Context.CallSessionContext

•

NHibernate.Context.ThreadStaticSessionContext

•

NHibernate.Context.WebSessionContext

- current sessions are tracked by CallContext. You are responsible to bind and unbind an ISession instance with static methods of class CurrentSessionContext . - current session is stored in a thread-static variable. This context only supports one session factory. You are responsible to bind and unbind an ISession instance with static methods of class CurrentSessionContext. - analogous to ManagedWebSessionContext above, stores the current session in HttpContext. You are responsible to bind and unbind an ISession instance with static methods of class CurrentSessionContext.

The

configuration parameter defines which NHibernate.Context.ICurrentSessionContext implementation should be used. Typically, the value of this parameter would just name the implementation class to use (including the assembly name); for the out-of-the-box implementations, however, there are corresponding short names: "managed_web", "call", "thread_static", and "web", respectively. hibernate.current_session_context_class

NHibernate 2.1.0

10

Chapter 3. ISessionFactory Configuration Because NHibernate is designed to operate in many different environments, there are a large number of configuration parameters. Fortunately, most have sensible default values and NHibernate is distributed with an example App.config file (found in src\NHibernate.Test) that shows the various options. You usually only have to put that file in your project and customize it.

3.1. Programmatic Configuration An instance of NHibernate.Cfg.Configuration represents an entire set of mappings of an application's .NET types to a SQL database. The Configuration is used to build an (immutable) ISessionFactory. The mappings are compiled from various XML mapping files. You may obtain a Configuration instance by instantiating it directly. Heres an example of setting up a datastore from mappings defined in two XML configuration files: Configuration cfg = new Configuration() .AddFile("Item.hbm.xml") .AddFile("Bid.hbm.xml");

An alternative (sometimes better) way is to let NHibernate load a mapping file from an embedded resource: Configuration cfg = new Configuration() .AddClass(typeof(NHibernate.Auction.Item)) .AddClass(typeof(NHibernate.Auction.Bid));

Then NHibernate will look for mapping files named NHibernate.Auction.Item.hbm.xml and NHibernate.Auction.Bid.hbm.xml embedded as resources in the assembly that the types are contained in. This approach eliminates any hardcoded filenames. Another alternative (probably the best) way is to let NHibernate load all of the mapping files contained in an Assembly: Configuration cfg = new Configuration() .AddAssembly( "NHibernate.Auction" );

Then NHibernate will look through the assembly for any resources that end with .hbm.xml. This approach eliminates any hardcoded filenames and ensures the mapping files in the assembly get added. If a tool like Visual Studio .NET or NAnt is used to build the assembly, then make sure that the .hbm.xml files are compiled into the assembly as Embedded Resources. A Configuration also specifies various optional properties: IDictionary props = new Hashtable(); ... Configuration cfg = new Configuration() .AddClass(typeof(NHibernate.Auction.Item)) .AddClass(typeof(NHibernate.Auction.Bind)) .SetProperties(props);

A Configuration is intended as a configuration-time object, to be discarded once an ISessionFactory is built.

NHibernate 2.1.0

11

ISessionFactory Configuration

3.2. Obtaining an ISessionFactory When all mappings have been parsed by the Configuration, the application must obtain a factory for ISession instances. This factory is intended to be shared by all application threads: ISessionFactory sessions = cfg.BuildSessionFactory();

However, NHibernate does allow your application to instantiate more than one ISessionFactory. This is useful if you are using more than one database.

3.3. User provided ADO.NET connection An ISessionFactory may open an ISession on a user-provided ADO.NET connection. This design choice frees the application to obtain ADO.NET connections wherever it pleases: IDbConnection conn = myApp.GetOpenConnection(); ISession session = sessions.OpenSession(conn); // do some data access work

The application must be careful not to open two concurrent ISessions on the same ADO.NET connection!

3.4. NHibernate provided ADO.NET connection Alternatively, you can have the ISessionFactory open connections for you. The ISessionFactory must be provided with ADO.NET connection properties in one of the following ways: 1. 2. 3.

4.

Pass an instance of IDictionary mapping property names to property values to Configuration.SetProperties(). Add the properties to a configuration section in the application configuration file. The section should be named nhibernate and its handler set to System.Configuration.NameValueSectionHandler. Include elements in a configuration section in the application configuration file. The section should be named hibernate-configuration and its handler set to NHibernate.Cfg.ConfigurationSectionHandler. The XML namespace of the section should be set to urn:nhibernate-configuration-2.2. Include elements in hibernate.cfg.xml (discussed later).

If you take this approach, opening an ISession is as simple as: ISession session = sessions.OpenSession(); // open a new Session // do some data access work, an ADO.NET connection will be used on demand

All NHibernate property names and semantics are defined on the class NHibernate.Cfg.Environment. We will now describe the most important settings for ADO.NET connection configuration. NHibernate will obtain (and pool) connections using an ADO.NET data provider if you set the following properties: Table 3.1. NHibernate ADO.NET Properties

NHibernate 2.1.0

12

ISessionFactory Configuration Property name

Purpose

connection.provider_class

The type of a custom IConnectionProvider. eg. full.classname.of.ConnectionProvider if the Provider is built into NHibernate, or full.classname.of.ConnectionProvider,

as-

if using an implementation of IConnectionProvider not included in NHibernate. sembly

connection.driver_class

The type of a custom IDriver, if using DriverConnectionProvider. full.classname.of.Driver

if the Driver is built into

NHibernate, or full.classname.of.Driver, assembly if using an implementation of IDriver not included in NHibernate. This is usually not needed, most of the time the dialect will take care of setting the IDriver using a sensible default. See the API documentation of the specific dialect for the defaults. connection.connection_string

Connection string to use to obtain the connection.

connection.connection_string_name

The name of the connection string (defined in configuration file element) to use to obtain the connection.

connection.isolation

Set the ADO.NET transaction isolation level. Check System.Data.IsolationLevel for meaningful values and the database's documentation to ensure that level is supported. eg. Chaos, ReadCommitted, ReadUncommitted, RepeatableRead, Serializable, Unspecified

connection.release_mode

Specify when NHibernate should release ADO.NET connections. See Section 10.7, “Connection Release Modes”. eg. auto (default) | on_close | after_transaction Note that this setting only affects ISessions returned from ISessionFactory.OpenSession. For ISessions obtained through ISessionFactory.GetCurrentSession, the ICurrentSessionContext implementation configured for use controls the connection release mode for those ISessions. See Section 2.3, “Contextual Sessions”.

command_timeout

Specify the default timeout of IDbCommands generated by NHibernate.

adonet.batch_size

Specify the batch size to use when batching update statements. Setting this to 0 (the default) disables the functionality. See Section 17.6, “Batch updates”.

NHibernate 2.1.0

13

ISessionFactory Configuration

This is an example of how to specify the database connection properties inside a web.config:

NHibernate.Dialect.MsSql2005Dialect Server=(local);initial catalog=theDb;Integrated Security=SSPI ReadCommitted

NHibernate.ByteCode.LinFu.ProxyFactoryFactory, NHibernate.ByteCode.Lin

NHibernate relies on the ADO.NET data provider implementation of connection pooling. You may define your own plugin strategy for obtaining ADO.NET connections by implementing the interface NHibernate.Connection.IConnectionProvider. You may select a custom implementation by setting connection.provider_class.

3.5. Optional configuration properties There are a number of other properties that control the behaviour of NHibernate at runtime. All are optional and have reasonable default values. System-level properties can only be set manually by setting static properties of NHibernate.Cfg.Environment class or be defined in the section of the application configuration file. These properties cannot be set using Configuration.SetProperties or be defined in the section of the application configuration file. Table 3.2. NHibernate Configuration Properties Property name

Purpose

dialect

The classname of a NHibernate Dialect - enables certain platform dependent features. eg. full.classname.of.Dialect, assembly

default_schema

Qualify unqualified tablenames with the given schema/tablespace in generated SQL. eg. SCHEMA_NAME

use_outer_join

NHibernate 2.1.0

Enables

outer

join max_fetch_depth.

fetching.

Deprecated,

use

14

ISessionFactory Configuration Property name

Purpose eg. true | false

max_fetch_depth

Set a maximum "depth" for the outer join fetch tree for single-ended associations (one-to-one, manyto-one). A 0 disables default outer join fetching. eg. recommended values between 0 and 3

use_reflection_optimizer

Enables use of a runtime-generated class to set or get properties of an entity or component instead of using runtime reflection (System-level property). The use of the reflection optimizer inflicts a certain startup cost on the application but should lead to better performance in the long run. You can not set this property in hibernate.cfg.xml or section of the application configuration file. eg. true | false

bytecode.provider

Specifies the bytecode provider to use to optimize the use of reflection in NHibernate. Use null to disable the optimization completely, lcg to use lightweight code generation. eg. null | lcg

cache.provider_class

The classname of a custom ICacheProvider. eg. classname.of.CacheProvider, assembly

cache.use_minimal_puts

Optimize second-level cache operation to minimize writes, at the cost of more frequent reads (useful for clustered caches). eg. true | false

cache.use_query_cache

Enable the query cache, individual queries still have to be set cacheable. eg. true | false

cache.query_cache_factory

The classname of a custom IQueryCacheFactory interface, defaults to the built-in StandardQueryCacheFactory. eg. classname.of.QueryCacheFactory, assembly

cache.region_prefix

A prefix to use for second-level cache region names. eg. prefix

query.substitutions

Mapping from tokens in NHibernate queries to SQL tokens (tokens might be function or literal names, for example). eg.

NHibernate 2.1.0

hqlLiteral=SQL_LITERAL,

hqlFunc-

15

ISessionFactory Configuration Property name

Purpose tion=SQLFUNC

Write all SQL statements to console.

show_sql

eg. true | false Automatically export schema DDL to the database when the ISessionFactory is created. With createdrop, the database schema will be dropped when the ISessionFactory is closed explicitly.

hbm2ddl.auto

eg. create | create-drop Enables or disables validation of interfaces or classes specified as proxies. Enabled by default.

use_proxy_validator

eg. true | false The classname of a custom ITransactionFactory implementation, defaults to the built-in AdoNetTransactionFactory.

transaction.factory_class

eg. classname.of.TransactionFactory, assembly

3.5.1. SQL Dialects You should always set the dialect property to the correct NHibernate.Dialect.Dialect subclass for your database. This is not strictly essential unless you wish to use native or sequence primary key generation or pessimistic locking (with, eg. ISession.Lock() or IQuery.SetLockMode()). However, if you specify a dialect, NHibernate will use sensible defaults for some of the other properties listed above, saving you the effort of specifying them manually. Table 3.3. NHibernate SQL Dialects (dialect) RDBMS

Dialect

DB2

NHibernate.Dialect.DB2Dialect

DB2 for iSeries (OS/400)

NHibernate.Dialect.DB2400Dialect

Ingres

NHibernate.Dialect.IngresDialect

PostgreSQL

NHibernate.Dialect.PostgreSQLDialect

PostgreSQL 8.1

NHibernate.Dialect.PostgreSQL81Dialect

PostgreSQL 8.2

NHibernate.Dialect.PostgreSQL82Dialect

MySQL 3 or 4

NHibernate.Dialect.MySQLDialect

MySQL 5

NHibernate.Dialect.MySQL5Dialect

Oracle

NHibernate.Dialect.Oracle8iDialect

Oracle 9

NHibernate.Dialect.Oracle9iDialect

NHibernate 2.1.0

16

ISessionFactory Configuration RDBMS

Dialect

Oracle 10g

NHibernate.Dialect.Oracle10gDialect

Sybase Adaptive Server En- NHibernate.Dialect.SybaseDialect terprise Sybase Adaptive Server Any- NHibernate.Dialect.SybaseAnywhereDialect where Microsoft SQL Server 2000

NHibernate.Dialect.MsSql2000Dialect

Microsoft SQL Server 2005

NHibernate.Dialect.MsSql2005Dialect

Microsoft SQL Server 2005 NHibernate.Dialect.MsSqlCeDialect Everywhere Edition Microsoft SQL Server 7

NHibernate.Dialect.MsSql7Dialect

Firebird

NHibernate.Dialect.FirebirdDialect

SQLite

NHibernate.Dialect.SQLiteDialect

Ingres 3.0

NHibernate.Dialect.IngresDialect

Additional dialects may be available in the NHibernate.Dialect namespace.

3.5.2. Outer Join Fetching If your database supports ANSI or Oracle style outer joins, outer join fetching might increase performance by limiting the number of round trips to and from the database (at the cost of possibly more work performed by the database itself). Outer join fetching allows a graph of objects connected by many-to-one, one-to-many or oneto-one associations to be retrieved in a single SQL SELECT. By default, the fetched graph when loading an objects ends at leaf objects, collections, objects with proxies, or where circularities occur. For a particular association, fetching may be configured (and the default behaviour overridden) by setting the fetch attribute in the XML mapping. Outer join fetching may be disabled globally by setting the property max_fetch_depth to 0. A setting of 1 or higher enables outer join fetching for one-to-one and many-to-one associations which have been mapped with fetch="join". See Section 17.1, “Fetching strategies” for more information. In NHibernate 1.0, outer-join attribute could be used to achieve a similar effect. This attribute is now deprecated in favor of fetch.

3.5.3. Custom ICacheProvider You may integrate a process-level (or clustered) second-level cache system by implementing the interface NHibernate.Cache.ICacheProvider. You may select the custom implementation by setting cache.provider_class. See the Section 17.2, “The Second Level Cache” for more details.

NHibernate 2.1.0

17

ISessionFactory Configuration

3.5.4. Query Language Substitution You may define new NHibernate query tokens using query.substitutions. For example: query.substitutions true=1, false=0

would cause the tokens true and false to be translated to integer literals in the generated SQL. query.substitutions toLowercase=LOWER

would allow you to rename the SQL LOWER function.

3.6. Logging NHibernate logs various events using Apache log4net. You may download log4net from http://logging.apache.org/log4net/. To use log4net you will need a log4net configuration section in the application configuration file. An example of the configuration section is distributed with NHibernate in the src/NHibernate.Test project. We strongly recommend that you familiarize yourself with NHibernate's log messages. A lot of work has been put into making the NHibernate log as detailed as possible, without making it unreadable. It is an essential troubleshooting device. Also don't forget to enable SQL logging as described above (show_sql), it is your first step when looking for performance problems.

3.7. Implementing an INamingStrategy The interface NHibernate.Cfg.INamingStrategy allows you to specify a "naming standard" for database objects and schema elements. You may provide rules for automatically generating database identifiers from .NET identifiers or for processing "logical" column and table names given in the mapping file into "physical" table and column names. This feature helps reduce the verbosity of the mapping document, eliminating repetitive noise (TBL_ prefixes, for example). The default strategy used by NHibernate is quite minimal. You may specify a different strategy by calling Configuration.SetNamingStrategy() before adding mappings: ISessionFactory sf = new Configuration() .SetNamingStrategy(ImprovedNamingStrategy.Instance) .AddFile("Item.hbm.xml") .AddFile("Bid.hbm.xml") .BuildSessionFactory();

NHibernate.Cfg.ImprovedNamingStrategy

is a built-in strategy that might be a useful starting point for some

applications.

3.8. XML Configuration File An alternative approach is to specify a full configuration in a file named hibernate.cfg.xml. This file can be used as a replacement for the or sections of the application conNHibernate 2.1.0

18

ISessionFactory Configuration figuration file. The XML configuration file is by default expected to be in your application directory. Here is an example:

NHibernate.Connection.DriverConnectionProvider NHibernate.Driver.SqlClientDriver Server=localhost;initial catalog=nhibernate;User false NHibernate.Dialect.MsSql2000Dialect true

Configuring NHibernate is then as simple as ISessionFactory sf = new Configuration().Configure().BuildSessionFactory();

You can pick a different XML configuration file using ISessionFactory sf = new Configuration() .Configure("/path/to/config.cfg.xml") .BuildSessionFactory();

NHibernate 2.1.0

19

Chapter 4. Persistent Classes Persistent classes are classes in an application that implement the entities of the business problem (e.g. Customer and Order in an E-commerce application). Persistent classes have, as the name implies, transient and also persistent instance stored in the database. NHibernate works best if these classes follow some simple rules, also known as the Plain Old CLR Object (POCO) programming model.

4.1. A simple POCO example Most .NET applications require a persistent class representing felines. using System; using Iesi.Collections; namespace Eg { public class Cat { private long id; // identifier private string name; private DateTime birthdate; private Cat mate; private ISet kittens private Color color; private char sex; private float weight; public virtual long Id { get { return id; } set { id = value; } } public virtual string Name { get { return name; } set { name = value; } } public virtual Cat Mate { get { return mate; } set { mate = value; } } public virtual DateTime Birthdate { get { return birthdate; } set { birthdate = value; } } public virtual float Weight { get { return weight; } set { weight = value; } } public virtual Color Color { get { return color; } set { color = value; } }

NHibernate 2.1.0

20

Persistent Classes

public virtual ISet Kittens { get { return kittens; } set { kittens = value; } } // AddKitten not needed by NHibernate public virtual void AddKitten(Cat kitten) { kittens.Add(kitten); } public virtual char Sex { get { return sex; } set { sex = value; } } } }

There are four main rules to follow here:

4.1.1. Declare accessors and mutators for persistent fields declares accessor methods for all its persistent fields. Many other ORM tools directly persist instance variables. We believe it is far better to decouple this implementation detail from the persistence mechanism. NHibernate persists properties, using their getter and setter methods. Cat

Properties need not be declared public - NHibernate can persist a property with an internal, protected, protected internal or private visibility.

4.1.2. Implement a default constructor has an implicit default (no-argument) constructor. All persistent classes must have a default constructor (which may be non-public) so NHibernate can instantiate them using Activator.CreateInstance(). Cat

4.1.3. Provide an identifier property (optional) has a property called Id. This property holds the primary key column of a database table. The property might have been called anything, and its type might have been any primitive type, string or System.DateTime. (If your legacy database table has composite keys, you can even use a user-defined class with properties of these types - see the section on composite identifiers below.) Cat

The identifier property is optional. You can leave it off and let NHibernate keep track of object identifiers internally. However, for many applications it is still a good (and very popular) design decision. What's more, some functionality is available only to classes which declare an identifier property: • •

Cascaded updates (see "Lifecycle Objects") ISession.SaveOrUpdate()

We recommend you declare consistently-named identifier properties on persistent classes.

4.1.4. Prefer non-sealed classes and virtual methods (optional)

NHibernate 2.1.0

21

Persistent Classes

A central feature of NHibernate, proxies, depends upon the persistent class being non-sealed and all its public methods, properties and events declared as virtual. Another possibility is for the class to implement an interface that declares all public members. You can persist sealed classes that do not implement an interface and don't have virtual members with NHibernate, but you won't be able to use proxies - which will limit your options for performance tuning.

4.2. Implementing inheritance A subclass must also observe the first and second rules. It inherits its identifier property from Cat. using System; namespace Eg { public class DomesticCat : Cat { private string name; public virtual string Name { get { return name; } set { name = value; } } } }

4.3. Implementing Equals() and GetHashCode() You have to override the Equals() and GetHashCode() methods if you intend to mix objects of persistent classes (e.g. in an ISet). This only applies if these objects are loaded in two different ISessions, as NHibernate only guarantees identity ( a == b , the default implementation of Equals()) inside a single ISession! Even if both objecs a and b are the same database row (they have the same primary key value as their identifier), we can't guarantee that they are the same object instance outside of a particular ISession context. The most obvious way is to implement Equals()/GetHashCode() by comparing the identifier value of both objects. If the value is the same, both must be the same database row, they are therefore equal (if both are added to an ISet, we will only have one element in the ISet). Unfortunately, we can't use that approach. NHibernate will only assign identifier values to objects that are persistent, a newly created instance will not have any identifier value! We recommend implementing Equals() and GetHashCode() using Business key equality. Business key equality means that the Equals() method compares only the properties that form the business key, a key that would identify our instance in the real world (a natural candidate key): public class Cat { ... public override bool Equals(object other) { if (this == other) return true; Cat cat = other as Cat; if (cat == null) return false; // null or not a cat if (Name != cat.Name) return false;

NHibernate 2.1.0

22

Persistent Classes

if (!Birthday.Equals(cat.Birthday)) return false; return true; } public override int GetHashCode() { unchecked { int result; result = Name.GetHashCode(); result = 29 * result + Birthday.GetHashCode(); return result; } } }

Keep in mind that our candidate key (in this case a composite of name and birthday) has to be only valid for a particular comparison operation (maybe even only in a single use case). We don't need the stability criteria we usually apply to a real primary key!

4.4. Dynamic models Note that the following features are currently considered experimental and may change in the near future. Persistent entities don't necessarily have to be represented as POCO classes at runtime. NHibernate also supports dynamic models (using Dictionaries of Dictionarys at runtime) . With this approach, you don't write persistent classes, only mapping files. By default, NHibernate works in normal POCO mode. You may set a default entity representation mode for a particular ISessionFactory using the default_entity_mode configuration option (see Table 3.2, “NHibernate Configuration Properties”. The following examples demonstrates the representation using Maps (Dictionary). First, in the mapping file, an entity-name has to be declared instead of (or in addition to) a class name:

NHibernate 2.1.0

23

Persistent Classes



Note that even though associations are declared using target class names, the target type of an associations may also be a dynamic entity instead of a POCO. After setting the default entity mode to dynamic-map for the ISessionFactory, we can at runtime work with Dictionaries of Dictionaries: Session s = OpenSession(); Transaction tx = s.BeginTransaction(); ISession s = OpenSession(); // Create a customer var frank = new Dictionary(); frank["name"] = "Frank"; // Create an organization var foobar = new Dictionary(); foobar["name"] = "Foobar Inc."; // Link both frank["organization"] =

foobar;

// Save both s.Save("Customer", frank); s.Save("Organization", foobar); tx.Commit(); s.Close();

The advantages of a dynamic mapping are quick turnaround time for prototyping without the need for entity class implementation. However, you lose compile-time type checking and will very likely deal with many exceptions at runtime. Thanks to the NHibernate mapping, the database schema can easily be normalized and sound, allowing to add a proper domain model implementation on top later on. Entity representation modes can also be set on a per ISession basis: Session dynamicSession = pocoSession.GetSession(EntityMode.Map); // Create a customer var frank = new Dictionary(); frank["name"] = "Frank"; dynamicSession.Save("Customer", frank); ... dynamicSession.Flush(); dynamicSession.Close() ... // Continue on pocoSession

Please note that the call to GetSession() using an EntityMode is on the ISession API, not the ISessionFactory. That way, the new ISession shares the underlying ADO connection, transaction, and other context information. This means you don't have tocall Flush() and Close() on the secondary ISession, and also leave the transaction and connection handling to the primary unit of work.

4.5. Tuplizers NHibernate 2.1.0

24

Persistent Classes

NHibernate.Tuple.Tuplizer,

and its sub-interfaces, are responsible for managing a particular representation of a piece of data, given that representation's NHibernate.EntityMode. If a given piece of data is thought of as a data structure, then a tuplizer is the thing which knows how to create such a data structure and how to extract values from and inject values into such a data structure. For example, for the POCO entity mode, the correpsonding tuplizer knows how create the POCO through its constructor and how to access the POCO properties using the defined property accessors. There are two high-level types of Tuplizers, represented by the NHibernate.Tuple.Entity.IEntityTuplizer and NHibernate.Tuple.Component.IComponentTuplizer interfaces. IEntityTuplizers are responsible for managing the above mentioned contracts in regards to entities, while IComponentTuplizers do the same for components. Users may also plug in their own tuplizers. Perhaps you require that a System.Collections.IDictionary implementation other than System.Collections.Hashtable be used while in the dynamic-map entity-mode; or perhaps you need to define a different proxy generation strategy than the one used by default. Both would be achieved by defining a custom tuplizer implementation. Tuplizers definitions are attached to the entity or component mapping they are meant to manage. Going back to the example of our customer entity: ...

public class CustomMapTuplizerImpl: NHibernate.Tuple.Entity.DynamicMapEntityTuplizer { // override the BuildInstantiator() method to plug in our custom map... protected override IInstantiator BuildInstantiator( NHibernate.Mapping.PersistentClass mappingInfo) { return new CustomMapInstantiator( mappingInfo ); } private static final class CustomMapInstantiator: NHibernate.Tuple.DynamicMapInstantiator { // override the generateMap() method to return our custom map... protected override IDictionary GenerateMap() { return new CustomMap(); } } }

4.6. Lifecycle Callbacks Optionally, a persistent class might implement the interface ILifecycle which provides some callbacks that allow the persistent object to perform necessary initialization/cleanup after save or load and before deletion or update. The NHibernate IInterceptor offers a less intrusive alternative, however. public interface ILifecycle

NHibernate 2.1.0

25

Persistent Classes

{ LifecycleVeto OnSave(ISession s); LifecycleVeto OnUpdate(ISession s); LifecycleVeto OnDelete(ISession s); void OnLoad(ISession s, object id);

(1) (2) (3) (4)

}

- called just before the object is saved or inserted - called just before an object is updated (when the object is passed to ISession.Update()) OnDelete - called just before an object is deleted OnLoad - called just after an object is loaded

(1)

OnSave

(2)

OnUpdate

(3) (4)

OnSave(), OnDelete()

and OnUpdate() may be used to cascade saves and deletions of dependent objects. This is an alternative to declaring cascaded operations in the mapping file. OnLoad() may be used to initialize transient properties of the object from its persistent state. It may not be used to load dependent objects since the ISession interface may not be invoked from inside this method. A further intended usage of OnLoad(), OnSave() and OnUpdate() is to store a reference to the current ISession for later use. Note that OnUpdate() is not called every time the object's persistent state is updated. It is called only when a transient object is passed to ISession.Update(). If OnSave(), OnUpdate() or OnDelete() return LifecycleVeto.Veto, the operation is silently vetoed. If a CallbackException is thrown, the operation is vetoed and the exception is passed back to the application. Note that OnSave() is called after an identifier is assigned to the object, except when native key generation is used.

4.7. IValidatable callback If the persistent class needs to check invariants before its state is persisted, it may implement the following interface: public interface IValidatable { void Validate(); }

The object should throw a ValidationFailure if an invariant was violated. An instance of Validatable should not change its state from inside Validate(). Unlike the callback methods of the ILifecycle interface, Validate() might be called at unpredictable times. The application should not rely upon calls to Validate() for business functionality.

NHibernate 2.1.0

26

Chapter 5. Basic O/R Mapping 5.1. Mapping declaration Object/relational mappings are defined in an XML document. The mapping document is designed to be readable and hand-editable. The mapping language is object-centric, meaning that mappings are constructed around persistent class declarations, not table declarations. Note that, even though many NHibernate users choose to define XML mappings by hand, a number of tools exist to generate the mapping document, including NHibernate.Mapping.Attributes library and various templatebased code generators (CodeSmith, MyGeneration). Let's kick off with an example mapping:

We will now discuss the content of the mapping document. We will only describe the document elements and attributes that are used by NHibernate at runtime. The mapping document also contains some extra optional attributes and elements that affect the database schemas exported by the schema export tool. (For example the not-null attribute.)

5.1.1. XML Namespace All XML mappings should declare the XML namespace shown. The actual schema definition may be found in the src\nhibernate-mapping.xsd file in the NHibernate distribution. Tip: to enable IntelliSense for mapping and configuration files, copy the appropriate .xsd files to \Common7\Packages\schemas\xml if you are using Visual Studio .NET 2003, or to \Xml\Schemas for Visual Studio 2005.

NHibernate 2.1.0

27

Basic O/R Mapping

5.1.2. hibernate-mapping This element has several optional attributes. The schema attribute specifies that tables referred to by this mapping belong to the named schema. If specified, tablenames will be qualified by the given schema name. If missing, tablenames will be unqualified. The default-cascade attribute specifies what cascade style should be assumed for properties and collections which do not specify a cascade attribute. The auto-import attribute lets us use unqualified class names in the query language, by default. The assembly and namespace attributes specify the assembly where persistent classes are located and the namespace they are declared in.

(1) (2) (3)

( 5

(1) (2) (3) (4) (5)

(optional): The name of a database schema. default-cascade (optional - defaults to none): A default cascade style. auto-import (optional - defaults to true): Specifies whether we can use unqualified class names (of classes in this mapping) in the query language. assembly and namespace(optional): Specify assembly and namespace to assume for unqualified class names in the mapping document. schema

(4))

If you are not using assembly and namespace attributes, you have to specify fully-qualified class names, including the name of the assembly that classes are declared in. If you have two persistent classes with the same (unqualified) name, you should set auto-import="false". NHibernate will throw an exception if you attempt to assign two classes to the same "imported" name.

5.1.3. class You may declare a persistent class using the class element:
(1) (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16)

/>

(1)

(2) (3)

name:

The fully qualified .NET class name of the persistent class (or interface), including its assembly

name. table(optional - defaults to the unqualified class name): The name of its database table. discriminator-value (optional - defaults to the class name): A value that distiguishes individual subclasses, used for polymorphic behaviour. Acceptable values include null and not null.

NHibernate 2.1.0

28

Basic O/R Mapping (optional, defaults to true): Specifies that instances of the class are (not) mutable. (optional): Override the schema name specified by the root element. proxy (optional): Specifies an interface to use for lazy initializing proxies. You may specify the name of the class itself. dynamic-update (optional, defaults to false): Specifies that UPDATE SQL should be generated at runtime and contain only those columns whose values have changed. dynamic-insert (optional, defaults to false): Specifies that INSERT SQL should be generated at runtime and contain only the columns whose values are not null. select-before-update (optional, defaults to false): Specifies that NHibernate should never perform an SQL UPDATE unless it is certain that an object is actually modified. In certain cases (actually, only when a transient object has been associated with a new session using update()), this means that NHibernate will perform an extra SQL SELECT to determine if an UPDATE is actually required. polymorphism (optional, defaults to implicit): Determines whether implicit or explicit query polymorphism is used. where (optional) specify an arbitrary SQL WHERE condition to be used when retrieving objects of this class persister (optional): Specifies a custom IClassPersister. batch-size (optional, defaults to 1) specify a "batch size" for fetching instances of this class by identifier. optimistic-lock (optional, defaults to version): Determines the optimistic locking strategy. lazy (optional): Lazy fetching may be completely disabled by setting lazy="false". abstract (optional): Used to mark abstract superclasses in hierarchies.

(4)

mutable

(5)

schema

(6)

(7)

(8)

(9)

(10)

(11) (12) (13) (14) (15) (16)

It is perfectly acceptable for the named persistent class to be an interface. You would then declare implementing classes of that interface using the element. You may persist any inner class. You should specify the class name using the standard form ie. Eg.Foo+Bar, Eg. Due to an HQL parser limitation inner classes can not be used in queries in NHibernate 1.0. Immutable classes, mutable="false", may not be updated or deleted by the application. This allows NHibernate to make some minor performance optimizations. The optional proxy attribute enables lazy initialization of persistent instances of the class. NHibernate will initially return proxies which implement the named interface. The actual persistent object will be loaded when a method of the proxy is invoked. See "Proxies for Lazy Initialization" below. Implicit polymorphism means that instances of the class will be returned by a query that names any superclass or implemented interface or the class and that instances of any subclass of the class will be returned by a query that names the class itself. Explicit polymorphism means that class instances will be returned only be queries that explicitly name that class and that queries that name the class will return only instances of subclasses mapped inside this declaration as a or . For most purposes the default, polymorphism="implicit", is appropriate. Explicit polymorphism is useful when two different classes are mapped to the same table (this allows a "lightweight" class that contains a subset of the table columns). The persister attribute lets you customize the persistence strategy used for the class. You may, for example, specify your own subclass of NHibernate.Persister.EntityPersister or you might even provide a completely new implementation of the interface NHibernate.Persister.IClassPersister that implements persistence via, for example, stored procedure calls, serialization to flat files or LDAP. See NHibernate.DomainModel.CustomPersister for a simple example (of "persistence" to a Hashtable). Note that the dynamic-update and dynamic-insert settings are not inherited by subclasses and so may also be specified on the or elements. These settings may increase performance in some cases, but might actually decrease performance in others. Use judiciously. Use of select-before-update will usually decrease performance. It is very useful to prevent a database update trigger being called unnecessarily.

NHibernate 2.1.0

29

Basic O/R Mapping

If you enable dynamic-update, you will have a choice of optimistic locking strategies: •

version

•

all

•

dirty

•

none

check the version/timestamp columns

check all columns check the changed columns

do not use optimistic locking

We very strongly recommend that you use version/timestamp columns for optimistic locking with NHibernate. This is the optimal strategy with respect to performance and is the only strategy that correctly handles modifications made outside of the session (ie. when ISession.Update() is used). Keep in mind that a version or timestamp property should never be null, no matter what unsaved-value strategy, or an instance will be detected as transient. Beginning with NHibernate 1.2.0, version numbers start with 1, not 0 as in previous versions. This was done to allow using 0 as unsaved-value for the version property.

5.1.4. id Mapped classes must declare the primary key column of the database table. Most classes will also have a property holding the unique identifier of an instance. The element defines the mapping from that property to the primary key column.

(1) (2) (3) (4)

(5)

(optional): The name of the identifier property. type (optional): A name that indicates the NHibernate type. column (optional - defaults to the property name): The name of the primary key column. unsaved-value (optional - defaults to a "sensible" value): An identifier property value that indicates that an instance is newly instantiated (unsaved), distinguishing it from transient instances that were saved or loaded in a previous session. access (optional - defaults to property): The strategy NHibernate should use for accessing the property value. name

If the name attribute is missing, it is assumed that the class has no identifier property. The unsaved-value attribute is almost never needed in NHibernate 1.0. There is an alternative declaration to allow access to legacy data with composite keys. We strongly discourage its use for anything else. 5.1.4.1. generator The required child element names a .NET class used to generate unique identifiers for instances of the persistent class. If any parameters are required to configure or initialize the generator instance, they are NHibernate 2.1.0

30

Basic O/R Mapping passed using the element. uid_table next_hi_value_column

All generators implement the interface NHibernate.Id.IIdentifierGenerator. This is a very simple interface; some applications may choose to provide their own specialized implementations. However, NHibernate provides a range of built-in implementations. There are shortcut names for the built-in generators: increment

generates identifiers of any integral type that are unique only when no other process is inserting data into the same table. Do not use in a cluster. identity

supports identity columns in DB2, MySQL, MS SQL Server and Sybase. The identifier returned by the database is converted to the property type using Convert.ChangeType. Any integral property type is thus supported. sequence

uses a sequence in DB2, PostgreSQL, Oracle or a generator in Firebird. The identifier returned by the database is converted to the property type using Convert.ChangeType. Any integral property type is thus supported. hilo

uses a hi/lo algorithm to efficiently generate identifiers of any integral type, given a table and column (by default hibernate_unique_key and next_hi respectively) as a source of hi values. The hi/lo algorithm generates identifiers that are unique only for a particular database. Do not use this generator with a usersupplied connection. You can use the "where" parameter to specify the row to use in a table. This is useful if you want to use a single tabel for your identifiers, with different rows for each table. seqhilo

uses a hi/lo algorithm to efficiently generate identifiers of any integral type, given a named database sequence. uuid.hex

uses System.Guid and its ToString(string format) method to generate identifiers of type string. The length of the string returned depends on the configured format. uuid.string

uses a new System.Guid to create a byte[] that is converted to a string. guid

uses a new System.Guid as the identifier. guid.comb

uses the algorithm to generate a new System.Guid described by Jimmy Nilsson in the article http://www.informit.com/articles/article.asp?p=25862. native

picks identity, sequence or hilo depending upon the capabilities of the underlying database. NHibernate 2.1.0

31

Basic O/R Mapping

assigned

lets the application to assign an identifier to the object before Save() is called. foreign

uses the identifier of another associated object. Usually used in conjunction with a primary key association. 5.1.4.2. Hi/Lo Algorithm The hilo and seqhilo generators provide two alternate implementations of the hi/lo algorithm, a favorite approach to identifier generation. The first implementation requires a "special" database table to hold the next available "hi" value. The second uses an Oracle-style sequence (where supported). hi_value next_value 100

hi_value 100

Unfortunately, you can't use hilo when supplying your own IDbConnection to NHibernate. NHibernate must be able to fetch the "hi" value in a new transaction. 5.1.4.3. UUID Hex Algorithm format_value seperator_value

The UUID is generated by calling Guid.NewGuid().ToString(format). The valid values for format are described in the MSDN documentation. The default seperator is - and should rarely be modified. The format determines if the configured seperator can replace the default seperator used by the format. 5.1.4.4. UUID String Algorithm The UUID is generated by calling Guid.NewGuid().ToByteArray() and then converting the byte[] into a char[]. The char[] is returned as a String consisting of 16 characters. 5.1.4.5. GUID Algorithms The guid identifier is generated by calling Guid.NewGuid(). To address some of the performance concerns with using Guids as primary keys, foreign keys, and as part of indexes with MS SQL the guid.comb can be used. The benefit of using the guid.comb with other databases that support GUIDs has not been measured. 5.1.4.6. Identity columns and Sequences

NHibernate 2.1.0

32

Basic O/R Mapping

For databases which support identity columns (DB2, MySQL, Sybase, MS SQL), you may use identity key generation. For databases that support sequences (DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB) you may use sequence style key generation. Both these strategies require two SQL queries to insert a new object. uid_sequence



For cross-platform development, the native strategy will choose from the identity, sequence and hilo strategies, dependent upon the capabilities of the underlying database. 5.1.4.7. Assigned Identifiers If you want the application to assign identifiers (as opposed to having NHibernate generate them), you may use the assigned generator. This special generator will use the identifier value already assigned to the object's identifier property. Be very careful when using this feature to assign keys with business meaning (almost always a terrible design decision). Due to its inherent nature, entities that use this generator cannot be saved via the ISession's SaveOrUpdate() method. Instead you have to explicitly specify to NHibernate if the object should be saved or updated by calling either the Save() or Update() method of the ISession.

5.1.5. composite-id ......

For a table with a composite key, you may map multiple properties of the class as identifier properties. The element accepts property mappings and mappings as child elements.

Your persistent class must override Equals() and GetHashCode() to implement composite identifier equality. It must also be Serializable. Unfortunately, this approach to composite identifiers means that a persistent object is its own identifier. There is no convenient "handle" other than the object itself. You must instantiate an instance of the persistent class itself and populate its identifier properties before you can load() the persistent state associated with a composite key. We will describe a much more convenient approach where the composite identifier is implemented as a NHibernate 2.1.0

33

Basic O/R Mapping seperate class in Section 7.4, “Components as composite identifiers”. The attributes described below apply only to this alternative approach: •

(optional, required for this approach): A property of component type that holds the composite identifier (see next section). access (optional - defaults to property): The strategy NHibernate should use for accessing the property value. class (optional - defaults to the property type determined by reflection): The component class used as a composite identifier (see next section). name

• •

5.1.6. discriminator The element is required for polymorphic persistence using the table-per-class-hierarchy mapping strategy and declares a discriminator column of the table. The discriminator column contains marker values that tell the persistence layer what subclass to instantiate for a particular row. A restricted set of types may be used: String, Char, Int32, Byte, Short, Boolean, YesNo, TrueFalse.

(1) (2) (3)

(4)

(5)

(optional - defaults to class) the name of the discriminator column. type (optional - defaults to String) a name that indicates the NHibernate type force (optional - defaults to false) "force" NHibernate to specify allowed discriminator values even when retrieving all instances of the root class. insert (optional - defaults to true) set this to false if your discriminator column is also part of a mapped composite identifier. formula (optional) an arbitrary SQL expression that is executed when a type has to be evaluated. Allows content-based discrimination. column

Actual values of the discriminator column are specified by the discriminator-value attribute of the and elements. The force attribute is (only) useful if the table contains rows with "extra" discriminator values that are not mapped to a persistent class. This will not usually be the case. Using the formula attribute you can declare an arbitrary SQL expression that will be used to evaluate the type of a row:

5.1.7. version (optional) The element is optional and indicates that the table contains versioned data. This is particularly useful if you plan to use long transactions (see below).
NHibernate 2.1.0

(1) (2) (3)

34

Basic O/R Mapping

access="field|property|nosetter|ClassName" unsaved-value="null|negative|undefined|value" generated="never|always"

(4) (5) (6)

/>

(1) (2) (3) (4)

(5)

(6)

(optional - defaults to the property name): The name of the column holding the version number. name: The name of a property of the persistent class. type (optional - defaults to Int32): The type of the version number. access (optional - defaults to property): The strategy NHibernate should use for accessing the property value. unsaved-value (optional - defaults to a "sensible" value): A version property value that indicates that an instance is newly instantiated (unsaved), distinguishing it from transient instances that were saved or loaded in a previous session. (undefined specifies that the identifier property value should be used.) generated (optional - defaults to never): Specifies that this version property value is actually generated by the database. See the discussion of Section 5.5, “Generated Properties”. column

Version numbers may be of type Int64, Int32, Int16, Ticks, Timestamp, or TimeSpan (or their nullable counterparts in .NET 2.0).

5.1.8. timestamp (optional) The optional element indicates that the table contains timestamped data. This is intended as an alternative to versioning. Timestamps are by nature a less safe implementation of optimistic locking. However, sometimes the application might use the timestamps in other ways.

(1) (2) (3)

(4)

(5)

(optional - defaults to the property name): The name of a column holding the timestamp. name: The name of a property of .NET type DateTime of the persistent class. access (optional - defaults to property): The strategy NHibernate should use for accessing the property value. unsaved-value (optional - defaults to null): A timestamp property value that indicates that an instance is newly instantiated (unsaved), distinguishing it from transient instances that were saved or loaded in a previous session. (undefined specifies that the identifier property value should be used.) generated (optional - defaults to never): Specifies that this timestamp property value is actually generated by the database. See the discussion of Section 5.5, “Generated Properties”. column

Note that is equivalent to .

5.1.9. property The element declares a persistent property of the class.
NHibernate 2.1.0

(1) (2) (3) (4) (4) (5)

35

Basic O/R Mapping

access="field|property|ClassName" optimistic-lock="true|false" generated="never|insert|always"

(6) (7) (8)

/>

(1) (2) (3) (4)

(5)

(6)

(7)

(8)

name:

the name of the property of your class. column (optional - defaults to the property name): the name of the mapped database table column. type (optional): a name that indicates the NHibernate type. update, insert (optional - defaults to true) : specifies that the mapped columns should be included in SQL UPDATE and/or INSERT statements. Setting both to false allows a pure "derived" property whose value is initialized from some other property that maps to the same column(s) or by a trigger or other application. formula (optional): an SQL expression that defines the value for a computed property. Computed properties do not have a column mapping of their own. access (optional - defaults to property): The strategy NHibernate should use for accessing the property value. optimistic-lock (optional - defaults to true): Specifies that updates to this property do or do not require acquisition of the optimistic lock. In other words, determines if a version increment should occur when this property is dirty. generated (optional - defaults to never): Specifies that this property value is actually generated by the database. See the discussion of Section 5.5, “Generated Properties”.

typename could be: 1. 2. 3. 4. 5.

The name of a NHibernate basic type (eg. Int32, String, Char, DateTime, Timestamp, Single, Byte[], Object, ...). The name of a .NET type with a default basic type (eg. System.Int16, System.Single, System.Char, System.String, System.DateTime, System.Byte[], ...). The name of an enumeration type (eg. Eg.Color, Eg). The name of a serializable .NET type. The class name of a custom type (eg. Illflow.Type.MyCustomType).

Note that you have to specify full assembly-qualified names for all except basic NHibernate types (unless you set assembly and/or namespace attributes of the element). NHibernate supports .NET 2.0 Nullable types. These types are mostly treated the same as plain non-Nullable types internally. For example, a property of type Nullable can be mapped using type="Int32" or type="System.Int32". If you do not specify a type, NHibernate will use reflection upon the named property to take a guess at the correct NHibernate type. NHibernate will try to interpret the name of the return class of the property getter using rules 2, 3, 4 in that order. However, this is not always enough. In certain cases you will still need the type attribute. (For example, to distinguish between NHibernateUtil.DateTime and NHibernateUtil.Timestamp, or to specify a custom type.) The access attribute lets you control how NHibernate will access the value of the property at runtime. The value of the access attribute should be text formatted as access-strategy.naming-strategy. The .naming-strategy is not always required. Table 5.1. Access Strategies Access Strategy Name

Description

property

The default implementation. NHibernate uses the get/ NHibernate 2.1.0

36

Basic O/R Mapping Access Strategy Name

Description set accessors of the property. No naming strategy should be used with this access strategy because the value of the name attribute is the name of the property.

field

NHibernate will access the field directly. NHibernate uses the value of the name attribute as the name of the field. This can be used when a property's getter and setter contain extra actions that you don't want to occur when NHibernate is populating or reading the object. If you want the name of the property and not the field to be what the consumers of your API use with HQL, then a naming strategy is needed. nosetter

NHibernate will access the field directly when setting the value and will use the Property when getting the value. This can be used when a property only exposes a get accessor because the consumers of your API can't change the value directly. A naming strategy is required because NHibernate uses the value of the name attribute as the property name and needs to be told what the name of the field is. ClassName

If NHibernate's built in access strategies are not what is needed for your situation then you can build your own by implementing the interface NHibernate.Property.IPropertyAccessor. The value of the access attribute should be an assembly-qualified name that can be loaded with Activator.CreateInstance(string

assemblyQualified-

Name).

Table 5.2. Naming Strategies Naming Strategy Name

Description

camelcase

The name attribute is converted to camel case to find the field. uses the field foo. camelcase-underscore

The name attribute is converted to camel case and prefixed with an underscore to find the field. uses the field _foo. lowercase

The name attribute is converted to lower case to find the Field. uses the NHibernate 2.1.0

37

Basic O/R Mapping Naming Strategy Name

Description field foobar.

lowercase-underscore

The name attribute is converted to lower case and prefixed with an underscore to find the Field. uses the field _foobar. pascalcase-underscore

The name attribute is prefixed with an underscore to find the field. uses the field _Foo. pascalcase-m

The name attribute is prefixed with the character m to find the field. uses the field mFoo. pascalcase-m-underscore

The name attribute is prefixed with the character m and an underscore to find the field. uses the field m_Foo.

5.1.10. many-to-one An ordinary association to another persistent class is declared using a many-to-one element. The relational model is a many-to-one association. (It's really just an object reference.)

(1) (2) (3)

(4)

(5) (6)

(7)

(1) (2) (3) (4) (5) (6) (6) (7) (8) (9) (10) (11)

name:

The name of the property. column (optional): The name of the column. class (optional - defaults to the property type determined by reflection): The name of the associated class. cascade (optional): Specifies which operations should be cascaded from the parent object to the associated object. fetch (optional - defaults to select): Chooses between outer-join fetching or sequential select fetching. update, insert (optional - defaults to true) specifies that the mapped columns should be included in SQL UPDATE and/or INSERT statements. Setting both to false allows a pure "derived" association whose value is initialized from some other property that maps to the same colum(s) or by a trigger or other application. property-ref: (optional) The name of a property of the associated class that is joined to this foreign key. If not specified, the primary key of the associated class is used.

NHibernate 2.1.0

38

Basic O/R Mapping access

(8)

(optional - defaults to property): The strategy NHibernate should use for accessing the property

value. (optional): Enable the DDL generation of a unique constraint for the foreign-key column. (optional - defaults to true): Specifies that updates to this property do or do not require acquisition of the optimistic lock. In other words, dertermines if a version increment should occur when this property is dirty. not-found (optional - defaults to exception): Specifies how foreign keys that reference missing rows will be handled: ignore will treat a missing row as a null association. unique

(9)

(10) optimistic-lock

(11)

The cascade attribute permits the following values: all, save-update, delete, none. Setting a value other than none will propagate certain operations to the associated (child) object. See "Lifecycle Objects" below. The fetch attribute accepts two different values: • •

join

Fetch the association using an outer join Fetch the association using a separate query

select

A typical many-to-one declaration looks as simple as

The property-ref attribute should only be used for mapping legacy data where a foreign key refers to a unique key of the associated table other than the primary key. This is an ugly relational model. For example, suppose the Product class had a unique serial number, that is not the primary key. (The unique attribute controls NHibernate's DDL generation with the SchemaExport tool.)

Then the mapping for OrderItem might use:

This is certainly not encouraged, however.

5.1.11. one-to-one A one-to-one association to another persistent class is declared using a one-to-one element.

(1)

name:

(2)

class

(1) (2) (3) (4) (5) (6) (7)

The name of the property. (optional - defaults to the property type determined by reflection): The name of the associated

class. (3)

cascade

(optional) specifies which operations should be cascaded from the parent object to the associated

object. (4)

(optional) specifies that a foreign key constraint on the primary key of the mapped table references the table of the associated class. This option affects the order in which Save() and Delete() are cascaded (and is also used by the schema export tool). constrained

NHibernate 2.1.0

39

Basic O/R Mapping (optional - defaults to select): Chooses between outer-join fetching or sequential select fetching. (optional) The name of a property of the associated class that is joined to the primary key of this class. If not specified, the primary key of the associated class is used. access (optional - defaults to property): The strategy NHibernate should use for accessing the property value.

(5)

fetch

(6)

property-ref:

(7)

There are two varieties of one-to-one association: •

primary key associations

•

unique foreign key associations

Primary key associations don't need an extra table column; if two rows are related by the association then the two table rows share the same primary key value. So if you want two objects to be related by a primary key association, you must make sure that they are assigned the same identifier value! For a primary key association, add the following mappings to Employee and Person, respectively.



Now we must ensure that the primary keys of related rows in the PERSON and EMPLOYEE tables are equal. We use a special NHibernate identifier generation strategy called foreign: Employee ...

A newly saved instance of Person is then assigned the same primar key value as the Employee instance refered with the Employee property of that Person. Alternatively, a foreign key with a unique constraint, from Employee to Person, may be expressed as:

And this association may be made bidirectional by adding the following to the Person mapping:

5.1.12. natural-id ......

Even though we recommend the use of surrogate keys as primary keys, you should still try to identify natural NHibernate 2.1.0

40

Basic O/R Mapping

keys for all entities. A natural key is a property or combination of properties that is unique and non-null. If it is also immutable, even better. Map the properties of the natural key inside the element. Hibernate will generate the necessary unique key and nullability constraints, and your mapping will be more selfdocumenting. We strongly recommend that you implement Equals() and GetHashCode() to compare the natural key properties of the entity. This mapping is not intended for use with entities with natural primary keys. •

(optional, defaults to false): By default, natural identifier properties as assumed to be immutable (constant). mutable

5.1.13. component, dynamic-component The element maps properties of a child object to columns of the table of a parent class. Components may, in turn, declare their own properties, components or collections. See "Components" below.

(1) (2) (3) (4) (5) (6)

........

(1) (2)

(3) (4) (5)

(6)

name:

The name of the property. class (optional - defaults to the property type determined by reflection): The name of the component (child) class. insert: Do the mapped columns appear in SQL INSERTs? update: Do the mapped columns appear in SQL UPDATEs? access (optional - defaults to property): The strategy NHibernate should use for accessing the property value. optimistic-lock (optional - defaults to true): Specifies that updates to this component do or do not require acquisition of the optimistic lock. In other words, determines if a version increment should occur when this property is dirty.

The child tags map properties of the child class to table columns. The element allows a subelement that maps a property of the component class as a reference back to the containing entity. The element allows an IDictionary to be mapped as a component, where the property names refer to keys of the dictionary.

5.1.14. subclass Finally, polymorphic persistence requires the declaration of each subclass of the root persistent class. For the (recommended) table-per-class-hierarchy mapping strategy, the declaration is used.

NHibernate 2.1.0

41

Basic O/R Mapping



(1) (2) (3) (4)

.....

(1)

name:

(2)

discriminator-value

(3) (4)

The fully qualified .NET class name of the subclass, including its assembly name. (optional - defaults to the class name): A value that distiguishes individual subclasses. proxy (optional): Specifies a class or interface to use for lazy initializing proxies. lazy (optional, defaults to true): Setting lazy="false" disables the use of lazy fetching.

Each subclass should declare its own persistent properties and subclasses. and properties are assumed to be inherited from the root class. Each subclass in a hierarchy must define a unique discriminatorvalue. If none is specified, the fully qualified .NET class name is used. For information about inheritance mappings, see Chapter 8, Inheritance Mapping.

5.1.15. joined-subclass Alternatively, a subclass that is persisted to its own table (table-per-subclass mapping strategy) is declared using a element.

(1) (2) (3)

.....

(1)

name:

(2)

proxy

(3)

The fully qualified class name of the subclass. (optional): Specifies a class or interface to use for lazy initializing proxies. lazy (optional): Setting lazy="true" is a shortcut equalivalent to specifying the name of the class itself as the proxy interface.

No discriminator column is required for this mapping strategy. Each subclass must, however, declare a table column holding the object identifier using the element. The mapping at the start of the chapter would be re-written as:

NHibernate 2.1.0

42

Basic O/R Mapping



For information about inheritance mappings, see Chapter 8, Inheritance Mapping.

5.1.16. union-subclass A third option is to map only the concrete classes of an inheritance hierarchy to tables, (the tableper-concrete-class strategy) where each table defines all persistent state of the class, including inherited state. In Hibernate, it is not absolutely necessary to explicitly map such inheritance hierarchies. You can simply map each class with a separate declaration. However, if you wish use polymorphic associations (e.g. an association to the superclass of your hierarchy), you need to use the mapping.

(1) (2) (3) (4)

.....

(1)

name:

(2)

table:

(3) (4)

The fully qualified class name of the subclass. The name of the subclass table. proxy (optional): Specifies a class or interface to use for lazy initializing proxies. lazy (optional, defaults to true): Setting lazy="false" disables the use of lazy fetching.

No discriminator column or key column is required for this mapping strategy. For information about inheritance mappings, see Chapter 8, Inheritance Mapping.

5.1.17. join Using the element, it is possible to map properties of one class to several tables, when there's a 1-to-1 NHibernate 2.1.0

43

Basic O/R Mapping relationship between the tables.

(1) (2) (3) (4) (5)

...

(1)

table:

(2)

schema

(3)

(4)

(5)

The name of the joined table. (optional): Override the schema name specified by the root element. fetch (optional - defaults to join): If set to join, the default, Hibernate will use an inner join to retrieve a defined by a class or its superclasses and an outer join for a defined by a subclass. If set to select then Hibernate will use a sequential select for a defined on a subclass, which will be issued only if a row turns out to represent an instance of the subclass. Inner joins will still be used to retrieve a defined by the class and its superclasses. inverse (optional - defaults to false): If enabled, Hibernate will not try to insert or update the properties defined by this join. optional (optional - defaults to false): If enabled, Hibernate will insert a row only if the properties defined by this join are non-null and will always use an outer join to retrieve the properties.

For example, the address information for a person can be mapped to a separate table (while preserving value type semantics for all properties): ... ...

This feature is often only useful for legacy data models, we recommend fewer tables than classes and a finegrained domain model. However, it is useful for switching between inheritance mapping strategies in a single hierarchy, as explained later.

5.1.18. map, set, list, bag Collections are discussed later.

5.1.19. import Suppose your application has two persistent classes with the same name, and you don't want to specify the fully qualified name in NHibernate queries. Classes may be "imported" explicitly, rather than relying upon autoimport="true". You may even import classes and interfaces that are not explicitly mapped.

NHibernate 2.1.0

44

Basic O/R Mapping


(1) (2)

/>

(1) (2)

class:

The fully qualified class name of any .NET class, including its assembly name. rename (optional - defaults to the unqualified class name): A name that may be used in the query language.

5.2. NHibernate Types 5.2.1. Entities and values To understand the behaviour of various .NET language-level objects with respect to the persistence service, we need to classify them into two groups: An entity exists independently of any other objects holding references to the entity. Contrast this with the usual Java model where an unreferenced object is garbage collected. Entities must be explicitly saved and deleted (except that saves and deletions may be cascaded from a parent entity to its children). This is different from the ODMG model of object persistence by reachability - and corresponds more closely to how application objects are usually used in large systems. Entities support circular and shared references. They may also be versioned. An entity's persistent state consists of references to other entities and instances of value types. Values are primitives, collections, components and certain immutable objects. Unlike entities, values (in particular collections and components) are persisted and deleted by reachability. Since value objects (and primitives) are persisted and deleted along with their containing entity they may not be independently versioned. Values have no independent identity, so they cannot be shared by two entities or collections. All NHibernate types except collections support null semantics if the .NET type is nullable (i.e. not derived from System.ValueType). Up until now, we've been using the term "persistent class" to refer to entities. We will continue to do that. Strictly speaking, however, not all user-defined classes with persistent state are entities. A component is a user defined class with value semantics.

5.2.2. Basic value types The basic types may be roughly categorized into three groups - System.ValueType types, System.Object types, and System.Object types for large objects. Just like the .NET Types, columns for System.ValueType types can not store null values and System.Object types can store null values. Table 5.3. System.ValueType Mapping Types NHibernate Type

.NET Type

Database Type

AnsiChar

System.Char

Db-

Remarks

Type.AnsiStringFixedL ength - 1 char Boolean

NHibernate 2.1.0

System.Boolean

DbType.Boolean

Default when no type attribute specified.

45

Basic O/R Mapping NHibernate Type

.NET Type

Database Type

Remarks

Byte

System.Byte

DbType.Byte

Default when no type attribute specified.

Char

System.Char

Db-

Default when no type attribute specified.

Type.StringFixedLengt h - 1 char

- ig- Default when no type atnores the milliseconds tribute specified.

DateTime

System.DateTime

DbType.DateTime

Decimal

System.Decimal

DbType.Decimal

Default when no type attribute specified.

Double

System.Double

DbType.Double

Default when no type attribute specified.

Guid

System.Guid

DbType.Guid

Default when no type attribute specified.

Int16

System.Int16

DbType.Int16

Default when no type attribute specified.

Int32

System.Int32

DbType.Int32

Default when no type attribute specified.

Int64

System.Int64

DbType.Int64

Default when no type attribute specified.

PersistentEnum

A System.Enum

The DbType for the under- Do not specify lying value. type="PersistentEnum" in the mapping. Instead specify the Assembly Qualified Name of the Enum or let NHibernate use Reflection to "guess" the Type. The UnderlyingType of the Enum is used to determine the correct DbType.

Single

System.Single

DbType.Single

Default when no type attribute specified.

Ticks

System.DateTime

DbType.Int64

type="Ticks"

must be

specified. Default when no type attribute specified.

TimeSpan

System.TimeSpan

DbType.Int64

Timestamp

System.DateTime

DbType.DateTime

TrueFalse

System.Boolean

Db-

type="TrueFalse"

Type.AnsiStringFixedL

be specified.

- as type="Timestamp" must specific as database sup- be specified. ports.

ength

must

- 1 char either 'T'

or 'F' NHibernate 2.1.0

46

Basic O/R Mapping NHibernate Type

.NET Type

Database Type

Remarks

YesNo

System.Boolean

Db-

type="YesNo"

Type.AnsiStringFixedL ength

must be

specified.

- 1 char either 'Y'

or 'N'

Table 5.4. System.Object Mapping Types NHibernate Type

.NET Type

Database Type

Remarks

AnsiString

System.String

DbType.AnsiString

type="AnsiString"

must

be specified. CultureInfo

Sys-

DbType.String

tem.Globalization.Cul

for culture

- 5 chars Default when no type attribute specified.

tureInfo Binary

System.Byte[]

DbType.Binary

Default when no type attribute specified.

Type

System.Type

DbType.String

holding Default when no type atQualified tribute specified.

Assembly Name. String

System.String

DbType.String

Default when no type attribute specified.

Table 5.5. Large Object Mapping Types NHibernate Type

.NET Type

Database Type

Remarks

StringClob

System.String

DbType.String

type="StringClob"

BinaryBlob

System.Byte[]

DbType.Binary

type="BinaryBlob"

Serializable

Any System.Object that DbType.Binary is marked with SerializableAttribute.

must be specified. Entire field is read into memory. must be specified. Entire field is read into memory. type="Serializable"

should be specified. This is the fallback type if no NHibernate Type can be found for the Property.

NHibernate supports some additional type names for compatibility with Hibernate (useful for those coming over from Hibernate or using some of the tools to generate hbm.xml files). A type="integer" or type="int" will map to an Int32 NHibernate type, type="short" to an Int16 NHibernateType. To see all of the conversions you can view the source of static constructor of the class NHibernate.Type.TypeFactory.

5.2.3. Custom value types NHibernate 2.1.0

47

Basic O/R Mapping

It is relatively easy for developers to create their own value types. For example, you might want to persist properties of type Int64 to VARCHAR columns. NHibernate does not provide a built-in type for this. But custom types are not limited to mapping a property (or collection element) to a single table column. So, for example, you might have a property Name { get; set; } of type String that is persisted to the columns FIRST_NAME, INITIAL, SURNAME. To implement a custom type, implement either NHibernate.UserTypes.IUserType or NHibernate.UserTypes.ICompositeUserType and declare properties using the fully qualified name of the type. Check out NHibernate.DomainModel.DoubleStringType to see the kind of things that are possible.

Notice the use of tags to map a property to multiple columns. The ICompositeUserType, IEnhancedUserType, INullableUserType, IUserCollectionType, and IUserVersionType interfaces provide support for more specialized uses. You may even supply parameters to an IUserType in the mapping file. To do this, your IUserType must implement the NHibernate.UserTypes.IParameterizedType interface. To supply parameters to your custom type, you can use the element in your mapping files. 0

The IUserType can now retrieve the value for the parameter named default from the IDictionary object passed to it. If you use a certain UserType very often, it may be useful to define a shorter name for it. You can do this using the element. Typedefs assign a name to a custom type, and may also contain a list of default parameter values if the type is parameterized. 0



It is also possible to override the parameters supplied in a typedef on a case-by-case basis by using type parameters on the property mapping. Even though NHibernate's rich range of built-in types and support for components means you will very rarely need to use a custom type, it is nevertheless considered good form to use custom types for (non-entity) classes that occur frequently in your application. For example, a MonetaryAmount class is a good candidate for an ICompositeUserType, even though it could easily be mapped as a component. One motivation for this is abstraction. With a custom type, your mapping documents would be future-proofed against possible changes in your way of representing monetary values.

5.2.4. Any type mappings

NHibernate 2.1.0

48

Basic O/R Mapping

There is one further type of property mapping. The mapping element defines a polymorphic association to classes from multiple tables. This type of mapping always requires more than one column. The first column holds the type of the associated entity. The remaining columns hold the identifier. It is impossible to specify a foreign key constraint for this kind of association, so this is most certainly not meant as the usual way of mapping (polymorphic) associations. You should use this only in very special cases (eg. audit logs, user session data, etc).

The meta-type attribute lets the application specify a custom type that maps database column values to persistent classes which have identifier properties of the type specified by id-type. If the meta-type returns instances of System.Type, nothing else is required. On the other hand, if it is a basic type like String or Char, you must specify the mapping from values to classes.


(1) (2) (3) (4) (5) (6)

> ..... .....

(1) (2) (3)

(4) (5)

(6)

name:

the property name. id-type: the identifier type. meta-type (optional - defaults to Type): a type that maps System.Type to a single database column or, alternatively, a type that is allowed for a discriminator mapping. cascade (optional - defaults to none): the cascade style. access (optional - defaults to property): The strategy NHibernate should use for accessing the property value. optimistic-lock (optional - defaults to true): Specifies that updates to this property do or do not require acquisition of the optimistic lock. In other words, define if a version increment should occur if this property is dirty.

5.3. SQL quoted identifiers You may force NHibernate to quote an identifier in the generated SQL by enclosing the table or column name in backticks in the mapping document. NHibernate will use the correct quotation style for the SQL Dialect (usually double quotes, but brackets for SQL Server and backticks for MySQL).

NHibernate 2.1.0

49

Basic O/R Mapping

...

5.4. Modular mapping files It is possible to define subclass and joined-subclass mappings in seperate mapping documents, directly beneath hibernate-mapping. This allows you to extend a class hierachy just by adding a new mapping file. You must specify an extends attribute in the subclass mapping, naming a previously mapped superclass. Use of this feature makes the ordering of the mapping documents important!



5.5. Generated Properties Generated properties are properties which have their values generated by the database. Typically, NHibernate applications needed to Refresh objects which contain any properties for which the database was generating values. Marking properties as generated, however, lets the application delegate this responsibility to NHibernate. Essentially, whenever NHibernate issues an SQL INSERT or UPDATE for an entity which has defined generated properties, it immediately issues a select afterwards to retrieve the generated values. Properties marked as generated must additionally be non-insertable and non-updateable. Only Section 5.1.7, “version (optional)”, Section 5.1.8, “timestamp (optional)”, and Section 5.1.9, “property” can be marked as generated. never

(the default) - means that the given property value is not generated within the database.

- states that the given property value is generated on insert, but is not regenerated on subsequent updates. Things like created-date would fall into this category. Note that even though Section 5.1.7, “version (optional)” and Section 5.1.8, “timestamp (optional)” properties can be marked as generated, this option is not available there... insert

always

- states that the property value is generated both on insert and on update.

5.6. Auxiliary Database Objects Allows CREATE and DROP of arbitrary database objects, in conjunction with NHibernate's schema evolution tools, to provide the ability to fully define a user schema within the NHibernate mapping files. Although designed specifically for creating and dropping things like triggers or stored procedures, really any SQL command that can be run via a IDbCommand.ExecuteNonQuery() method is valid here (ALTERs, INSERTS, etc). There are essentially two modes for defining auxiliary database objects. The first mode is to explicitly list the CREATE and DROP commands out in the mapping file:

NHibernate 2.1.0

50

Basic O/R Mapping

... CREATE TRIGGER my_trigger ... DROP TRIGGER my_trigger

The second mode is to supply a custom class which knows how to construct the CREATE and DROP commands. This custom class must implement the NHibernate.Mapping.IAuxiliaryDatabaseObject interface. ...

You may also specify parameters to be passed to the database object: ... parameterValue

NHibernate will call IAuxiliaryDatabaseObject.SetParameterValues passing it a dictionary of parameter names and values. Additionally, these database objects can be optionally scoped such that they only apply when certain dialects are used. ...

NHibernate 2.1.0

51

Chapter 6. Collection Mapping 6.1. Persistent Collections NHibernate requires that persistent collection-valued fields be declared as an interface type, for example: public class Product { private string serialNumber; private ISet parts = new HashedSet(); public ISet Parts { get { return parts; } set { parts = value; } } public string SerialNumber { get { return serialNumber; } set { serialNumber = value; } } }

The

actual

interface

might

be

Iesi.Collections.ISet,

tem.Collections.IList, tem.Collections.Generic.ICollection,

System.Collections.ICollection,

System.Collections.IDictionary, System.Collections.Generic.IList,

SysSysSys-

tem.Collections.Generic.IDictionary, Iesi.Collections.Generic.ISet

or ... anything you like! (Where "anything you like" means you will have to write an implementation of NHibernate.UserType.IUserCollectionType.) Notice how we initialized the instance variable with an instance of HashedSet. This is the best way to initialize collection valued properties of newly instantiated (non-persistent) instances. When you make the instance persistent - by calling Save(), for example - NHibernate will actually replace the HashedSet with an instance of NHibernate's own implementation of ISet. Watch out for errors like this: Cat cat = new DomesticCat(); Cat kitten = new DomesticCat(); .... ISet kittens = new HashedSet(); kittens.Add(kitten); cat.Kittens = kittens; session.Save(cat); kittens = cat.Kittens; //Okay, kittens collection is an ISet HashedSet hs = (HashedSet) cat.Kittens; //Error!

Collection instances have the usual behavior of value types. They are automatically persisted when referenced by a persistent object and automatically deleted when unreferenced. If a collection is passed from one persistent object to another, its elements might be moved from one table to another. Two entities may not share a reference to the same collection instance. Due to the underlying relational model, collection-valued properties do not support null value semantics; NHibernate does not distinguish between a null collection reference and an empty collection. You shouldn't have to worry much about any of this. Just use NHibernate's collections the same way you use ordinary .NET collections, but make sure you understand the semantics of bidirectional associations (discussed later) before using them.

NHibernate 2.1.0

52

Collection Mapping

Collection instances are distinguished in the database by a foreign key to the owning entity. This foreign key is referred to as the collection key . The collection key is mapped by the element. Collections may contain almost any other NHibernate type, including all basic types, custom types, entity types and components. This is an important definition: An object in a collection can either be handled with "pass by value" semantics (it therefore fully depends on the collection owner) or it can be a reference to another entity with an own lifecycle. Collections may not contain other collections. The contained type is referred to as the collection element type. Collection elements are mapped by , , , or . The first two map elements with value semantics, the other three are used to map entity associations. All collection types except ISet and bag have an index column - a column that maps to an array or IList index or IDictionary key. The index of an IDictionary may be of any basic type, an entity type or even a composite type (it may not be a collection). The index of an array or list is always of type Int32. Indexes are mapped using , , or . There are quite a range of mappings that can be generated for collections, covering many common relational models. We suggest you experiment with the schema generation tool to get a feeling for how various mapping declarations translate to database tables.

6.2. Mapping a Collection Collections are declared by the , ,