Hibernate 3# - Session API

Hibernate's Session is the interface that provides API for Java application to interact with persistence layer. It introduces CRUD methods to operate on entities. It also contains methods used to handle transactions. We can say, that Session is the core interface in the Hibernate library. We will have a look at the core features of Session and how it is handled in Spring framework.

Entity Management

You will often see additional layers of abstraction over Session interface (like in Spring, which is discussed later). However, in this part of the article I will show some basic examples of using Session object directly with regard to operations on entities.

Entity is a domain model class. Its instance represents in the Java world a database row. As an entity example we will use following class:


As you can see we are using multiple annotations which are needed by Hibernate to properly map the entity instance to a database row and vice versa. This annotations are @Entity, @Table, @Column and so forth. More details regarding entites can be found here: Hibernate entites docs.

In this article we will set our minds on the Hibernate Session details.
Below we will present the simple examples of CRUD operations that can be performed on entities using Hibernate's Session object

1. Loading an entity:
   
2. Saving a new entity:
   
3. Deleting an entity:
   
4. Updating an entity:
   

By managing entities, Hibernate Session is changing their state which can later result in performing a proper database statements during flush time. We will introduce flush time concept in another section.
There are 4 states of entities with regard to persistence context:

• transcient - not yet added to the persistence context
• persistent - handled by persistence context, changes will be saved to database during flush time.
• detached - has been handled by persistence context but after detaching is not handled anymore. 
• removed - object will be deleted from database during flush time.

More on the entity states can be found here: entity states overview. Session's ability to manage entities states also leads to calling it a Persistence Context.

Transaction Management

Session's lifecycle begins when logical transaction is opened and ends when logical transaction is closed. Similarly to the previous section, we will have a look at the direct Session usage with regard to handling transactions. In real case scenarios (like Spring projects) you will probably see an addidtional abstraction layer over direct Session usage, also in case of transaction handling. We will cover that scenarios later on. For now lets see, how can transaction management be handled using plain Session implementation:


As you can see, Session contains method that starts a transaction (session.beginTransaction()) which returns a Transaction object. Later we can invoke tx.commit() or tx.rollback() methods on Transaction object. It is very important to be sure, that we always finish the transaction by either commiting or rollbacking it. After finishing the transaction Session should be closed by calling session.close() (there are exceptions to this rules like long-term conversations, which will be explained later). The session.close() method ends the session and releases a JDBC connection.

flush() method

Hibernate Session interface flush() method is used to perform all the database statements used to synchronize entities state with database. It could be for example an INSERT statement, when we have a new entity (without corresponding row in database) in persistent state or a DELETE statement when we have an entity in removed state. This process is called Flushing the Session and the time when it is performed is called flush time. We can only synchronize those entities that are present in persistence context (in either persistent or removed state). Flushing the session can also happen:

• While commiting transaction (calling commit() method on Transaction object). 
• Before some of the query executions. 

It is however possible to configure when the flush should be performed and when it should not. More details are described here - Hibernate - Flushing the Session.

Session & JPA

JPA is an abstraction over persistance layer, which means that it is an abstraction over the ORM provider API. The interface that abstracts the ORM provider's API is an EntityManager. Session interface extends EntityManager interface which means that it is compilant with JPA. It also means that Session implementation is also an EntityManager implementation. We often see EntityManager interface used (with Session implementation underneath) rather then Session interface directly. It is a good practice since it decouples our code from the ORM library provider like Hibernate. Below you can see example how to retrieve a Session object from the EntityManager, if you will ever have that need..

Usage in Spring

In order to be able to bootstrap a Hibernate in Spring, we have to add a proper dependency. In case of maven, it would be the following one:

A lot of things are happening behind the scenes in Spring. As previously mentioned, Session interface is hidden by its JPA abstraction - EntityManager. In Spring, EntityManager is often ... hidden by other abstractions. Lets have a look at the typical example of Spring service method which uses performs operations on entities:


Repository which is used to save the entity is a Spring Data repository. Behind the scenes is uses EntityManager. When the persistence provider is Hibernate, then Session implementation will be called since Session interface extends EntityManager interface. You can also see a @Transactional annotation which is a Spring annotation to use declarative transactions support. Transactions support again is based on EntityManager methods, that provide possibility to open, commit or rollback transaction. In this case again, the Session implementation will be used underneath.
There are ways of obtaining Session object directly in Spring, however this is not considered as the best practcice since we would introduce a coupling between Spring and Hibernate. What is more, the abstractions provided by Spring (like repositories) or support for declarative transaction management are just more concise and simpler to use that plain Session or even EntityManager object. 

Concurrency

Session object is not thread safe. That is why it should not be shared between threads. It is intended that it will discarded after being used for:

1. Single request/Single transaction. This is the default behaviour in Spring project, unless you try to handle Session with some kind of manual approach, which is usually not needed and not recommended. In this approach, after finishing the logical transaction in a single request the session is closed.
2. Single conversation - it could be in a case of extended application level transaction, often called as long-term conversation. It is a logical transaction that spans over multiple physical transactions which also means that it could span over multiple requests. 

Creating a new Session object per transaction/conversation is not expensive. Concurrency of entities stored in Hibernate Session (Persistence Context) should be ensured by either pessimistic or optimistic locking. Entities should not be synchronized. 

More details on Session concurrency and long-term conversations can be found here: Hibernate docs.

Conclusions

Hibernate's Session interface is the main API used to handle the persistence layer. It provides methods to operate on entities and manage transactions. These methods are however often invoked behind the scenes. In Spring we have an EntityManager which is a JPA abstraction over Session interface. Together with declarative transaction management and Spring Data repositories we often do not even see the Session methods being called in real life projects. It is however good to know that it is there and is used under the hood.