NHibernate 3.0 Cookbook

Before we begin mapping, let's get our Visual Studio solution set up. Follow these steps to set up your solution with NHibernate binaries and schemas.

Now, let's start by creating our Product class with the following steps:

Next, let's create an NHibernate mapping for our product class. Follow these steps:

In this recipe, we begin by creating our model. The model is the collection of classes that will be persisted or stored in the database. A persistent class is any class that will be persisted. An entity class is a persistent class with an ID. An instance of an entity class is called an entity. So far, our model only contains the Product entity class. We will expand on this model over the next few recipes.

Notice that our Product class looks just like any other Plain Old CLR Object (POCO) class. One of the strongly held design decisions in NHibernate is that all entity classes should be persistence ignorant, that is, they should not know about, or be dependent on NHibernate.

Let's examine the Id property a little closer. The Id property of each Product instance will contain the primary key value from the database. In NHibernate, this is named the persistent object identifier (POID). Just as the primary key value uniquely identifies a row in a database table, the POID will uniquely identify an entity in memory.

If you are new to NHibernate, this protected setter may look strange to you.

    public virtual Guid Id { get; protected set; }

This is a shorthand way to limit access to the Id property. Code outside of the Product class is unable to change the value of the Id property. However, NHibernate sets properties using highly optimized reflection, ignoring the protected restriction. This keeps your application from inadvertently altering this value.

Next, we create our mapping for the Product entity class. Visual Studio uses the nhibernate-mapping.xsd schema to provide IntelliSense while completing this mapping. As a general rule, all NHibernate mapping files end with a .hbm.xml extension, and have a build action of Embedded Resource. NHibernate searches through the embedded resources in your assembly, loading each one with this extension.

Let's break down this XML mapping. Every XML mapping document contains a single hibernate-mapping element. The xmlns attribute sets the XML namespace. Along with the schema in our Schema folder, Visual Studio uses this to enable IntelliSense inside NHibernate mappings.

The assembly attribute tells NHibernate which assembly, by default, contains our types. Similarly, the namespace attribute sets the default .NET namespace types in this mapping file. Together, they allow us to use the simple name Product instead of the full assembly qualified name of Eg.Core.Product, Eg.Core. Inside the hibernate-mapping element, we have a class element. The name attribute tells NHibernate that this class element defines the mapping for our entity class Product.

The Id element defines the POID. The name attribute refers to the Id property of our Product class. It is case-sensitive, just as in the C# language.

The generator element defines how NHibernate will generate POIDs. In this case, we've told NHibernate to use the guid.comb algorithm. Several other options exist.

The property elements define properties on our Product class. Each name attribute matches the name of a property on our Product class. By default, NHibernate allows null values. Adding not-null="true" tells NHibernate to disallow null values.

With this mapping, the Microsoft SQL Server database table used to store our Product entities appears as shown in the next screenshot. It may differ slightly for other databases.

There are three main approaches to begin developing an NHibernate application.

<natural-id mutable="true">
  <property name="UserName" not-null="true" />
</natural-id>

Complete the previous Mapping a class with XML example.

In this example, we've mapped a table-per-class hierarchy, meaning data for our entire hierarchy is stored in a single table, as shown in the next screenshot:

NHibernate uses a discriminator column, ProductType in this case, to distinguish among products, books, and movies. By default, the discriminator contains the class name. In this example, that would be Eg.Core.Product, Eg.Core.Book, or Eg.Core.Movie. These defaults can be overridden in the mappings by using a discriminator-value attribute on our class and subclass elements.

In our Book.hbm.xml mapping, we've defined Book as a subclass of Product with Author and ISBN properties. In our Movie.hbm.xml mapping, we've defined Movie as a subclass of Product with a Director property.

With table-per-class-hierarchy, we cannot define any of our subclass properties as not-null="true", because this would create a not-null constraint on those fields. For instance, if we set up the Director property as not null, we wouldn't be able to insert Product or Book instances, because they don't define a Director property. If this is required, use one of the hierarchy mapping strategies listed next.

