This article is an introduction to version-based optimistic concurrency control in Hibernate and JPA. The concept is fairly old and much has been written on it, but anyway I have seen it reinvented, misunderstood and misused. I’m writing it just to spread knowledge and hopefully spark interest in the subject of concurrency control and locking.
Use Cases
Let’s say we have a system used by multiple users, where each entity can be modified by more than one user. We want to prevent situations where two persons load some information, make some decision based on what they see, and update the state at the same time. We don’t want to lose changes made by the user who first clicked “save” by overwriting them in the following transaction.
It can also happen in server environment – multiple transactions can modify a shared entity, and we want to prevent scenarios like this:
- Transaction 1 loads data
- Transaction 2 updates that data and commits
- Using state loaded in step 1 (which is no longer current), transaction 1 performs some calculations and update the state
In some ways it’s comparable to non-repeatable reads.
Solution: Versioning
Hibernate and JPA implement the concept of version-based concurrency control for this reason. Here’s how it works.
You can mark a simple property with @Version or <version> (numeric or timestamp). It’s going to be a special column in database. Our mapping can look like:
@Entity
@Table(name = "orders")
public class Order {
@Id
private long id;
@Version
private int version;
private String description;
private String status;
// ... mutators
}
When such an entity is persisted, the version property is set to a starting value.
Whenever it’s updated, Hibernate executes query like:
update orders set description=?, status=?, version=? where id=? and version=?
Note that in the last line, the WHERE clause now includes version. This value is always set to the “old” value, so that it only will update a row if it has the expected version.
Let’s say two users load an order at version 1 and take a while looking at it in the GUI.
Anne decides to approve the order and executes such action. Status is updated in database, everything works as expected. Versions passed to update statement look like:
update orders set description=?, status=?, version=2 where id=? and version=1
As you can see, while persisting that update the persistence layer increments the version counter to 2.
In her GUI, Betty still has the old version (number 1). When she decides to perform an update on the order, the statement looks like:
update orders set description=?, status=?, version=2 where id=? and version=1
At this point, after Anne’s update, the row’s version in database is 2. So this second update affects 0 rows (nothing matches the WHERE clause). Hibernate detects that and an org.hibernate.StaleObjectStateException (wrapped in a javax.persistence.OptimisticLockException).
As a result, the second user cannot perform any updates unless he refreshes the view. For proper user experience we need some clean exception handling, but I’ll leave that out.
Configuration
There is little to customize here. The @Version property can be a number or a timestamp. Number is artificial, but typically occupies fewer bytes in memory and database. Timestamp is larger, but it always is updated to “current timestamp”, so you can actually use it to determine when the entity was updated.
Why?
So why would we use it?
- It provides a convenient and automated way to maintain consistency in scenarios like those described above. It means that each action can only be performed once, and it guarantees that the user or server process saw up-to-date state while making a business decision.
- It takes very little work to set up.
- Thanks to its optimistic nature, it’s fast. There is no locking anywhere, only one more field added to the same queries.
- In a way it guarantees repeatable reads even with read committed transaction isolation level. It would end with an exception, but at least it’s not possible to create inconsistent state.
- It works well with very long conversations, including those that span multiple transactions.
- It’s perfectly consistent in all possible scenarios and race conditions on ACID databases. The updates must be sequential, an update involves a row lock and the “second” one will always affect 0 rows and fail.
Demo
To demonstrate this, I created a very simple web application. It wires together Spring and Hibernate (behind JPA API), but it would work in other settings as well: Pure Hibernate (no JPA), JPA with different implementation, non-webapp, non-Spring etc.
The application keeps one Order with schema similar to above and shows it in a web form where you can update description and status. To experiment with concurrency control, open the page in two tabs, do different modifications and save. Try the same thing without @Version.
It uses an embedded database, so it needs minimal setup (only a web container) and only takes a restart to start with a fresh database.
It’s pretty simplistic – accesses EntityManager in a @Transactional @Controller and backs the form directly with JPA-mapped entity. May not be the best way to do things for less trivial projects, but at least it gathers all code in one place and is very easy to grasp.
Full source code as Eclipse project can be found at my GitHub repository.
