The Inquisitive Coder - Davy Brion's Blog » NHibernate

Using NHibernate In Your Service Layer

Davy Brion — Fri, 11 Dec 2009 12:53:36 +0000

I have an old post where i discuss how you can manage your NHibernate sessions in a service layer scenario. Now, the example of the service layer code in that post was pretty poor and people were asking for a better example. Hopefully, this post will do a better job at making sure everything is clear

First of all, the idea is to make sure that managing the NHibernate session (creating it, starting a transaction, committing or rolling back the transaction and closing the session) is taken care of automatically so you no longer have to worry about it. I also want to avoid passing the NHibernate session around all the time. This means that it will be created automatically when a request is sent to your service layer and stored in some place that will keep the instance alive during the handling of the service layer request. Every class that needs a reference to the current session (ideally only classes that deal purely with data access) will be able to retrieve it very easily, all in a thread-safe manner that can never be influenced by other concurrent requests.

First of all, you need something to wrap NHibernate’s ISessionFactory. I use the ISessionProvider for that:

    public interface ISessionProvider
    {
        ISession Create();
    }
 
    public class SessionProvider : ISessionProvider
    {
        private readonly ISessionFactory sessionFactory;
 
        public SessionProvider(string mappingAssemblyName)
        {
            Configuration configuration = new Configuration()
                .Configure()
                .AddAssembly(mappingAssemblyName);
 
            sessionFactory = configuration.BuildSessionFactory();
        }
 
        public ISession Create()
        {
            return sessionFactory.OpenSession();
        }
    }

In my case, i configure the IOC container to pass the name of the assembly that contains the mappings to the constructor of the SessionProvider class. If you’re using this code directly in your application, you could just as well hardcode the name of the assembly here.

You’ll also need something that allows you to store and retrieve the NHibernate session for the duration of the current request. I use the IActiveSessionManager for that:

    public interface IActiveSessionManager
    {
        ISession GetActiveSession();
        void SetActiveSession(ISession session);
        void ClearActiveSession();
        bool HasActiveSession { get; }
    }
 
    public class ActiveSessionManager : IActiveSessionManager
    {
        private const string sessionKey = "_currentSession";
        private readonly IRequestState requestState;
 
        public ActiveSessionManager(IRequestState requestState)
        {
            this.requestState = requestState;
        }
 
        public ISession GetActiveSession()
        {
            if (Current == null)
            {
                throw new InvalidOperationException("There is no active ISession instance for this thread");
            }
 
            return Current;
        }
 
        public void SetActiveSession(ISession session)
        {
            if (Current != null)
            {
                throw new InvalidOperationException("There is already an active ISession instance for this thread");
            }
 
            Current = session;
        }
 
        public void ClearActiveSession()
        {
            Current = null;
        }
 
        public bool HasActiveSession
        {
            get { return Current != null; }
        }
 
        protected virtual ISession Current
        {
            get
            {
                return requestState.Get<ISession>(sessionKey);
            }
            set
            {
                requestState.Store(sessionKey, value);
            }
        }
    }

This class will store the ISession instance in the current request state (definitely click on that link if you don’t know IRequestState yet).

Now we can create our own Unit Of Work. This is not a pure Unit Of Work because it doesn’t do any change tracking or anything like that, but it does take care of creating an NHibernate session (which does do change tracking and anything that a real Unit Of Work should do) and cleaning it up when the Unit Of Work is completed. Here’s my implementation:

    public interface IUnitOfWork : IDisposable
    {
        void Clear();
        void Flush();
        ITransaction CreateTransaction();
        ITransaction CreateTransaction(IsolationLevel isolationLevel);
    }
 
    public class UnitOfWork : Disposable, IUnitOfWork
    {
        private readonly IActiveSessionManager sessionManager;
        private readonly ISession session;
        private readonly bool isRootUnitOfWork;
 
        public UnitOfWork(ISessionProvider sessionProvider, IActiveSessionManager sessionManager)
        {
            this.sessionManager = sessionManager;
 
            if (sessionManager.HasActiveSession)
            {
                isRootUnitOfWork = false;
                session = sessionManager.GetActiveSession();
            }
            else
            {
                isRootUnitOfWork = true;
                session = sessionProvider.Create();
                sessionManager.SetActiveSession(session);
            }
        }
 
        public void Clear()
        {
            session.Clear();
        }
 
        public void Flush()
        {
            session.Flush();
        }
 
        public ITransaction CreateTransaction()
        {
            return CreateTransaction(IsolationLevel.ReadCommitted);
        }
 
        public ITransaction CreateTransaction(IsolationLevel isolationLevel)
        {
            if (session.Transaction != null && session.Transaction.IsActive)
            {
                throw new InvalidOperationException("nested transactions are not supported!");
            }
 
            return session.BeginTransaction(isolationLevel);
        }
 
        protected override void DisposeManagedResources()
        {
            if (isRootUnitOfWork)
            {
                if (session != null)
                {
                    session.Close();
                    session.Dispose();
                }
 
                sessionManager.ClearActiveSession();
            }
        }
    }

The idea is very simple. When the Unit Of Work is created, it asks the IActiveSessionManager if there is already an active session available. If not, it will create a new session through the ISessionProvider, and store it as the active session through the IActiveSessionManager. In the old implementation, the Unit Of Work would automatically create a new session in the constructor, but this obviously causes problems if you want to reuse a certain request handler from another request handler if they both depend on a IUnitOfWork instance. The IUnitOfWork interface doesn’t expose a lot of functionality but it’s all you need to manage your session in your service layer. It gives you the ability to create a transaction, clear the session and flush the session. When the IUnitOfWork is disposed, it will clean up the session and instruct the IActiveSessionManager to get rid of the session for this request.

Once you have this, you have all you need to prepare your service layer to take care of NHibernate session management automatically. I’m going to base the following service layer code example on Agatha (just because i think it’s the easiest way to implement a service layer ) but you can do exactly the same in your service layer. The important part is that you should configure your IOC container to inject a new instance of IUnitOfWork into the class that handles your service request. When the container injects the new instance, the NHibernate session will be created and stored in the IActiveSessionManager so there’s no more reason why you would have to do this yourself.

Now, i use the following class as the base class for all my request handlers that need NHibernate support:

    public abstract class NhRequestHandler : RequestHandler
        where TRequest : Request
        where TResponse : Response
    {
        public IUnitOfWork UnitOfWork { get; set; }
 
        protected override void DisposeManagedResources()
        {
            if (UnitOfWork != null) UnitOfWork.Dispose();
        }
 
        public override Response Handle(Request request)
        {
            using (ITransaction transaction = UnitOfWork.CreateTransaction())
            {
                Response response;
 
                try
                {
                    response = base.Handle(request);
                    transaction.Commit();
                }
                catch (Exception handlerException)
                {
                    transaction.Rollback();
                    throw;
                }
 
                return response;
            }
        }
    }