Java refugees may recognize the extends attribute, as extends is the Java keyword used to declare class inheritance. NHibernate first came to life as a port of Java's Hibernate ORM.

Table-per-class hierarchy is the suggested method for mapping class hierarchies, but NHibernate always gives us other options. However, mixing these options within the same class hierarchy is discouraged, and only works in very limited circumstances.

Table per class

In table-per-class mappings, properties of the base class (Product) are stored in a shared table, while each subclass gets its own table for the subclass properties.

Table per subclass uses the joined-subclass element, which requires a key element to name the primary key column. As the name implies, NHibernate will use a join to query for this data. Also, notice that our Product table doesn't contain a ProductType column. Only table-per-class hierarchy uses discriminators. Using table-per-class, our Movie mapping will appear as the following code:

<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"
    assembly="Eg.Core"
    namespace="Eg.Core">
  <joined-subclass name="Movie" extends="Product">
    <key column="Id" />
    <property name="Director" />
  </joined-subclass>
</hibernate-mapping>

Table per concrete class

In table-per-concrete-class mappings, each class gets its own table containing columns for all properties of the class and the base class, as shown in the next screenshot:

There is no duplication of data. That is, data from a Book instance is only written to the Book table, not the Product table. To fetch Product data, NHibernate will use unions to query all three tables. Using table-per-concrete-class, our Movie mapping will appear as shown in the following code:

<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"
    assembly="Eg.Core"
    namespace="Eg.Core">
  <union-subclass name="Movie" extends="Product">
    <property name="Director" />
  </union-subclass>
</hibernate-mapping>

Complete the previous Creating class hierarchy mappings example.

Our ActorRole mapping is simple. Check out Mapping a class with XML for more information. ActorRole isn't part of our Product hierarchy. In the database, it gets a table of its own, as shown in the next screenshot:

As expected, the ActorRole table has fields for the Id, Actor, and Role properties. The MovieId and ActorIndex columns come from the mapping of our Actors list on Movie, not the ActorRole mapping.

The Actors property uses an IList collection. Another strong design choice with NHibernate, and a good programming practice in general, is the liberal use of interfaces. This allows NHibernate to use its own list implementation to support lazy loading, discussed later in this recipe.

In our Movie mapping, the Actors property is mapped with the list element. To associate an ActorRole with a Movie in the database, we store the Movie's Id with each ActorRole. The key element tells NHibernate to store this in a column named MovieId.

We've defined Actors as a list, which implies that order is significant. Actors in leading roles get top billing. Our index element defines the ActorIndex column to store the position of each element in the list. Finally, we tell NHibernate that Actors is a collection of ActorRoles with <one-to-many class="ActorRole" />.

The all-delete-orphan value of the cascade attribute tells NHibernate to save the associated ActorRole objects automatically when it saves a Movie, and delete them when it deletes a Movie.

There are a few items to discuss with this recipe.

foreach (var actor in movie.Actors)
  Console.WriteLine(actor.Actor);

SELECT 
  actors0_.MovieId as MovieId1_, 
  actors0_.Id as Id1_, 
  actors0_.ActorIndex as ActorIndex1_, 
  actors0_.Id as Id0_0_, 
  actors0_.Actor as Actor0_0_, 
  actors0_.Role as Role0_0_ 
FROM ActorRole actors0_ 
WHERE 
  actors0_.MovieId= 'a2c42861-9ff0-4546-85c1-9db700d6175e'

public class ActorRole : Entity
{

  public virtual string Actor { get; set; }
  public virtual string Role { get; set; }
  public virtual Movie Movie { get; set; }

}

<bag name="Actors">
  <key column="MovieId"/>
  <one-to-many class="ActorRole"/>
</bag>

<idBag name="Actors">
  <collection-id column="ActorRoleBagId" type="Int64">
    <generator class="hilo" />
  </collection-id>
  <key column="MovieId"/>
  <one-to-many class="ActorRole"/>
