Almost every unit test that we looked at in Chapter 3, Let's Tell NHibernate About Our Database involved saving entities into database. Back then we had used very simple code to save entities into in-memory database. We had said that we would look at that particular piece of code in detail in one of the upcoming chapters. This is the chapter where we would learn more about what that piece of code did for us.
We will begin this chapter with three important concepts that we must understand before we start interacting with NHibernate API that lets us store data into database. The first concept is entity states. NHibernate uses entity states to determine what action needs to be taken when entity is presented to NHibernate API. Second concept is transactions. NHibernate offers an abstraction over database's native transaction in the form of its transaction API. Understanding transactions is very fundamental to understanding how NHibernate synchronizes entity changes to the database. The third concept is flush modes which determines when the changes we made to entity instances are sent to the database.
We will then explore the simple code we used in Chapter 3, Let's Tell NHibernate About Our database to store entities into in-memory database. We will look under the bonnet to understand the SQL generated by NHibernate for this code and try to understand every part in more detail. We will then look into some complex persistence examples where NHibernate does a lot of heavy lifting for us with features such as transitive persistence, cascade, and so on. We will then bring forward the NHibernate architecture diagram from previous chapter and update it with our learnings from this chapter, and try to get complete picture of our knowledge so far.
Let's get going then.
From the time you create a new instance of an entity in memory till the time the instance is saved in the database, the entity instance goes through different states from NHibernate's point of view. It is important to understand these states because NHibernates's persistence behavior is largely dependent on this state of the entity. Depending on the state of the entity, you are allowed or not allowed to perform some operations on it. This state information is completely isolated from the entity instances and the entity itself is not aware of its own state. NHibernate manages the state of entities separately. To understand entity states, let's first look into some scenarios around saving/deleting entities.
When we create a new instance of an entity in the application, NHibernate is not aware of this instance. This instance is also not saved in the database yet and as such only exists in the application memory. Any changes you make to this entity instance would not be saved in the database yet.
In order to save this entity instance in the database, we can use one of the NHibernate APIs such as Save, Update, and such. We will discuss these APIs in detail in this chapter. When entity instance is passed to these APIs, NHibernate becomes aware of the entity and starts tracking it. Any changes you make to the entity after this point would be visible to NHibernate. At appropriate time, which is governed by multiple factors, this entity instance would be synchronized with database.
Often, we load entities that are present in database already. These entities are also tracked by NHibernate.
There are three states that NHibernate defines:
- Transient: An entity instance that is newly created and only exists inside the application memory and not in the database yet. NHibernate is not aware of existence of such entities and cannot track the changes being made to them.
- Persistent: An entity which exists in both database and in memory. Unlike transient entities, NHibernate knows about existence of such entities and is capable of tracking the changes being made to them. When an entity is loaded from database into memory, it is in persistent state by default. Also, when a transient entity is saved in database, it becomes persistent.
- Detached: These are entities that exist in the memory and database but NHibernate is not aware of their presence in the memory. Because of this, NHibernate is not able to track changes being made to them. There are two ways in which an entity can go into detached state. In this chapter we will look into both.
ISession interface of NHibernate provides methods that let you change the state of the entities. For instance, you can pass in a transient entity instance to the Save method of ISession to make that instance persistent. In the same way, invoking ISession.Delete on a persistent entity instance would make that instance detached. We will keep visiting these methods and preceding entity states throughout the chapter. For now, let's move on to the next concept.