One of the things that get me thoroughly confused is the use of session.Flush
,in conjunction with session.Commit
, and session.Close
.
Sometimes session.Close
works, e.g., it commits all the changes that I need. I know I need to use commit when I have a transaction, or a unit of work with several creates/updates/deletes, so that I can choose to rollback if an error occurs.
But sometimes I really get stymied by the logic behind session.Flush
. I have seen examples where you have a session.SaveOrUpdate()
followed by a flush, but when I remove Flush it works fine anyway. Sometimes I run into errors on the Flush statement saying that the session timed out, and removing it made sure that I didn't run into that error.
Does anyone have a good guideline as to where or when to use a Flush? I've checked out the NHibernate documentation for this, but I still can't find a straightforward answer.
Briefly:
Close()
, instead wrap your calls on an ISession
inside a using
statement or manage the lifecycle of your ISession somewhere else.From the documentation:
From time to time the
ISession
will execute the SQL statements needed to synchronize the ADO.NET connection's state with the state of objects held in memory. This process, flush, occurs by default at the following points
- from some invocations of
Find()
orEnumerable()
- from
NHibernate.ITransaction.Commit()
- from
ISession.Flush()
The SQL statements are issued in the following order
- all entity insertions, in the same order the corresponding objects were saved using
ISession.Save()
- all entity updates
- all collection deletions
- all collection element deletions, updates and insertions
- all collection insertions
- all entity deletions, in the same order the corresponding objects were deleted using
ISession.Delete()
(An exception is that objects using native ID generation are inserted when they are saved.)
Except when you explicity
Flush()
, there are absolutely no guarantees about when the Session executes the ADO.NET calls, only the order in which they are executed. However, NHibernate does guarantee that theISession.Find(..)
methods will never return stale data; nor will they return the wrong data.It is possible to change the default behavior so that flush occurs less frequently. The
FlushMode
class defines three different modes: only flush at commit time (and only when the NHibernateITransaction
API is used), flush automatically using the explained routine, or never flush unlessFlush()
is called explicitly. The last mode is useful for long running units of work, where anISession
is kept open and disconnected for a long time.
...
Also refer to this section:
Ending a session involves four distinct phases:
- flush the session
- commit the transaction
- close the session
- handle exceptions
Flushing the Session
If you happen to be using the
ITransaction
API, you don't need to worry about this step. It will be performed implicitly when the transaction is committed. Otherwise you should callISession.Flush()
to ensure that all changes are synchronized with the database.Committing the database transaction
If you are using the NHibernate ITransaction API, this looks like:
tx.Commit(); // flush the session and commit the transaction
If you are managing ADO.NET transactions yourself you should manually
Commit()
the ADO.NET transaction.sess.Flush(); currentTransaction.Commit();
If you decide not to commit your changes:
tx.Rollback(); // rollback the transaction
or:
currentTransaction.Rollback();
If you rollback the transaction you should immediately close and discard the current session to ensure that NHibernate's internal state is consistent.
Closing the ISession
A call to
ISession.Close()
marks the end of a session. The main implication of Close() is that the ADO.NET connection will be relinquished by the session.tx.Commit(); sess.Close(); sess.Flush(); currentTransaction.Commit(); sess.Close();
If you provided your own connection,
Close()
returns a reference to it, so you can manually close it or return it to the pool. OtherwiseClose()
returns it to the pool.