</idBag>

<list name="Actors">
  <key column="MovieId" />
  <list-index column="ActorRoleIndex" />
  <one-to-many class="ActorRole"/>
</list>

<set name="Actors">
  <key column="MovieId" />
  <one-to-many class="ActorRole"/>
</set>

<map name="Actors" >
  <key column="MovieId" />
  <map-key column="Role" type="string" />
  <element column="Actor" type="string"/>
</map>

<map name="SomeProperty">
  <key column="Id" />
  <index-many-to-many class="KeyEntity"/>
  <many-to-many class="ValueEntity" />
</map>

Complete the previous three recipes.

NHibernate relies on the Equals method to determine equality. The default behavior defined in System.Object uses reference equality for reference types, including classes. That is, x.Equals(y) is only true when x and y point to the same object instance. This default works well in most cases.

To support lazy loading, NHibernate uses proxy objects. As we learned in the previous recipe, these proxy objects are subclasses of the real entity class, with every member overridden to enable lazy loading.

This combination of proxy objects and the default Equals behavior can lead to subtle and unexpected bugs in your application. An application should not be aware of proxy objects, and therefore would expect that a proxy and a real instance representing the same entity would be equal. A Product instance with an ID of 8 should be equal to a different Product instance or Product proxy with an ID of 8. To handle this, we must override the default Equals behavior.

On our Entity base class, we override the Equals method to determine equality based on POID. In Equals(Object obj), we simply call Equals(Entity<TId> other), attempting to cast the object to Entity. If it can't be cast, null is passed instead.

If other is null, the objects are not equal. This serves two purposes. First, x.Equals(null) should always return false. Second, someEntity.Equals(notAnEntity) should also return false. Next, we compare references. Obviously, if two variables reference the same instance, they are equal. If ReferenceEquals(this, other) returns true, we return true.

Next, we compare the Ids to the default value to determine if the entities are transient. A transient object is an object that has not been persisted to the database. default(TId) returns whatever the default may be for TId. For Guids, the default is Guid.Empty. For strings and all other reference types, it's null. For numeric types, it's zero. If the Id property equals the default value, the entity is transient. If one or both entities are transient, we give up and return false.

If both entities are persisted, they both have POIDs. We can compare these POIDs to determine equality. If the POIDs don't match, we know for certain that the two entities are not equal. We return false.

Finally, we have one last check. We know that both entities are persistent, and they have the same Id. This doesn't quite prove that they're equal. It's perfectly legal for an ActorRole entity to have the same POID as a Product entity. Our last check is to compare the types. If one type is assignable to the other type, then we know for certain that the two are equal.

Suppose other is a proxy of Product representing a book entity, and this is an actual Book instance representing the same entity. this.Equals(other) should return true because they both represent the same entity. Unfortunately, other.GetType() will return the type ProductProxy12398712938 instead of the type Product. As typeof(ProductProxy12398712938).IsAssignableFrom(typeof(Book)) returns false, our Equals would fail on this case. However, we can use other.GetUnproxiedType() to reach down through the proxy layer and return the entity type. Because typeof(Product).IsAssignableFrom(typeof(Book)) returns true, our Equals implementation works.

Because we've overridden Equals, we also need to override GetHashCode to satisfy the requirements of the .NET Framework. Specifically, if x.Equals(y), then x.GetHashCode() and y.GetHashCode() should return the same value. The inverse is not necessarily true, however; x and y may share a hash code even when they're not equal. In our Entity base class, we simply use the hash code of Id, as this is the basis of our equality check.

For more information on Equals and GetHashCode, refer to the MSDN documentation for these methods at http://msdn.microsoft.com/en-us/library/system.object.aspx.

Complete all the previous recipes including Setting up a base entity class.

Suppose you have a database application with two users. User #1 and user #2 both pull up the same data on their screen and begin making changes. User #1 submits her changes back to the database. A few moments later, user #2 submits his changes. Without any concurrency checking, user #2's changes will silently overwrite user #1's changes. There are two possible ways to prevent this: optimistic and pessimistic concurrency.

