We develop a highly customizable application, where it is expected that our customers (or our custom services department) will not only create new entities but extend existing ones. For example, if our standard product defines the entity Cat, and some customer wants to extend it, we want standard product queries that refer to Cat to automatically return instances of the customer's subclass.

We've made this possible by requiring subclasses (intended to replace base classes) to have the same class name, but a different namespace. E.g. If the base product defines Microsquish.KillerApp.Domain.Cat, then a customer's replacement would need to be named something like MegaCorp.KillerApp.Domain.Cat. On application startup, only the replacement class's .hbm.xml file gets added to the NHibernate configuration. So far, this appears to work just fine.

However, now I've stumbled upon the polymorphism="implicit" attribute for the <class> element. The documentation suggests that it can do the same thing, without requiring matching unqualified class names. I assume the mappings (.hbm.xml files) for both the base class and subclass must be added to the NHibernate configuration at application startup.

Am I understanding the polymorphism="implicit" option correctly? How does NHibernate know which classes inherit from others? For each class added to the configuration, does it check every other class to see they are the base/sub class?

Implicit polymorphism is the default actually. When a query for a particular class is issued, NHibernate goes through the list of all persisters known to it and collects those that have polymorphism set to explicit and derive from the class or implement the interface. See SessionFactoryImpl.GetImplementors for the relevant code.

This is what makes queries like "from System.Object" work.

Thanks for the reply, Sergey. I found a recent post related to this, that says instances of the base class and the subclass gets returned by a query. I'm confused as to why someone would want this behavior -- that would seem to confuse code using the query, with what amounts to duplicates appearing in the result set. If the result set consumer wants an instance of a subclass to appear as a base class, they can just assign it to a reference of the base class type. Why the duplicates?

I don't understand the part about duplicates and what you mean by "they can just assign it to a reference of the base class type".

This behavior will not cause any duplicates, if there's an object of type Subclass and an object of type Superclass in the database and you issue a query "from Superclass", then you will get a list containing two items: one Superclass object and one Subclass object, no duplicates.

Duplicate object references in general only appear in query results if the corresponding SQL query returned duplicate rows. And even then, the objects are not actually duplicated, the results just contain several duplicate references to the same object.

Forget it. For better or for worse, we are not using polymorphism in the "standard" sense -- we are only supporting entity subclasses to allow our customers to replace our entities with their extensions. This replacement is not provided by <class polymorphism="true">, so apparently our efforts to provide a mechanism where entity type replacement occurs transparently was not a waste of time.

Let me put it this way, using the Cat example. Say our product defines a basic Cat entity. Out-of-the-box, this Cat entity is not all that useful. Our customers are very different -- one may be a veterinary clinic, one a pet store, one a research laboratory. They each want to track different additional information about Cats, so they subclass the Cat entity and add properties. All of their Cats are of their subclass. Yet, we provide basic functionality in our product to query and manage Cats, and this source code needs to deal with Cat queries returning the customer's subclass. Standard display and reporting will of course not show the subclass's additional properties, but it will still work. The customer will of course add additional data forms and queries that know about their subclass and do something with the additional properties. Now add to this the possibility that there are three or more "layers" of customization -- we may sell our product to a VAR, who extends our entities with subclasses, and then sells it to customers who then extend it further with their subclasses.

Of course, using subclasses in this way prevents any given customer from using subclasses for polymorphism. A big loss? Well, we are converting our application from a 2-tiered system that used ADO.NET untyped DataSets and the "Table Module" pattern to one with true entity objects and NHibernate. OO-design is not warmly embraced at my company, so adopting ORM was done reluctantly and is still questioned. Using different classes for data stored in the same table by use of discriminator columns in the NHibernate mapping would be considered unnecessary complexity.