NHibernate collections are considered to be a logical part of their owning entity and not of the contained entities. Be aware that this is a critical distinction that has the following consequences:

Adding an entity to a collection, by default, merely creates a link between the two entities. Removing the entity will remove the link. This is appropriate for all sorts of cases. However, it is not appropriate in the case of a parent/child relationship. In this case, the life of the child is bound to the life cycle of the parent.

Suppose we start with a simple <one-to-many> association from Parent to Child.

<set name="Children">
    <key column="parent_id" />
    <one-to-many class="Child" />
</set>

If we were to execute the following code:

Parent p = ...;
Child c = new Child();
p.Children.Add(c);
session.Save(c);
session.Flush();

NHibernate would issue two SQL statements:

This is not only inefficient, but also violates any NOT NULL constraint on the parent_id column. You can fix the nullability constraint violation by specifying not-null="true" in the collection mapping:

<set name="Children">
    <key column="parent_id" not-null="true"/>
    <one-to-many class="Child"/>
</set>

However, this is not the recommended solution.

The underlying cause of this behavior is that the link (the foreign key parent_id) from p to c is not considered part of the state of the Child object and is therefore not created in the INSERT. The solution is to make the link part of the Child mapping.

<many-to-one name="Parent" column="parent_id" not-null="true"/>

You also need to add the Parent property to the Child class.

Now that the Child entity is managing the state of the link, we tell the collection not to update the link. We use the inverse attribute to do this:

<set name="Children" inverse="true">
    <key column="parent_id"/>
    <one-to-many class="Child"/>
</set>

The following code would be used to add a new Child:

Parent p = session.Load<Parent>(pid);
Child c = new Child();
c.Parent = p;
p.Children.Add(c);
session.Save(c);
session.Flush();

Only one SQL INSERT would now be issued.

You could also create an AddChild() method of Parent.

public void AddChild(Child c)
{
    c.Parent = this;
    children.Add(c);
}

The code to add a Child looks like

Parent p = session.Load<Parent>(pid);
Child c = new Child();
p.AddChild(c);
session.Save(c);
session.Flush();

You can address the frustrations of the explicit call to Save() by using cascades.

<set name="Children" inverse="true" cascade="all">
    <key column="parent_id"/>
    <one-to-many class="Child"/>
</set>

This simplifies the code above to:

Parent p = session.Load<Parent>(pid);
Child c = new Child();
p.AddChild(c);
session.Flush();

Similarly, we do no more need to iterate over the children when saving or deleting a Parent. The following removes p and all its children from the database.

Parent p = session.Load<Parent>(pid);
session.Delete(p);
session.Flush();

However, the following code:

Parent p = session.Load<Parent>(pid);
// Get one child out of the set
Child c = p.Children.First();

p.Children.Remove(c);
c.Parent = null;
session.Flush();

will not remove c from the database. In this case, it will only remove the link to p and cause a NOT NULL constraint violation. You need to explicitly Delete() the Child.

Parent p = session.Load<Parent>(pid);
// Get one child out of the set
Child c = p.Children.First();

p.Children.Remove(c);
session.Delete(c);
session.Flush();

In our case, a Child cannot exist without its parent. So if we remove a Child from the collection, we do want it to be deleted. To do this, we must use cascade="all-delete-orphan".

<set name="Children" inverse="true" cascade="all-delete-orphan">
    <key column="parent_id"/>
    <one-to-many class="Child"/>
</set>

Even though the collection mapping specifies inverse="true", cascades are still processed by iterating the collection elements. If you need an object be saved, deleted or updated by cascade, you must add it to the collection. It is not enough to simply set its parent.

Suppose we loaded up a Parent in one ISession, made some changes in a UI action and wanted to persist these changes in a new ISession by calling Update(). The Parent will contain a collection of children and, since the cascading update is enabled, NHibernate needs to know which children are newly instantiated and which represent existing rows in the database. We will also assume that both Parent and Child have generated identifier properties of type long. NHibernate will use the identifier and version/timestamp property value to determine which of the children are new. (See Section 10.4.2, “Updating detached objects”.)

The unsaved-value attribute is used to specify the identifier value of a newly instantiated instance. In NHibernate it is not necessary to specify unsaved-value explicitly.

The following code will update parent and child and insert newChild.

//parent and child were both loaded in a previous session
parent.AddChild(child);
Child newChild = new Child();
parent.AddChild(newChild);
session.Update(parent);
session.Flush();

This may be suitable for the case of a generated identifier, but what about assigned identifiers and composite identifiers? This is more difficult, since NHibernate cannot use the identifier property to distinguish between a newly instantiated object, with an identifier assigned by the user, and an object loaded in a previous session. In this case, NHibernate will either use the timestamp or version property, or will actually query the second-level cache or, worst case, the database, to see if the row exists.

To avoid the worst case, either:

For the IInterceptor solution, you could by example define a base class for your persistent classes:

public class Persistent
{
    private bool _saved = false;

    public virtual void OnSave()
    {
        _saved = true;
    }

    public virtual void OnLoad()
    {
        _saved = true;
    }

    public virtual void OnDelete()
    {
        _saved = false;
    }

    ...

    public virtual bool IsSaved
    {
        get { return _saved; }
    }
}

(The saved property is non-persistent.) Then implement in you interceptor class IsTransient(), along with OnLoad(), OnSave() and OnDelete() as follows:

public object IsTransient(object entity)
{
    if (entity is Persistent)
    {
        return !((Persistent) entity).IsSaved;
    }
    else
    {
        return null;
    }
}

public bool OnLoad(object entity,
    object id,
    object[] state,
    string[] propertyNames,
    IType[] types)
{
    if (entity is Persistent)
        ((Persistent) entity).OnLoad();
    return false;
}

public boolean OnSave(object entity,
    object id,
    object[] state,
    string[] propertyNames,
    IType[] types)
{
    if (entity is Persistent)
        ((Persistent) entity).OnSave();
    return false;
}

public virtual void OnDelete(object entity,
    object id,
    object[] state,
    string[] propertyNames,
    IType[] types)
{
    if (entity is Persistent)
        ((Persistent) entity).OnDelete();
}

See Section 13.1, “Interceptors” for more information.

There is quite a bit to digest here and it might look confusing first time around. However, in practice, it all works out quite nicely. Most NHibernate applications use the parent / child pattern in many places.

We mentioned an alternative in the first paragraph. None of the above issues exist in the case of <composite-element> mappings, which have exactly the semantics of a parent/child relationship. Unfortunately, there are two big limitations to composite element classes: composite elements cannot own collections, and they should not be the child of any entity other than the unique parent. (However, they may have a surrogate primary key, using an <idbag> mapping.)