We have seen examples of saving an entity graph involving all transient entities in Chapter 3, Let's Tell NHibernate About Our Database, while discussing association mappings. But let's look at the examples again and understand what happens under the hood. In the following example, we try to save a transient instance of employee having some transient benefit instances added to its Benefits collection:

object id = 0;
using (var transaction = Session.BeginTransaction())
{
  id = Session.Save(new Employee
  {
    Benefits = new HashSet<Benefit>
    {
      new SeasonTicketLoan
      {
        Amount = 1200,
        MonthlyInstalment = 100,
        StartDate = new DateTime(2014, 5, 12),
        EndDate = new DateTime(2015, 4, 12)
      }

    }
  });
  transaction.Commit();
}

When the preceding code is run, NHibernate first saves the employee entity. After that, NHibernate inspects the associations and checks the cascade setting on the association mapping to determine what needs to be done to the associated benefit entity. If we had set cascade to none, then NHibernate would ignore the transient benefit entity and commit the transaction. On the other hand, had the cascade been set to save-update or all, NHibernate would generate necessary insert statements to insert the benefit records in database. Following SQL statements would be sent to database by NHibernate in that situation:

If you notice, NHibernate has generated an extraneous update statement to set correct foreign key value in the Employee_Id column of the Benefit table. This looks a bit unwise on part of NHibernate but fortunately there is way to fix this. In one of the upcoming sections, we will look at why NHibernate generates this extraneous update statement and how to fix this.

Another thing to note here is that when the record is inserted into the Benefit table, Employee_Id is inserted as null. This is because we did not correctly set the Employee property on the SeasonTicketLoan instance, leaving it as null. In the next section, we will talk about why it is important to set both ends of a bidirectional association.

object id = 0;
using (var transaction = Session.BeginTransaction())
{
  var seasonTicketLoan = new SeasonTicketLoan
  {
    Amount = 1200,
    MonthlyInstalment = 100,
    StartDate = new DateTime(2014, 5, 12),
    EndDate = new DateTime(2015, 4, 12)
  };
  var employee = new Employee
  {

    Benefits = new HashSet<Benefit>
    {
      seasonTicketLoan
    }
  };
  seasonTicketLoan.Employee = employee;

  id = Session.Save(employee);
  transaction.Commit();
}

public virtual void AddBenefit(Benefit benefit)
{
  benefit.Employee = this;
  Benefits.Add(benefit);
}

public Employee()
{
  Benefits = new HashSet<Benefit>();
}

private Address residentialAddress;
public virtual Address ResidentialAddress
{
  get
  {
    return residentialAddress;
  }
  set
  {
    residentialAddress = value;
    if (value != null) 
      residentialAddress.Employee = this;
  }
}

At the beginning of this section, we have seen the example of updating simple properties on a persistent entity, so I will not repeat that here. We have just looked at an example of adding entities to a collection on a transient entity. Adding entities to a collection on persistent entity is no different. The only thing you need to ensure is that both ends of the association are set if there is a bidirectional association. Removing items from a one-to-many association on a persistent entity works slightly differently and that is what we are going to discuss here.

Previously, when we discussed various cascade options, we learned that all-delete-orphan should be our default cascade style for one-to-many associations. Here, we would see with example what difference does that option bring in contrast to something such as save-update or delete. In the following code listing, a benefit instance of type Leave is removed from the Benefits collection on employee:

using (var tx = Session.BeginTransaction())
{
  var emp = Session.Get<Employee>(id);

  var leave = employee.Benefits.OfType<Leave>().FirstOrDefault();
  emp.RemoveBenefit(leave);

  tx.Commit();
}

We have a used convenience method named RemoveBenefit defined on the Employee class in order to remove the benefit instance from collection. This is in line with discussion around setting both ends of a bidirectional association. The same logic applies when breaking a bidirectional association. In this case, just removing the benefit from the Benefits collection of Employee is not enough. We also need to set the Employee property on Benefit to null.

Following is how the RemoveBenefit method looks:

public virtual void RemoveBenefit(Benefit benefit)
{
  benefit.Employee = null;
  Benefits.Remove(benefit);
}

If cascade setting on mapping of the Benefits collection is set to save-update or all, then the preceding code would result in following SQL being generated:

  UPDATE
    Benefit
  SET
    Name = @p0,
    Description = @p1,
    Employee_Id = @p2
  WHERE
    Id = @p3;
  @p0 = NULL [Type: String (0)],
  @p1 = NULL [Type: String (0)],
  @p2 = NULL [Type: Int32 (0)],
  @p3 = 65537 [Type: Int32 (0)]

Note that, though we asked NHibernate to remove leave instance, NHibernate only updated the value of foreign key column Employee_Id in the Benefit table to NULL. It effectively only deleted the association between employee and benefit but the benefit instance is still there in the database. Such behavior is desired if there are other records in database referring to this benefit record or for some reason you are not allowed to delete the so called orphan records not referenced anymore. But what if you want these orphan records to be deleted when no other database record references this record? That is when you use cascade setting delete-orphan which tells NHibernate that the moment it detects an orphan record resulting out of any database operation, it should delete it. Following code listing shows how you can set cascade value of delete-orphan using mapping by code:

Set(e => e.Benefits, mapper =>
{
  mapper.Key(k => k.Column("Employee_Id"));
  mapper.Cascade(Cascade.All.Include(Cascade.DeleteOrphans));
  mapper.Inverse(true);
},
relation => relation.OneToMany(mapping => mapping.Class(typeof(Benefit))));

Note that we have set the cascade value to All first and then included DeleteOrphan on top. This is because cascade values work in a similar way to a set or union. You are telling NHibernate which set of operations you want to cascade by combining them as we did in the preceding example. After setting the cascade value to all-delete-orphan, following SQL is generated by NHibernate for the same piece of code:

  DELETE
  FROM
    Leave
  WHERE
    Id = @p0;
  @p0 = 65537 [Type: Int32 (0)]

  DELETE
  FROM
    Benefit
  WHERE
    Id = @p0;
  @p0 = 65537 [Type: Int32 (0)]

You can see that NHibernate has detected an orphan record and issued the commands to delete it. It also figures out that record from the Leave table needs to be deleted before it can delete the record in the Benefit table.

In more than one way, the API for deleting a persistent entity is similar to the API for saving an entity. Similar to Save(), session has a method named Delete() to which you pass the entity instance that you want to delete. The way NHibernate navigates through the associations and checks cascade settings while saving the entities, it does the same thing while deleting the entities. Following code listing deletes an employee instance:

using (var tx = Session.BeginTransaction())
{
  var emp = Session.Get<Employee>(id);
  Session.Delete(emp);
  tx.Commit();
}

If the preceding employee instance has all its associations set with a cascade value that would propagate the delete operation (delete or all), then NHibernate would navigate all the associations and issue delete commands in correct order to ensure that all the entities are deleted without any violation of dependency.

After the entity is deleted from the database, NHibernate also removes it from the session.