(Note: the real implementation contains a bit more logging but other than that this is the real thing)

If you don’t understand the whole request handling concept, please check out the first 3 posts in this series. Regardless of whether you’re using Agatha, your own Request/Response Service Layer or a classic (dare i say old-school?) service layer, the idea should be the same. Make sure this code is centralized in one place so you don’t have to repeat yourself all over your service layer code. Btw, in this case the IUnitOfWork instance is injected by the IOC container through Setter Injection instead of Constructor Injection. I’ve already discussed the reasons on why i prefer Setter Injection in this case here.

Now, you’re going to have some classes that will need to use an ISession instance to perform their tasks. I always create Repository classes for that, but the following approach would be similar for any other type of class which needs an ISession. Call them Data Access Objects, Data Access Classes or Sloppy Joes for all i care. Whatever you call these classes, they need a dependency on the IActiveSessionManager. Simply declare the IActiveSessionManager to be a dependency of your Sloppy Joe, i mean, Repository or DAO or whatever, like this:

    public class Repository : IRepository
    {
        private readonly IActiveSessionManager activeSessionManager;
 
        public Repository(IActiveSessionManager activeSessionManager)
        {
            this.activeSessionManager = activeSessionManager;
        }
 
        protected ISession Session
        {
            get { return activeSessionManager.GetActiveSession(); }
        }

Now you can write request handlers like this:

    public class GetCustomersRequestHandler : NhRequestHandler<GetCustomersRequest, GetCustomersResponse>
    {
        private readonly IRepository<Customer> repository;
 
        public GetCustomersRequestHandler(IRepository<Customer> repository)
        {
            this.repository = repository;
        }
 
        public override Response Handle(GetCustomersRequest request)
        {
            var response = CreateTypedResponse();
            response.Customers = ConvertToDtos(repository.FindAll(request.Criteria));
            return response;
        }
 
        private CustomerDto[] ConvertToDtos(IEnumerable<Customer> customers)
        {
            // …
        }
    }

Obviously, this is a simple example but it works just as well for complex request handlers. Your NHibernate session is created and cleaned up automatically, without you having to write that code every single time. Each request handler will run in a transaction, and it will be committed or rolled back automatically without you having to do anything for it. And you only need to access the ISession instance in your Sloppy Joes.

Also keep in mind that you can also use the the ISessionProvider, IActiveSessionManager and IUnitOfWork in a purely web-based scenario as well if you want to.

Testing CRUD Operations With NHibernate

Davy Brion — Mon, 07 Dec 2009 11:38:02 +0000

I was asked to show how you can easily do CRUD tests, so here’s a base class that makes it very easy

    public abstract class CrudTest : NHibernateTest
        where TEntity : IHaveAnId
    {
        [Test]
        public virtual void SelectQueryWorks()
        {
            session.CreateCriteria(typeof(TEntity)).SetMaxResults(5).List();
        }
 
        [Test]
        public virtual void AddEntity_EntityWasAdded()
        {
            var entity = BuildEntity();
 
            InsertEntity(entity);
 
            session.Evict(entity);
 
            var reloadedEntity = session.Get(entity.Id);
 
            Assert.IsNotNull(reloadedEntity);
            AssertAreEqual(entity, reloadedEntity);
            AssertValidId(reloadedEntity);
        }
 
        [Test]
        public virtual void UpdateEntity_EntityWasUpdated()
        {
            var entity = BuildEntity();
 
            InsertEntity(entity);
            ModifyEntity(entity);
            UpdateEntity(entity);
 
            session.Evict(entity);
 
            var reloadedEntity = session.Get(entity.Id);
            Assert.IsNotNull(reloadedEntity);
            AssertAreEqual(entity, reloadedEntity);
        }
 
        [Test]
        public virtual void DeleteEntity_EntityWasDeleted()
        {
            var entity = BuildEntity();
 
            InsertEntity(entity);
            DeleteEntity(entity);
 
            Assert.IsNull(session.Get(entity.Id));
        }
 
        protected virtual void InsertEntity(TEntity entity)
        {
            session.Save(entity);
            session.Flush();
        }
 
        protected virtual void UpdateEntity(TEntity entity)
        {
            session.Update(entity);
            session.Flush();
        }
 
        protected virtual void DeleteEntity(TEntity entity)
        {
            session.Delete(entity);
            session.Flush();
        }
 
        protected abstract TEntity BuildEntity();
        protected abstract void ModifyEntity(TEntity entity);
        protected abstract void AssertAreEqual(TEntity expectedEntity, TEntity actualEntity);
        protected abstract void AssertValidId(TEntity entity);
    }

Simply inherit from this class, implement the BuildEntity, ModifyEntity, AssertAreEqual and AssertValidId methods and that’s it. Those methods are usually pretty simple. In BuildEntity you just create an unpersisted entity and assign values to the properties, in ModifyEntity you modify the properties, and in AssertAreEqual you compare the properties of both instances. In AssertValidId, you make sure that the ID value is ok (depending on your identifier strategy).

This is good for regular CRUD operations, though we typically add extra tests when we want to test cascades or one-to-many associations mapped with inverse=”true”.

Unit Testing An NHibernate Application

Davy Brion — Sun, 06 Dec 2009 19:21:13 +0000

Grant Palin recently asked me for an in-depth article on TDD’ing an NHibernate application. While this post won’t be very in-depth, it might be helpful already. There are basically two approaches that i’ve seen used with good results, though there are obviously more approaches that you can use. I’m going to limit the scope of this post to the following two approaches though, and i’ll also discuss exactly what we test.

Creating a new database for each test (or testfixture)

This approach creates the database at the beginning of each test (or testfixture), runs the test (or tests in the fixture), and then destroys the database after the test (or testfixture) completed. The easiest way to do this is to create a base test class that all of you data access test class should inherit from. Here’s a simple example:

    public class NHibernateTest
    {
        private Configuration configuration;
        protected ISessionFactory sessionFactory;
 
        [TestFixtureSetUp]
        public void TestFixtureSetup()
        {
            configuration = new Configuration()
                .Configure()
                .AddAssembly("YourAssemblyName");
 
            new SchemaExport(configuration).Create(false, true);
            sessionFactory = configuration.BuildSessionFactory();
        }
 
        [TestFixtureTearDown]
        public void TestFixtureTearDown()
        {
            new SchemaExport(configuration).Drop(false, true);
        }
 
        protected ISession CreateTransactionalSession()
        {
            var session = sessionFactory.OpenSession();
            session.BeginTransaction();
            return session;
        }
    }

This class will create the database from scratch once for each TestFixture, which means that each test in the fixture will use the same database. It also destroys the database at the end of the fixture. It creates the database based on your mappings, and as you can see, you really don’t have to do a lot for this. If you want the database to be recreated and dropped for each test, then you obviously need to move the code in the TestFixtureSetup and TestFixtureTearDown methods to your regular SetUp and TearDown methods. If you go that route, i’d advise you to include empty template methods before and after the setup and teardown so you can plug in some extra code before and after these operations in your derived test classes.

The biggest benefit of this approach is that you don’t have any possibly present state in the database that can influence your tests. The downside is that you can’t rely on certain data (eg reference data) to be present and you have to recreate it whenever you need it. You can also use multiple transactions in your tests, though you are also responsible for cleaning any data that is left in the database at the end of each test. You also need to guarantee that this always happens because any data that is left by one test might influence another one. Also, if you leave data in the database, that might lead to problems when dropping the database, so you really need to be careful with this.

Another problem with this example is that there is no automatic way to push the ISession instance to your data access components. That could easily be added though, depending on how your data access components retrieve a reference to a valid ISession.

Tests that automatically roll back their transactions

This is the approach that we always use at work. These tests require your database to be set up in a valid manner before your tests begin. Each test uses one transaction, which is automatically rolled back at the end of the test to prevent the possibility of any test data remaining in the database. With this way of testing, it’s also possible to provide some kind of ‘known state’ in the database (eg reference data) that you can use from within your code.

Here’s the NHibernateTest class that our NHibernate test classes all inherit from:

    public abstract class NHibernateTest
    {
        protected static readonly ActiveSessionManager activeSessionManager = new ActiveSessionManager();
 
        private UnitOfWork unitOfWork;
        protected ISession session;
 
        protected abstract ISessionProvider GetSessionProvider();
 
        protected virtual IActiveSessionManager GetActiveSessionManager()
        {
            return activeSessionManager;
        }
 
        [SetUp]
        public void SetUp()
        {
            BeforeSetup();
            var sessionManager = GetActiveSessionManager();
            unitOfWork = new UnitOfWork(GetSessionProvider(), sessionManager);
            session = sessionManager.GetActiveSession();
            unitOfWork.CreateTransaction();
            AfterSetup();
        }
 
        [TearDown]
        public void TearDown()
        {
            BeforeTearDown();
 
            if (unitOfWork != null)
            {
                unitOfWork.Dispose();
            }
 
            unitOfWork = null;
            AfterTearDown();
        }
 
        protected virtual void BeforeSetup() { }
        protected virtual void AfterSetup() { }
        protected virtual void BeforeTearDown() { }
        protected virtual void AfterTearDown() { }
    }

Now, this example uses our UnitOfWork and ActiveSessionManager classes (read this if you haven’t seen those yet) to make sure that our data access components can access the current ISession instance. Each test has a valid ISession present, which has already created a transaction and we can create/modify/delete data, run our queries, modify some stuff again, run our queries again and perform our assertions, all in the same transaction. After the test is completed, the transaction is never committed (and thus, automatically rolled back) so none of that data ever remains in the database.

What Exactly Do We Test?

Well, we test everything basically. We test all of our CRUD operations (again, with a simple base class which only requires you to implement the BuildEntity, ModifyEntity and AssertEqual methods and does all of the operations and checks automatically) for each entity. That’s right, for each entity. The extra work that this requires really doesn’t take a lot of time and it lets us know for a fact that our mappings are valid.

We also test every custom query that we write, always using the following approach: create some test data, flush the session, perform your query and verify that the expected data has indeed been returned by the query, and also that data that shouldn’t have been returned isn’t there.

And that’s pretty much it. We mock the data layer in all of our other tests, so our CRUD and query tests are the only ones that actually use NHibernate and the database. But CRUD actions and queries are tested very extensively.

Why NHibernate Entities Need A Public Or Protected Parameterless Constructor

Davy Brion — Sun, 04 Oct 2009 16:17:16 +0000

I have an older post where i discuss how you can implement a Value Object with NHibernate. In that post i mentioned the following:

NHibernate allows a private default constructor for Value Objects, but for Entities you will need a default public or protected constructor as private is not sufficient.

I got the following comment from someone:

I too am trying to determine how well NHibernate lives up to the promise of persistence ignorance. I can definitely live with unnecessary private constructors, but I’m dubious about adding protected constructors just to support an ORM.

At any rate, I was surprised by the sentence I quoted, because I didn’t realize there were any circumstances in which NHibernate required protected default constructors.

Once again, the answer is related to the dynamic proxies that NHibernate uses. Value Objects will never be proxied by NHibernate, so NHibernate only needs a private default constructor to create the instances. If an entity is eligible for lazy loading however, then NHibernate will create a type which inherits from your entity (this is described in depth here and here). Which means that we really need either a public or protected constructor in entity classes that are eligible for lazy loading. Consider the following class:




    public class SomeEntity
    {
        public SomeEntity(string someRequiredValue)
        {
        }
 
        private SomeEntity()
        {
        }
    }

If we try to create the following derived class:




    public class SomeEntityProxy : SomeEntity
    {
    }

We get the following compiler error:

Error 1 ‘ConsoleApplication1.SomeEntity.SomeEntity()’ is inaccessible due to its protection level

It’s a silly example, but it does show why entity types need at least a public or a protected default constructor and why a private one isn’t sufficient.

Must Everything Be Virtual With NHibernate, Part III

Davy Brion — Sun, 27 Sep 2009 17:45:30 +0000

In the previous post i showed a piece of code which suffers from 2 problems and asked you guys to spot both problems. One of the problems was pointed out in the comments, but nobody mentioned the other one.

Once again, this is the code example:

Instead of making everything virtual, only properties that are eligible for lazy-loading have been made virtual. Now, the line of code that is problematic is obviously the one where the DiscountPercentage of the customer backing field is accessed. I will address using the field instead of the property later on in this post so bear with me for now.

There are 2 situations in which this code will fail badly. The first situation is when you’re dealing with a proxy of an Order. If you have an uninitialized proxy of Order, and you call the non-virtual CreateOrderLine method then you will get a NullReferenceException because the proxy can’t intercept the call to CreateOrderLine, and because it also can’t intercept accessing the customer field, which will be null at that time. This problem was correctly spotted by one of the people who left a comment.

The other problem is far worse, IMO. Suppose you have a genuine instance of an Order object, but its reference properties haven’t been loaded yet and are uninitialized proxies. If there is no requirement for every public member of a proxy-able type to be virtual, then we can pretty much assume that the DiscountPercentage of the Customer class is also non-virtual. Which means that with this code, we have no possible way of intercepting the call to the Customer’s proxy’s DiscountPercentage property. Unfortunately, DiscountPercentage will have its default value of 0, so you won’t get an exception… instead, the customer gets no discount even though its record in the database might have a discount set.

The possibility of running into one of these problems due to usage of an ORM and depending on how an object is loaded is simply unacceptable. Some people commented on the usage of the customer backing field instead of the Customer property with a “then simply don’t do that” response. That’s not an acceptable solution to this problem, it’s a lame workaround at best. There are plenty of reasons why people would use the backing field in their code instead of the property and if they run into this problem, they definitely will blame the ORM. And rightfully so, i might add.

Must Everything Be Virtual With NHibernate, Part II

Davy Brion — Wed, 23 Sep 2009 04:56:34 +0000

I already tried to explain this before, but here’s a simple example from a presentation i recently did on NHibernate:

As you can see, only the properties of associations that are eligible for lazy-loading are virtual in this piece of code, because that is what many people seem to want. There are actually 2 different ways in which this can cause problems… can you spot both problems?

Slides Of My NHibernate Talk

Davy Brion — Thu, 10 Sep 2009 18:00:24 +0000

I’m giving a talk on NHibernate for the Belgian Visual Studio User Group right now (gotta love scheduled posts!). You can download the slides of the presentation here. I don’t like most typical technical presentations, so i wanted a slightly different approach. So this presentation probably isn’t like most presentations that you may be used to. This is also the first time i’m giving a ‘big’ talk for a group of people that i don’t know personally, so hopefully, it’ll be alright and i won’t screw up .

If i did screw up: sorry, but at least it was free :p

Of Course NHibernate Is Slow When You Use It Incorrectly

Davy Brion — Wed, 19 Aug 2009 20:48:36 +0000

Just saw the following post where the performance of NHibernate and Entity Framework is compared for a couple of different operations. Spoiler alert: NHibernate loses. As it typically does in these kinds of ‘benchmarks’ or ‘comparisons’ that seem to pop up frequently lately.

For some reason, a lot of people seem to think that opening an NHibernate session and performing thousands of operations is a valid use case. It’s not. Far from it actually. And with all of the features that NHibernate offers, it can’t possibly perform well in such a scenario. See, an NHibernate session is a unit of work. A unit of work is a business transaction which is typically short and small, but it should never be something huge. Your DBA probably won’t appreciate huge database transactions on the database either.

Whenever you load an object through NHibernate, it will be tracked by the session that loaded it. That means that the NHibernate session keeps a reference to it, and performs a series of checks on it periodically, depending on what you’re doing and some configuration settings such as the FlushMode. For instance, suppose you’ve loaded a hundred different entities in one session. If the FlushMode is set to automatic, it means that NHibernate will perform a dirty check for each entity associated with the session before each query is executed. The more entity instances you’ve loaded, the longer this takes (obviously). If you take this to an extreme level, like loading thousands of entities like most of these ‘benchmarks’ do, performance will naturally be horrible.

Each entity instance is also stored in the first level (or session level) cache. That means that whenever you retrieve a row from the database, NHibernate will check if an instance of that row already exists in the first level cache. Again, the more instances you’ve loaded, the larger the overhead of this will be. There are also a lot of possible extension points where you can plug in custom logic. Again, there is a very minor cost that comes with this extensibility and as you can expect, that minor cost can add up to something much more noticable once you start dealing with an unreasonably large number of instances in your session.

Always keep in mind that an ORM (and this goes for every ORM) is most suitable for OLTP. Using an ORM for batch processing jobs or large data processing operations in general is simply put a bad idea. And they will never perform as well as other solutions in these scenarios. So please don’t bother even benchmarking ORM performance in non OLTP usage because it quite simply doesn’t make sense to do so, and the results will be completely untrustworthy anyway.

An ORM can offer you nice performance gains in OLTP scenarios simply by trying to minimize database connectivity, minimizing the number of database operations, and relatively sane caching usage. Unfortunately, these are aspects that are never tested in these ‘benchmarks’ or ‘comparisons’.

One Of My Favorite NHibernate 2.1 Features

Davy Brion — Thu, 30 Jul 2009 09:38:16 +0000

Check out the following piece of code:


            Session.CreateQuery(
                @"delete from DocumentTypeAssignment
                  where Id.DmsDocument in (from DmsDocument where Id = :documentId) and
                        Id.DocumentType.Id not in (:newDocumentTypeIds)")
                .SetInt64("documentId", dmsDocumentId)
                .SetParameterList("newDocumentTypeIds", newDocumentTypesToAssign.ToList(), NHibernateUtil.Int64)
                .ExecuteUpdate();

(pay no attention to Id.DmsDocument or Id.DocumentType… it’s a composite key for a legacy table)

Which results in this SQL statement:


delete
    from
        DocumentManagement.DocumentTypeAssignment
    where
        (
            DmsDocumentID in (
                select
                    dmsdocumen1_.ID
                from
                    DocumentManagement.DmsDocument dmsdocumen1_
                where
                    dmsdocumen1_.ID=@p0
            )
        )
        and (
            DocumentTypeID not in  (
                @p1 , @p2
            )
        );
    @p0 = 1634, @p1 = 2313, @p2 = 2310

Avoid Using NHibernate With NUnit 2.4.6

Davy Brion — Wed, 24 Jun 2009 17:35:42 +0000

We just spent about 2 hours trying to find out why our NHibernate tests were about 10x slower on our build server than they were on our local machines. I had noticed lately that the build for one of our projects was taking longer and longer but i hadn’t really timed the difference. This project has about 1200 tests that use NHibernate and they run in about 45-60 seconds on my local machine. It turns out they took around 15 minutes on the buildserver when running them through TeamCity.

I logged into the buildserver and ran the tests manually using nunit’s console runner (with an NUnit-2.4.7 build that i happened to have installed somewhere on the machine) and they only took about 45 seconds. After a lot of guesswork and screwing around, it turned out that we never modified our base build script (why yes, i do believe in build script inheritance) to use a newer version of NUnit. We set up the buildserver about 1 year ago, and at that time, the latest stable NUnit version that TeamCity supported was NUnit 2.4.6. Our base build script was still referring to NUnit 2.4.6, which apparently sets log4net to use debug level logging. Now, NHibernate logs a huge amount of information at the debug level, so this turned out to slow down all of our builds that had NHibernate tests.

We changed the the 2.4.6 version in our script to 2.4.7 and the build time of this particular project decreased from around 50 minutes to about 35 minutes. Yes, that’s still a lot but this is a huge project with a lot of legacy tests and the entire build process is pretty complex. Other projects went from build times from around 7 minutes to about 2 minutes.

That’s a pretty nice improvement for simply changing a “6″ to a “7″

Using The Guid.Comb Identifier Strategy

Davy Brion — Thu, 21 May 2009 12:00:31 +0000

As you may have read by now, it’s a good idea to avoid identity-style identifier strategies with ORM’s. One of the better alternatives that i kinda like is the guid.comb strategy. Using regular guids as a primary key value leads to fragmented indexes (due to the randomness of the guid’s value) which leads to bad performance. This is a problem that the guid.comb strategy can solve quite easily for you.

If you want to learn how the guid.comb strategy really works, be sure to check out Jimmy Nilsson’s article on it. Basically, this strategy generates sequential guids which solves the fragmented index issue. You can generate these sequential guids in your database, but the downside of that is that your ORM would still need to insert each record seperately and fetch the generated primary key value each time. NHibernate includes the guid.comb strategy which will generate the sequential guids before actually inserting the records in your database.

This obviously has some great benefits:

you don’t have to hit the database immediately whenever a record needs to be inserted
you don’t need to retrieve a generated primary key value when a record was inserted
you can batch your insert statements

Let’s see how we can use this with NHibernate. First of all, you need to map the identifier of your entity like this:




    <id name="Id" column="Id" type="guid" >
      <generator class="guid.comb" />
    id>

And that’s actually all you have to do. You don’t have to assign the primary key values or anything like that. You don’t need to worry about them at all.

Take a look at the following test:




        [Test]
        public void InsertsAreOnlyExecutedAtTransactionCommit()
        {
            var insertCountBefore = sessionFactory.Statistics.EntityInsertCount;
 
            using (var session = sessionFactory.OpenSession())
            using (var transaction = session.BeginTransaction())
            {
                for (int i = 0; i < 50; i++)
                {
                    var category = new ProductCategory(string.Format("category {0}", i + 1));
                    // at this point, the entity doesn't have an ID value yet
                    Assert.AreEqual(Guid.Empty, category.Id);
                    session.Save(category);
                    // now the entity has an ID value, but we still haven't hit the database yet
                    Assert.AreNotEqual(Guid.Empty, category.Id);
                }
 
                // just verifying that we haven't hit the database yet to insert the new categories
                Assert.AreEqual(insertCountBefore, sessionFactory.Statistics.EntityInsertCount);
                transaction.Commit();
                // only now have the recors been inserted
                Assert.AreEqual(insertCountBefore + 50, sessionFactory.Statistics.EntityInsertCount);
            }
        }

Interesting, no? The entities have an ID value after they have been ’saved’ by NHibernate. But they haven’t actually been saved to the database yet though. NHibernate always tries to wait as long as possible to hit the database, and in this case it only needs to hit the database when the transaction is committed. If you’ve enabled batching of DML statements, you could severly reduce the number of times you need to hit the database in this scenario.

And in case you’re wondering, the generated guids look like this:

81cdb935-d371-4285-9dcb-9bdb0122f25f
a44baf99-58e9-4ad7-9a59-9bdb0122f25f
a88300c2-6d64-4ae3-a55b-9bdb0122f25f
032c7884-da2f-4568-b505-9bdb0122f25f
….
70d7713c-b38d-4341-953d-9bdb0122f25f

Notice the last part of the guids… this is what prevents the index fragmentation.

Obviously, this particular test is not a realistic scenario but i’m sure you understand how much of an improvement this identifier strategy could provide throughout an entire application. The only downside (IMO) is that guid’s aren’t really human readable so if that is important to you, you should probably look into other identifier strategies. The HiLo strategy would be particularly interesting in that case, but we’ll cover that in a later post

Using SQL Functions in Criteria Restrictions

Davy Brion — Thu, 30 Apr 2009 11:31:53 +0000

A coworker needed to use a SQL function in the where clause of a query that he was creating with NHibernate’s ICriteria API. Most examples of this on the web use HQL instead of the ICriteria API and since we primarily use the ICriteria API we looked into how to do this.

Turns out it is pretty simple to do, though the syntax isn’t really straightforward. Suppose you want to query all of your employees who are born in a specific year. You could mess around with some DateTime parameters, but most databases have SQL functions to get the year from a date. Using the ICriteria API, this would look like this:



            var employeesBornIn81 = session.CreateCriteria<Employee>()
                .Add(Restrictions.Eq(Projections.SqlFunction("year", NHibernateUtil.DateTime, Projections.Property("BirthDate")), 1981))
                .List<Employee>();

which adds the following where clause to the SQL statement (on SQL Server 2005):

WHERE datepart(year, this_.BirthDate) = @p0;

NHibernate’s Future Queries And Their Fallback Behavior

Davy Brion — Mon, 13 Apr 2009 18:07:55 +0000

I’ve blogged about NHibernate’s Future queries a couple of times already. But as you know, NHibernate aims to offer you a way to write your code completely independent of the actual database you’re using. So what happens if you run your code, which is using the Future and FutureValue features, on a database that doesn’t support batched queries? Previously, this would fail with a NotSupportedException being thrown.

As of today, (revision 4177 if you want to be specific) this is no longer the case. If you use the Future or FutureValue methods of either ICriteria or IQuery, and the database doesn’t support batching queries, NHibernate will fall back to simply executing the queries immediately, as the following tests show:




        [Test]
        public void FutureOfCriteriaFallsBackToListImplementationWhenQueryBatchingIsNotSupported()
        {
            using (var session = sessions.OpenSession())
            {
                var results = session.CreateCriteria<Person>().Future<Person>();
                results.GetEnumerator().MoveNext();
            }
        }




        [Test]
        public void FutureValueOfCriteriaCanGetSingleEntityWhenQueryBatchingIsNotSupported()
        {
            int personId = CreatePerson();
 
            using (var session = sessions.OpenSession())
            {
                var futurePerson = session.CreateCriteria<Person>()
                    .Add(Restrictions.Eq("Id", personId))
                    .FutureValue<Person>();
                Assert.IsNotNull(futurePerson.Value);
            }
        }

There are more tests obviously, but you get the point. The interesting part about these tests is how i disabled query batching support. I only have Sql Server and MySQL running on this machine, and they both support query batching. I didn’t really feel like installing a database that doesn’t support it, so i just took advantage of NHibernate’s extensibility. Since most of us run the NHibernate tests on Sql Server, i inherited from the Sql Server Driver and made sure that it would report to NHibernate that it didn’t support query batching:




    public class TestDriverThatDoesntSupportQueryBatching : SqlClientDriver
    {
        public override bool SupportsMultipleQueries
        {
            get { return false; }
        }
    }

Easy huh? Then i just inherited from the TestCase class we have in the NHibernate.Tests project which offers a virtual method where you can modify the NHibernate configuration for the current fixture:




        protected override void Configure(Configuration configuration)
        {
            configuration.Properties[Environment.ConnectionDriver] = 
                "NHibernate.Test.NHSpecificTest.Futures.TestDriverThatDoesntSupportQueryBatching, NHibernate.Test";
            base.Configure(configuration);
        }

Now NHibernate thinks that query batching isn’t supported, yet the above tests still work. Mission accomplished

Assigning Foreign Keys In NHibernate

Davy Brion — Fri, 03 Apr 2009 05:46:52 +0000

This post from the Entity Framework team recently caught my attention. It discusses the ability to add actual foreign key values to your entities instead of just references to the referred entities. One of the benefits of this ability is that you can assign foreign key values to an entity’s properties without having to actually retrieve the entity you are referring to. While i am no fan of this approach, i do want to point out that you can do this with NHibernate too, especially because some people don’t know about this.

Take a look at the following code:




                product.Category = session.Get<ProductCategory>(categoryId);
                session.SaveOrUpdate(product);

This code changes the product’s Category property, and to do that it retrieves the actual ProductCategory instance through the id value of the category. This causes 2 database hits. One to retrieve the ProductCategory, and one to persist the Product.

You could do this instead:




                product.Category = session.Load<ProductCategory>(categoryId);
                // this verifies that the product.Category is an uninitialized proxy
                // which means that we did not fetch the product category from the database
                Assert.IsFalse(NHibernateUtil.IsInitialized(product.Category));
                // we were able to save the product without having loaded the product category
                session.Save(product);

Notice how we use ISession’s Load method here, instead of the Get method to ‘retrieve’ the ProductCategory. The Get method actually fetches the entity from the database if it’s not already in the session cache. The Load method however will return an uninitialized proxy to the ProductCategory entity if it’s not present in the session cache. The NHibernateUtil.IsInitialized() method will return false, because this proxy is indeed uninitialized. It does not hit the database until you try to access any of the properties of the ProductCategory proxy, except for its identifier property. So accessing product.Category.Id would not hit the database, but product.Category.Name or product.Category.Description would.

If you want to avoid hitting the database to assign foreign keys, using a proxy might be an interesting alternative for you.

Transparent Query Batching Through Your Repository

Davy Brion — Wed, 01 Apr 2009 11:35:52 +0000

All of our projects that use NHibernate (which is all of them except those where the customer explicitly doesn’t want us to use it or where it wouldn’t make sense to use it) use the same Repository implementation. After the Future and FutureValue queries were added to NHibernate, i modified the implementation of that Repository class.

Two of the FindAll methods now look like this:




        public virtual IEnumerable FindAll()
        {
            return Session.CreateCriteria().Future();
        }
 
        public virtual IEnumerable FindAll(DetachedCriteria criteria)
        {
            return criteria.GetExecutableCriteria(Session).Future();
        }

The only thing i changed in those methods is calling the Future method, instead of the List method. That’s it. All of our specific Find-methods (those that execute specific queries) pass through the FindAll(DetachedCriteria criteria) method so they all benefit from this change.

That means that all of our queries are suddenly batched transparently whenever possible, without impacting any of the calling code. And that is pretty nice if you ask me. Batching queries can offer a substantial performance benefit, and we didn’t even have to change any of the calling code to achieve it.

Obviously, this only works for the queries that return IEnumerables (in our case, that’s every query that doesn’t return a single value). I also added a few more methods to enable query batching for queries that return a single entity, or a scalar value (i kept the original methods in this code snippet as well so you can see the difference):




        public virtual T FindOne(DetachedCriteria criteria)
        {
            return criteria.GetExecutableCriteria(Session).UniqueResult();
        }
 
        public virtual IFutureValue FindFutureOne(DetachedCriteria criteria)
        {
            return criteria.GetExecutableCriteria(Session).FutureValue();
        }
 



        public virtual K GetScalar(DetachedCriteria criteria)
        {
            return (K)criteria.GetExecutableCriteria(Session).UniqueResult();
        }
 
        public virtual IFutureValue GetFutureScalar(DetachedCriteria criteria)
        {
            return criteria.GetExecutableCriteria(Session).FutureValue();
        }
 



        public virtual int Count(DetachedCriteria criteria)
        {
            return Convert.ToInt32(QueryCount(criteria).GetExecutableCriteria(Session).UniqueResult());
        }
 
        public virtual IFutureValue<int> FutureCount(DetachedCriteria criteria)
        {
            return QueryCount(criteria).GetExecutableCriteria(Session).FutureValue<int>();
        }

So let’s recap. Queries that return IEnumerables are all batched transparently whenever it’s possible to do so. No calling code had to be modified to get this benefit. Queries that return single values (an entity instance or a scalar value) that still use the ‘old’ FindOne, GetScalar and Count methods obviously couldn’t benefit from the transparent batching without breaking backwards compatibility, but the new methods that were introduced do enable transparent batching for these queries from now on.

Does all of this sound too good to be true? I’d be skeptic too if i were you but i made these changes a few months ago actually and we have been using this stuff on a couple of projects with zero problems.

Obviously, you need NHibernate 2.1 Alpha 1 (or later) for this or the current trunk, both of which i would recommend over NH 2.0 at this point.

Must Everything Be Virtual With NHibernate?

Davy Brion — Mon, 30 Mar 2009 20:05:11 +0000

If you’ve ever used NHibernate 2.0 or later, you will have undoubtedly run into the following runtime exception a couple of times:

NHibernate.InvalidProxyTypeException: The following types may not be used as proxies:
NHibernateExamples.Entities.OrderLine: method get_UnitPrice should be ‘public/protected virtual’ or ‘protected internal virtual’
NHibernateExamples.Entities.OrderLine: method set_UnitPrice should be ‘public/protected virtual’ or ‘protected internal virtual’

Oops… we forgot to make the UnitPrice property on the OrderLine entity virtual. But why does it need to be virtual in the first place? That’s a question that many people who are new to NHibernate have.

The quick answer to that question is: because we need members to be virtual in order to do our lazy loading magic/voodoo.

The longer answer is more interesting though. An important feature that any real ORM must have is transparent Lazy Loading. If you retrieve an object through an ORM, you don’t want it to automatically pull in an entire object graph (not by default anyway), yet you don’t want to litter your code with checks to see if certain associations have been loaded yet, and then loading them if necessary. This is the ORM’s responsibility. Ideally, you want to be able to access properties and have the ORM load the necessary data upon first access of those properties if the data hasn’t been retrieved yet.

NHibernate has this ability, yet it doesn’t require you to inherit from some kind of NHibernate base class or implement any interfaces or anything like that. So how does it work? Well, NHibernate uses proxies of your classes at runtime whenever lazy loading is required. Ok, so what exactly is a proxy? In this case, an NHibernate proxy is a type which is generated dynamically when NHibernate is initialized for your application (this only happens once upon application startup). A proxy type will be generated for each of your entities that hasn’t explicitly been mapped to avoid lazy loading (more on this later). A proxy type for one of your entities will actually inherit from your entity, and will then intercept each possible call you can perform on that type.

Let’s discuss a small example that might make things clearer. Suppose you have an Order class. The Order class has properties such as Employee and Customer, among others. But when you load Order instances, you might not always want the Employee property to already contain the real Employee entity instance. Same thing goes for the Customer property. By default, NHibernate considers each entity type as eligible for lazy loading unless it’s been explicitly configured not to (again, more on this later). So when NHibernate is initialized, it will know that it needs to dynamically generate proxy types for Customer and Employee. Let’s just assume these types will be named CustomerProxyType and EmployeeProxyType (they wouldn’t be called like that btw, but it doesn’t matter). Now suppose that you are retrieving an Order instance (or a bunch of them, doesn’t really matter) and you don’t instruct NHibernate to already fetch the Customer or Employee data. You haven’t requested the Customer or Employee data, so it shouldn’t be there, right? But it shouldn’t be null either, right? So NHibernate assigns an instance of the CustomerProxyType class to the Customer property, and an instance of EmployeeProxyType and initializes both proxies so that they contain their identifier value, which you already have in memory anyway after selecting the order record.

You can safely use the Order instance(s) and you can even access the Employee and Customer instances and nothing will happen. But, whenever you access any of the non-identifier members (that means properties _and_ methods) of a proxy instance, NHibernate needs to make sure that the data of either the Customer or the Employee (depending on which one you’re using) needs to be fetched from the database. So how does NHibernate do that? The proxies will override all of your properties and methods and when one of them is accessed, NHibernate will either fetch the data of the entity if it’s not present yet and then proceed with the original implementation of the property or the method, or it will immediately call the original implementation if the data was already present.

This is basic OO… your entities are base classes to NHibernate’s proxies, and those proxies need to add a little bit of behavior to your entities’ behavior. In order to do that, NHibernate needs to override every public member to make sure that this extra behavior is triggered at the appropriate time. Now, there are quite a few people who dislike this requirement. First of all, there is a minor performance cost to calling virtual members as opposed to calling non virtual members. However, this performance cost is really extremely small and in practically every situation it’s completely negligible. This extra cost certainly doesn’t even compare to some real world performance costs, like hitting the database more often than you should or retrieving more data than you really need. Another reason why some people don’t like this is because they don’t like to enable derived classes to override whatever member they want to. In some cases, this is a valid objection. In most cases however, it’s pure Intellectual Masturbation which offers no real value at all. There are other ORM’s that don’t require you to make your members virtual and they are still able to offer lazy loading features. But those ORM’s usually require you to either inherit from a specified base class, or to implement one or more interfaces that the ORM will use. In both cases, i’d argue that this pollutes your entities far more than virtual members do, but that’s just my opinion.

But for those cases where you really do not want to make members virtual, and don’t mind forgoing on the lazy-loading features of NHibernate, you can simply map those entities to not enable lazy loading at all. You could just map an entity like this:




  <class name="OrderLine" table="OrderLine" lazy="false" >

Setting the lazy attribute to false will ensure that NHibernate will not create a proxy type of your entity type, and that you will always be dealing with instances of the actual type of your entity instead of a possible proxy type. It also means that you will never be able to use any kind of lazy loading when it comes to retrieving instances of these entity types.

Avoiding MySQL’s MAX_JOIN_SIZE Limit With NHibernate

Davy Brion — Mon, 30 Mar 2009 11:26:51 +0000

We’re working on an application which has to use a legacy MySQL database. So far, we haven’t really had any problems with MySQL (apart from the dreadful legacy schema but that’s another issue) but today, i started getting an exception with the following message:

The SELECT would examine more than MAX_JOIN_SIZE rows; check your WHERE and use SET SQL_BIG_SELECTS=1 or SET SQL_MAX_JOIN_SIZE=# if the SELECT is okay

There is a certain complex view in our application which apparently hits this default limit set by MySQL once there is a certain amount of data present. The view itself is a costly one… it really does need to do a whole lot of joins and rewriting it to use less joins would probably take a long time.

So i figured the better option in this case would be to set the SQL_BIG_SELECTS option to 1. The only problem was: how? It’s not a setting that you can pass through the connection string (or at least, i did not find a way to do so) and NHibernate is taking care of all of the database communication.

I remembered a trick i had used earlier, which is to extend NHibernate’s DriverConnectionProvider. It could then set the setting with the appropriate value whenever the connection is opened, like this:



    public class CustomConnectionProvider : NHibernate.Connection.DriverConnectionProvider
    {
        public override IDbConnection GetConnection()
        {
            IDbConnection connection = base.GetConnection();
            EnableBigSelects(connection);
            return connection;
        }
 
        private void EnableBigSelects(IDbConnection connection)
        {
            using (var command = connection.CreateCommand())
            {
                command.CommandText = "SET SQL_BIG_SELECTS=1";
                command.ExecuteNonQuery();
            }
        }
    }

After that, you just set the DriverConnectionProvider to use in your hibernate.cfg.xml file like this:



    <property name="connection.provider">MyProject.Infrastructure.NHibernate.CustomConnectionProvider, MyProjectproperty>

And all is well.

Implementing A Value Object With NHibernate

Davy Brion — Wed, 25 Mar 2009 22:12:06 +0000

I’ve covered implementing a Value Object before, but this post is about using Value Objects with NHibernate. First, a little recap of what a Value Object is for those who don’t know yet.

A Value Object (also known as Immutable Object) is basically an object without a conceptual identity. A Value Object is defined through its inner values, and not an identity like Entities. This means that a Value Object’s inner values can not be changed after object creation, hence the term Immutable Object. Should you need to change the inner values of the Value Object, you should actually create a new Value Object.

For some of you, this might seem odd. But you’ve actually used Value Objects on many occasions already. In .NET, strings are Value Objects. So are DateTime instances. If you create a string, you can’t modify its inner value. If you do, a new string is actually created. Same thing with a DateTime. The DateTime class provides methods to add days, hours, seconds, whatever… but those methods never modify the instance’s inner value. Instead, they return a new DateTime object because each DateTime instance is immutable.

This has interesting consequences on object equality. Two Value Objects holding the same data should be considered identical objects, even though they are 2 different instances. A Value Object should therefore properly implement the Equals and GetHashCode methods.

For this example, we’ll define a Name class, which is a Value Object consisting of 2 values: FirstName and LastName. If 2 people have the same first and last name, you could say that they have the same ‘name’, right? We’ll just ignore middle names here… The combination of a FirstName and LastName would make for a good Value Object. We need to make sure that once an instance of the Name class has been created, none of its values can be modified. We also need to make sure that multiple instances of the Name class that have the same values can be safely considered equal to each other. The code of the Name class looks like this:




    public class Name : IEquatable<Name>
    {
        private readonly string firstName;
        private readonly string lastName;
 
        public Name(string firstName, string lastName)
        {
            this.firstName = firstName;
            this.lastName = lastName;
        }
 
        // the default constructor is only here for NH (private is sufficient, it doesn't need to be public)
        private Name() : this(string.Empty, string.Empty) {}
 
        public string LastName
        {
            get { return lastName; }
        }
 
        public string FirstName
        {
            get { return firstName; }
        }
 
        public bool Equals(Name other)
        {
            if (ReferenceEquals(null, other)) return false;
            if (ReferenceEquals(this, other)) return true;
            return Equals(other.firstName, firstName) && Equals(other.lastName, lastName);
        }
 
        public override bool Equals(object obj)
        {
            if (ReferenceEquals(null, obj)) return false;
            if (ReferenceEquals(this, obj)) return true;
            if (obj.GetType() != typeof(Name)) return false;
            return Equals((Name)obj);
        }
 
        public override int GetHashCode()
        {
            unchecked
            {
                return (firstName.GetHashCode() * 397) ^ lastName.GetHashCode();
            }
        }
 
        public static bool operator ==(Name left, Name right)
        {
            return Equals(left, right);
        }
 
        public static bool operator !=(Name left, Name right)
        {
            return !Equals(left, right);
        }
    }

Take a close look at the constructors. The public constructor takes both required values (firstName and lastName), and assigns them to the private fields. The default constructor (which we’ve made private) merely calls the public constructor and passes String.Empty to the public constructor’s parameters. As you can gather from the comments on the private constructor, it’s only reason for existence is because NHibernate requires classes to have a default constructor. Well actually, that’s not entirely accurate since it is possible to use classes without a default constructor but it’s not trivial do so.

Creating a private default constructor seems to be a reasonable alternative. Developers can’t create invalid Name instances (unless they cheat with reflection), and NHibernate can use the private constructor so it can create the instances before it fills the fields with the values from the database.

Note: NHibernate allows a private default constructor for Value Objects, but for Entities you will need a default public or protected constructor as private is not sufficient.

We can now use this Value Object in every entity we want by simply adding a property to the entity like this:




        public virtual Name Name { get; set; }

The mapping of the Value Object must be added to the mapping of the entity like this:




    <component name="Name" class="NHibernateExamples.Values.Name" insert="true" update="true">
      <property name="FirstName" column="FirstName" type="string" length="50" not-null="true" access="nosetter.camelcase" />
      <property name="LastName" column="LastName" type="string" length="50" not-null="true" access="nosetter.camelcase" />
    component>

Notice the value of the access attribute. It’s set to nosetter.camelcase. That means that NHibernate will use the get property when reading the values, but it will use a camelcase private field to set the values when it’s creating the object with values from the database.

Entities: Required Properties And Properties That Shouldn’t Be Modified

Davy Brion — Tue, 24 Mar 2009 19:48:26 +0000

How often do you see entities mapped with getters and setters for every property, and only a default constructor (either added implicitly by the compiler or explicitly by a developer)? It’s not really the best way to map entities, so i just wanted to show a better way of doing this.

Consider the OrderLine entity. It has 4 required properties: Order, Product, UnitPrice and Quantity. It also has one optional property called DiscountPercentage. The Order and Product properties should never be changed after the OrderLine was created. It also has a database Id property which should never be changed either.

This is how the code of the OrderLine class would look like:




    public class OrderLine : IIdentifiable<int>
    {
        public OrderLine(Order order, Product product, decimal unitPrice, int quantity)
        {
            if (order == null) throw new ArgumentNullException("order"); 
            if (product == null) throw new ArgumentNullException("product");
 
            this.order = order;
            this.product = product;
            UnitPrice = unitPrice;
            Quantity = quantity;
        }
 
        // required for NH
        protected OrderLine() {}
 
        private int id;
 
        public virtual int Id
        {
            get { return id; }
        }
 
        private Order order;
 
        public virtual Order Order
        {
            get { return order; }
        }
 
        private Product product;
 
        public virtual Product Product
        {
            get { return product; }
        }
 
        public virtual decimal UnitPrice { get; set; }
        public virtual int Quantity { get; set; }
        public virtual double? DiscountPercentage { get; set; }
    }

There is only one public constructor, which takes all of the required properties as parameters. The protected constructor is only there because NHibernate needs it to create run-time proxies (which enable all of the lazy-loading magic). In theory, you can’t create instances of the OrderLine entity without its required data.

Also, notice how the Id, Order and Product properties only have a getter, and no setter. These values can no longer be changed by developers once the object is constructed. The UnitPrice and Quantity properties do have setters, because these values can be modified after the entity is created.

The mapping for this class looks like this:




  <class name="OrderLine" table="OrderLine" >
    <id name="Id" column="Id" type="int" access="nosetter.camelcase" >
      <generator class="identity" />
    id>
 
    <many-to-one name="Order" column="OrderId" class="Order" not-null="true" access="nosetter.camelcase" />
    <many-to-one name="Product" column="ProductId" class="Product" not-null="true" access="nosetter.camelcase" />
    <property name="UnitPrice" column="UnitPrice" type="Decimal" not-null="true" />
    <property name="Quantity" column="Quantity" type="int" not-null="true" />
    <property name="DiscountPercentage" column="DiscountPercentage" type="double" />
  class>

It’s pretty easy… each property that shouldn’t be changed after creation is mapped with the nosetter.camelcase access strategy. That means NHibernate uses the private field to set the value directly after creation, but will use the getters whenever it needs to read the data from the entity.

As you can see, without too much trouble you can make sure that your entities always have their required data, and that properties that shouldn’t change after creation can’t be modified either.

What Would You Like To See In My Upcoming NHibernate Examples?

Davy Brion — Sun, 22 Mar 2009 15:35:53 +0000

The original version of my NHibernate Mapping Examples was pretty popular, but they were based on NHibernate 1.2 and only showed some of the basics. I have plans to create a completely new version of these examples based on NHibernate 2.1. I want the examples to be suitable for people who are entirely new to NHibernate as an easy way to learn, as well as offering value to experienced NHibernate users by showing off some more advanced features.

It would be a downloadable Visual Studio solution, consisting of 2 projects. One being the mapping files and the POCO’s, the other being a test (as in: consisting of automated tests) project which would contain the code of various usage scenarios to demonstrate various features of NHibernate.

I already have some ideas of stuff i definitely want in these examples, but i’d also like to hear from you what you would like to see in these examples. So, if there is anything you’d like to see in there, let me know

Obviously, i can’t promise that everything you ask for will be included but i’ll try anyway