nhibernate: what are the best practices for implementing equality?

Question

I think that Entities should implement equality by primary key comparison as default, but the nhibernate documentation recommends using business identity:

The most obvious way is to implement Equals()/GetHashCode() by comparing the identifier value of both objects. If the value is the same, both must be the same database row, they are therefore equal (if both are added to an ISet, we will only have one element in the ISet). Unfortunately, we can't use that approach. NHibernate will only assign identifier values to objects that are persistent, a newly created instance will not have any identifier value! We recommend implementing Equals() and GetHashCode() using Business key equality.

Business key equality means that the Equals() method compares only the properties that form the business key, a key that would identify our instance in the real world (a natural candidate key)

And the example (also from the doc):

public override bool Equals(object other)
{
    if (this == other) return true;

    Cat cat = other as Cat;
    if (cat == null) return false; // null or not a cat

    if (Name != cat.Name) return false;
    if (!Birthday.Equals(cat.Birthday)) return false;

    return true;
}

This got my head spinning because the notion of business identity (according to the example) is the same as comparison by syntax, which is basically the type of semantics I associate with ValueObjects. The reason for not using database primary keys as comparison values is because this will change the hashcode of the object if the primary key is not generated on the client side (for ex incremental) and you use some sort of hashtable collection (such as ISet) for storing your entities.

How can I create a good equality implementation which does not break the general rules for equality/hashcode (http://msdn.microsoft.com/en-us/library/bsc2ak47.aspx) and conforms to nhibernate rules as well?

Answer 1

This is a known issue with ORM. Here I outline the solutions I know about and give a few pointers.

1 Surrogate/primary key: auto-generated

As you mentionned, if the object has not been saved, this doesn't work.

2 Surrogate/primary key: assigned value

You can decide to assign the value of the PK in the code, this way the object has always an ID and can be used for comparison. See Don't let hibernate steal your identity.

3 Natural key

If the object has another natural key, other than the primary key, you can use this one. This would be the case for a client entity, which has a numeric primary key and a string client number. The client number identifies the client in the real world and is a natural key which won't change.

4 Object values

Using the object values for equality is possible. But is has other shortcomings has you mentioned. This can be problematic if the values changes and the object is in a collection. For instance, if you have a Set with two objects that were different at first, but then you change the values while they are reference in the set so that they become equal. Then you break the contract of the Set. See Hibernate equals and hashcode.

5 Mixed: value + autogenerate primary/surrogate keys

If the objects to compare have an ID already, use it. Otherwise, use the object values for comparison.

All have some pros and cons. IMHO, the best is 3, if it is possible with your domain model. Otherwise, I've used 5 and it worked, though there are still some trap when using collections. I never used 2 but that sounds also a sensible solution, if you find a way to generate the PK in the code. Maybe other people have pointers for this one.