c# - NHibernate Definitive Cascade application guide

Question

Are there any internet resources that have a definitive guide to all of the cascade settings for NHibernate that will include examples of the class structure, HBM and the implications of actions with each of the cascade settings for all of the relationships with NH.

Also it would be helpful if there were examples for common associations to be done in the most correct manner such as setting up a states table that you will never end up cascade deleting a state, or that deleting an object that has a CreatedBy User property will never end up deleting the User in a cascade etc.

Answer 1

The following is adapted from the Java Hibernate reference http://docs.jboss.org/hibernate/stable/core/manual/en-US/html/objectstate.html#objectstate-transitive for NHiberate 3.0 (ie the current svn trunk).

For each basic operation of the NHibernate Session - including Persist(), Merge(), SaveOrUpdate(), Delete(), Lock(), Refresh(), Evict(), Replicate() - there is a corresponding cascade style. Respectively, the cascade styles are named persist, merge, save-update, delete, lock, refresh, evict, replicate. The cascade style for Save() and Update() is save-update; for SaveAndUpdateCopy() it is merge; and for PersistOnFlush() it is persist. And remove is an alias for delete.

If you want an operation to be cascaded along an association, you must indicate that in the mapping document. For example:

<one-to-one name="person" cascade="persist"/>

Cascade styles my be combined:

<one-to-one name="person" cascade="persist,delete,lock"/>

You can use cascade="all" to specify that all operations should be cascaded along the association. The default cascade="none" specifies that no operations are to be cascaded.

A special cascade style, delete-orphan, applies only to one-to-many associations, and indicates that the Delete() operation should be applied to any child object that is removed from the association. And all-delete-orphan is the same as all,delete-orphan.

Recommendations:

• It does not usually make sense to enable cascade on a <many-to-one> or <many-to-many> association. Cascade is often useful for <one-to-one> and <one-to-many> associations.
• If the child object's lifespan is bounded by the lifespan of the parent object, make it a life cycle object by specifying cascade="all-delete-orphan".
• Otherwise, you might not need cascade at all. But if you think that you will often be working with the parent and children together in the same transaction, and you want to save yourself some typing, consider using cascade="persist,merge,save-update".

Mapping an association (either a single valued association, or a collection) with cascade="all" marks the association as a parent/child style relationship where save/update/delete of the parent results in save/update/delete of the child or children. A child which becomes unreferenced by its parent is not automatically deleted, except in the case of a <one-to-many> association mapped with cascade="delete-orphan". The precise semantics of cascading operations for a parent/child relationship are as follows:

• If a parent is passed to Persist(), all children are passed to Persist()
• If a parent is passed to Merge(), all children are passed to Merge()
• If a parent is passed to Save(), Update() or SaveOrUpdate(), all children are passed to SaveOrUpdate()
• If a transient or detached child becomes referenced by a persistent parent, it is passed to SaveOrUpdate()
• If a parent is deleted, all children are passed to Delete()
• If a child is dereferenced by a persistent parent, nothing special happens - the application should explicitly delete the child if necessary - unless cascade="delete-orphan", in which case the "orphaned" child is deleted.