Optimistic concurrency is the process where data is checked for changes before any update is executed. In this scenario, user #1 and user #2 both begin their changes. User #1 submits her changes. When user #2 submits his changes, his update will fail because the current data (after user #1's changes) doesn't match the data that user #2 originally read from the database.

In the example shown here, we use the version field to track changes to an entity. Update statements takes the following form:

UPDATE Product
SET    Version = 2 /* @p0 */,
       Name = 'Junk' /* @p1 */,
       Description = 'Cool' /* @p2 */,
       UnitPrice = 100 /* @p3 */
WHERE  Id = '764de11e-1fd0-491e-8158-9db8015f9be5' /* @p4 */
       AND Version = 1 /* @p5 */

NHibernate checks that the version is the same value as when the entity was loaded from the database, and then increments the value. If the entity was already updated, the version field will not be 1, and no rows will be updated by this statement. NHibernate detects the zero rows affected and throws a StaleStateException, meaning the entity in memory is stale, or out of sync with the database.

The alternative to optimistic concurrency is pessimistic locking. Pessimistic locking is the process where a user obtains an exclusive lock on the data while they are editing it. It takes the pessimistic view that, given the chance, user #2 will overwrite user #1's changes, so it's best not to let user #2 even look at the data. In this scenario, once user #1 pulls up the data, she has an exclusive lock. User #2 will not be able to read that data. His query will wait until user #1 drops the lock or the query times out. Inevitably, user #1 will take a phone call or step away for a cup of coffee while user #2 waits for access to the data. To implement this type of locking with NHibernate, your application must call session.Lock within a transaction.

<class name="Product" 
       dynamic-update="true" 
       optimistic-lock="dirty">

UPDATE Product
SET    Name = 'Junk' /* @p0 */
WHERE  Id = '741bd189-78b5-400c-97bd-9db80159ef79' /* @p1 */
       AND Name = 'Stuff' /* @p2 */

UPDATE Product
SET    Name = 'Junk' /* @p0 */
WHERE  Id = 'd3458d6e-fa28-4dcb-9130-9db8015cc5bb' /* @p1 */
       AND Name = 'Stuff' /* @p2 */
       AND Description = 'Cool' /* @p3 */
       AND UnitPrice = 100 /* @p4 */

Download the Fluent NHibernate binary from the Fluent NHibernate website at http://fluentnhibernate.org/downloads. Select a version that's compatible with the specific build of NHibernate you are using. The Fluent NHibernate download also contains the necessary assemblies for NHibernate. You may wish to use them instead.

Extract FluentNHibernate.dll from the downloaded ZIP file to the Lib folder.

Complete the previous Eg.Core model and mapping recipes.

Fluent NHibernate provides two methods for mappings: Fluent mapping syntax and auto-mapping. In this recipe, we use the Fluent mapping syntax. Each entity class has a corresponding mapping class.

Because the mapping syntax requires class members to be accessible, we must change the Version property from protected to public. Fluent NHibernate also includes some tricks to work around this issue. They're explained fully in the wiki at http://wiki.fluentnhibernate.org/Fluent_mapping_private_properties.

Mappings for root classes are inherited from ClassMap, and subclasses in a class hierarchy inherit from SubclassMap. By default, Fluent NHibernate creates a table-per-subclass hierarchy. To use a table-per-class hierarchy instead, we specify DiscriminateSubClassesOnColumn in Product. Fluent NHibernate doesn't support table-per-concrete-class hierarchies.

When mapping the natural ID of Product, we specify .Not.ReadOnly(). This is the same as setting mutable="true" in the XML mapping.

Properties are mapped using the Map() method, which is equivalent to the property element in XML mappings.

One-to-many collections are mapped using the HasMany() method, followed by AsMap(), AsBag(), AsSet(), or AsList(). AsList uses the Column() method to specify a column name for the list index.

