Optimistic-lock is a setting that can be applied on an entity during its mapping. As of version 4.0 of NHibernate, this setting can only be applied through XML mapping. Support for mapping by code is still being built and is expected to be out in version 4.1. Optimistic-lock takes two values – Dirty and All. Let's jump into an example to see what these mean. Following is a partial XML mapping for Employee that shows how to specify the optimistic-lock setting:

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

Note that besides setting the optimistic-lock attribute, we have also set the dynamic-update attribute to true. For optimistic locks to work, it is required to turn on the dynamic updates. With the preceding mapping in place, let's say we execute the following code:

using (var tx = Database.Session.BeginTransaction())
{
  var emp = Database.Session.Get<Employee>(id);
  emp.Firstname = "Hillary";
  emp.Lastname = "Gamble";
  tx.Commit();
}

In the preceding code, we are updating Firstname and Lastname on the Employee instance. Following SQL is generated by the preceding code:

UPDATE
  Employee
    SET
      Firstname = @p0,
      Lastname = @p1
    WHERE
      Id = @p2 
      AND Firstname = @p3
      AND Lastname = @p4;
      @p0 = 'Hillary', @p1 = 'Gamble', @p2 = 10649600, @p3 = 'John', @p4 = 'Smith'

The preceding update statement has used an additional WHERE clause to match the Firstname and Lastname column values of the record being updated to the original values that were loaded from the database. If some other database transaction has changed those values, then our update would not succeed and a NHibernate.StaleObjectException would be thrown. Also note that we have turned on the dynamic-updates. It makes sense to use dirty setting of optimistic-lock along with dynamic-updates. You are only validating and updating what has changed and not everything.

If you would rather validate all the columns of the entity instead of just the ones that are changed, then you can use the optimistic-lock setting to all, as shown next:

<class name="Employee" optimistic-lock="all"
dynamic-update="true">

Using this setting, the same previous code would generate the following SQL:

UPDATE
    Employee
  SET
    Firstname = @p0,
    Lastname = @p1
  WHERE
    Id = @p2
    AND EmployeeNumber is null
    AND Firstname = @p3 
    AND Lastname = @p4 
    AND EmailAddress is null
        AND DateOfBirth = @p5
        AND DateOfJoining = @p6
        AND IsAdmin = @p7
        AND Password is null;
    @p0 = 'Hillary', @p1 = 'Gamble', @p2 = 10682368, @p3 = 'John', @p4 = 'Smith', @p5 = 05/03/1972 00:00:00, @p6 = 28/05/2001 00:00:00, @p7 = False

Another way to use optimistic concurrency control is to use a Version property on the entity which mapped using a special mapping construct. The Version property could be something simple similar to an integer, as shown in the following code snippet:

public class Employee : EntityBase<Employee>
{
  //other properties on Employee class

  public virtual int Version { get; set; }
}

And following is how we map this Version property:

public class EmployeeMappings : ClassMapping<Employee>
{
  public EmployeeMappings()
  {
    Version(e => e.Version, versionMapper =>
    {
      versionMapper.Generated(VersionGeneration.Never);
    });
  }
}

We have got a special method Version that takes in two lambda expressions as its input. First one expects a lambda to the property that is to be used for version tracking. Second lambda expression uses an instance of NHibernate.Mapping.ByCode.IVersionMapper to further configure the mapping of Version. There are several mapping options available here which I would like to leave to you to explore further. The only one that I have used and which is important is the IVersionMapper.Generated method. It is used to tell NHibernate whether we are expecting the database to generate the value for the version column or should NHibernate itself generate that value. This is specified by using enumeration NHibernate.Mapping.ByCode.VersionGeneration. A value of Never means that the database never generates this value and NHibernate should generate it instead.

Another value Always is used to tell NHibernate that it can leave the version generation to the database.

With this mapping in place, when we save a transient Employee instance, the following SQL is generated:

INSERT INTO Employee 
            ( 
                        Version, 
                        EmployeeNumber, 
                        Firstname, 
                        Lastname, 
                        EmailAddress, 
                        DateOfBirth, 
                        DateOfJoining, 
                        IsAdmin, 
                        Password, 
                        Id 
            ) 
            VALUES 
            ( 
                        @p0, 
                        @p1, 
                        @p2, 
                        @p3, 
                        @p4, 
                        @p5, 
                        @p6, 
                        @p7, 
                        @p8, 
                        @p9 
            );
@p0 = 1, @p1 = NULL, @p2 = 'John', @p3 = 'Smith', @p4 = NULL, 
@p5 = 01/01/0001 00:00:00, @p6 = 01/01/0001 00:00:00, 
@p7 = false, @p8 = NULL, @p9 = 11

Note that NHibernate has automatically generated and inserted a value for the Version column. If the preceding record is updated, then NHibernate would generate the following SQL:

UPDATE Employee
SET Version = @p0,
  Firstname = @p1,
  Lastname = @p2
WHERE Id = @p3
AND Version = @p4;@p0 = 2, @p1 = 'Hillary',
@p2 = 'Gamble', @p3 = 11, @p4 = 1

When this record was loaded from the database, Version had a value of 1. The Update statement generated by NHibernate increments that value to 2. At the same time, a check is being made that the version column in the database still has a value of 1. If some other transaction had updated the same record in the meantime, then the Version column would have had a different (incremented) value and the update statement would have failed, resulting in a NHibernate.StaleObjectException. When this update succeeds, then any other transaction that holds stale record would fail with NHibernate.StaleObjectException.

Using a numeric value for version tracking works nicely. But if there are database inserts happening that are not going to through NHibernate then you need to make sure that version is correctly inserted and updated. A database such as MS SQL offers a special column of type ROWVERSION which is automatically generated every time a new record is inserted and updated when the record is updated. You can make use of this feature of MS SQL Server and extend your concurrency control beyond NHibernate. NHibernate supports this native database feature via its user defined version type feature.

In order to make use of MS SQL's timestamp-based versioning of the database records, we would need to declare a version property of type byte[], shown as follows:

public virtual byte[] RowVersion { get; set; }

We then map this property as a version property, as shown in the following code snippet:

Version(e => e.RowVersion, versionMapper =>
{
  versionMapper.Generated(VersionGeneration.Always);
  versionMapper.UnsavedValue(null);
  versionMapper.Type<BinaryTimestamp>();
  versionMapper.Column(v =>
  {
    v.SqlType("timestamp");
    v.NotNullable(false);
    });
  });

We are telling NHibernate that versions are always generated by database. We are also telling NHibernate that the database type of the version column on database side is timestamp. The most important bit is the declaration of BinaryTimestamp as the type to be used for conversion from database's timestamp value to byte[] used in code. You can find the code for the BinaryTimestamp class in the accompanying code for this chapter.