With a standard NHibernate application, NHibernate takes each XML mapping and deserializes it into an HbmMapping object, then adds the HbmMapping object to the NHibernate configuration, as shown in the next diagram:

With ConfORM, we skip this deserialization step. The ConfORM mapper outputs an HbmMapping object built from our conventions, ready to be added to the configuration.

ConfORM uses conventions and patterns to build a mapping directly from the model. In addition to ConfORM's default patterns, we use a few extra conventions in our model.

Object relational mappers (ORM) are designed to overcome the impedance mismatch between the object model in the application and the relational model in the database. This mismatch is especially evident when representing a bidirectional one-to-many relationship between entities. In the relational model, this bidirectional relationship is represented by a single foreign key. In the object model, the parent entity has a collection of children, and each child has a reference to its parent.

To work around this mismatch, NHibernate ignores one side of the bidirectional relationship. The foreign key in the database is populated based on either the OrderItems reference to the Order or the Orders collection of OrderItems, but not both. We determine which end of the relationship controls the foreign key using the inverse attribute on the collection. By default, the Order controls the foreign key. Saving a new Order with one OrderItem will result in the following three SQL statements:

INSERT INTO "Order" (Id) VALUES (@p0)
INSERT INTO OrderItem (Id) VALUES (@p0)
UPDATE OrderItem SET OrderId = @p0 WHERE Id = @p1

When we specify inverse="true", the OrderItem controls the foreign key. This is preferable because it eliminates the extra UPDATE statement, resulting in the following two SQL statements:

INSERT INTO "Order" (Id) VALUES (@p0)
INSERT INTO OrderItem (OrderId, Id) VALUES (@p0, @p1)

We are responsible for keeping both sides of our two-way relationship in sync. In a normal class, we would add code in the property setter or the collection's add or remove methods to update the other end of the relationship automatically. NHibernate, however, throws exceptions when an object is manipulated while NHibernate is initializing it.

For this reason, it's suggested that we prevent direct manipulation of either end of the relationship, and instead use methods specifically written for this purpose, as we've done here with AddItem, RemoveItem, and SetOrder. Notice that we've mapped a set, which implies that order is not significant, and that duplicates are not allowed.

Notice the use of backticks in our table name from the Order mapping as follows:

<class name="Order" table="`Order`">

In Microsoft SQL Server, Order is a keyword. If we want to use it as an identifier, a table name in this case, NHibernate will need to put quotes around it. The backticks tell NHibernate to surround the identifier with whatever character may be appropriate for the database you're using.

By default, NHibernate will map an enumeration to a numeric field based on the enumeration's underlying type, typically an int. For example, if we set AcctType to AccountTypes.Corporate, the AcctType database field would hold the integer 2. This has one significant drawback. An integer value by itself doesn't describe the business meaning of the data.

One solution is to create a lookup table containing each enumeration value alongside a description, but this must be maintained in perfect sync with the application code because otherwise it can lead to serious versioning issues. Simply rearranging the order of the enumeration in code from one release to the next can have disastrous effects.

Another solution, the one shown here, is to store the name of the enumeration value in a string field. For example, if we set AcctType to AccountTypes.Corporate, the AcctType database field would hold the string value Corporate.

By specifying a type attribute for AcctType, we tell NHibernate to use a custom class for conversion between .NET types and the database. NHibernate includes EnumStringType<T> to override the conversion of enumeration values to database values so that the string name is stored, not the numeric value.

The type value NHibernate.Type.EnumStringType`1[[MappingEnums.AccountTypes, MappingEnums]], NHibernate is the assembly qualified name for NHibernate.Type.EnumStringType<AccountType>.

In this recipe, we can use the Address component class throughout our model without the overhead of maintaining a separate entity. We've used it in our Customer class for both billing and shipping address. The resulting database table will appear as shown in the next screenshot:

Our model looks like this:

We get all the reuse benefits without the database work. The Address fields are included in every query for Customer, and are automatically loaded.