Optimistic locking in a stateless application with JPA / Hibernate

Question

I'm wondering what would be the best way to implement optimistic locking (optimistic concurrency control) in a system where entity instances with a certain version can not be kept between requests. This is actually a pretty common scenario but almost all examples are based on applications that would hold the loaded entity between requests (in a http session).

How could optimistic locking be implemented with as little API pollution as possible?

Constraints

• The system is developed based on Domain Driven Design principles.
• Client/server system
• Entity instances can not be kept between requests (for availability and scalability reasons).
• Technical details should pollute the API of the domain as little as possible.

The stack is Spring with JPA (Hibernate), if this should be of any relevance.

Problem using @Version only

In many documents it looks like all you need to do would be to decorate a field with @Version and JPA/Hibernate would automatically check versions. But that only works if the loaded objects with their then current version are kept in memory until the update changes the same instance.

What would happen when using @Version in a stateless application:

1. Client A loads item with id = 1 and gets Item(id = 1, version = 1, name = "a")
2. Client B loads item with id = 1 and gets Item(id = 1, version = 1, name = "a")
3. Client A modifies the item and sends it back to the server: Item(id = 1, version = 1, name = "b")
4. The server loads the item with the EntityManager which returns Item(id = 1, version = 1, name = "a"), it changes the name and persist Item(id = 1, version = 1, name = "b"). Hibernate increments the version to 2.
5. Client B modifies the item and sends it back to the server: Item(id = 1, version = 1, name = "c").
6. The server loads the item with the EntityManager which returns Item(id = 1, version = 2, name = "b"), it changes the name and persist Item(id = 1, version = 2, name = "c"). Hibernate increments the version to 3. Seemingly no conflict!

As you can see in step 6, the problem is that the EntityManager reloads the then current version (version = 2) of the Item immediately before the update. The information that Client B started editing with version = 1 is lost and the conflict can not be detected by Hibernate. The update request performed by Client B would have to persist Item(id = 1, version = 1, name = "b") instead (and not version = 2).

The automatic version check provided by JPA/Hibernate would only work if the instances loaded on the the initial GET request would be kept alive in some kind of client session on the server, and would be updated later by the respective client. But in a stateless server the version coming from the client must be taken into consideration somehow.

Possible solutions

Explicit version check

An explicit version check could be performed in a method of an application service:

@Transactional
fun changeName(dto: ItemDto) {
    val item = itemRepository.findById(dto.id)
    if (dto.version > item.version) {
        throw OptimisticLockException()
    }
    item.changeName(dto.name)
}

Pros

• The domain class (Item) doesn't need a way to manipulate the version from the outside.
• Version checking is not part of the domain (except the version property itself)

Cons

• easy to forget
• Version field must be public
• automatic version checking by the framework (at the latest possible point in time) is not used

Forgetting the check could be prevented through an additional wrapper (ConcurrencyGuard in my example below). The repository would not directly return the item, but a container that would enforce the check.

@Transactional
fun changeName(dto: ItemDto) {
    val guardedItem: ConcurrencyGuard<Item> = itemRepository.findById(dto.id)
    val item = guardedItem.checkVersionAndReturnEntity(dto.version)
    item.changeName(dto.name)
}

A downside would be that the check is unnecessary in some cases (read-only access). But there could be another method returnEntityForReadOnlyAccess. Another downside would be that the ConcurrencyGuard class would bring a technical aspect to the domain concept of a repository.

Loading by ID and version

Entities could be loaded by ID and version, so that the conflict would show at load time.

@Transactional
fun changeName(dto: ItemDto) {
    val item = itemRepository.findByIdAndVersion(dto.id, dto.version)
    item.changeName(dto.name)
}

If findByIdAndVersion would find an instance with the given ID but with a different version, an OptimisticLockException would be thrown.

Pros

• impossible to forget handle the version
• version doesn't pollute all methods of the domain object (though repositories are domain objects, too)

Cons

• Pollution of the repository API
• findById without version would be needed anyway for initial loading (when editing starts) and this method could be easily used accidentally

Updating with explicit version

@Transactional
fun changeName(dto: itemDto) {
    val item = itemRepository.findById(dto.id)
    item.changeName(dto.name)
    itemRepository.update(item, dto.version)
}

Pros

• not every mutating method of the entity must be polluted with a version parameter

Cons

• Repository API is polluted with the technical parameter version
• Explicit update methods would contradict the "unit of work" pattern

Update version property explicitly on mutation

The version parameter could be passed to mutating methods which could internally update the version field.

@Entity
class Item(var name: String) {
    @Version
    private version: Int

    fun changeName(name: String, version: Int) {
        this.version = version
        this.name = name
    }
}

Pros

• impossible to forget

Cons

• technical details leaks in all mutating domain methods
• easy to forget
• It is not allowed to change the version attribute of managed entities directly.

A variant of this pattern would be to set the version directly on the loaded object.

@Transactional
fun changeName(dto: ItemDto) {
    val item = itemRepository.findById(dto.id)
    it.version = dto.version
    item.changeName(dto.name)
}

But that would expose the version directly expose for reading and writing and it would increase the possibility for errors, since this call could be easily forgotten. However, not every method would be polluted with a version parameter.

Create a new Object with the same ID

A new object with the same ID as the object to be update could created in the application. This object would get the version property in the constructor. The newly created object would then be merged into the persistence context.

@Transactional
fun update(dto: ItemDto) {
    val item = Item(dto.id, dto.version, dto.name) // and other properties ...
    repository.save(item)
}

Pros

• consistent for all kinds of modifications
• impossible to forget version attribute
• immutable objects are easy to create
• no need to load the existing object first in many cases

Cons

• ID and version as technical attributes are part of the interface of domain classes
• Creating new objects would prevent the usage of mutation methods with a meaning in the domain. Maybe there is a changeName method that should perform a certain action only on changes but not on the initial setting of the name. Such a method wouldn't be called in this scenario. Maybe this downside could be mitigated with specific factory methods.
• Conflicts with the "unit of work" pattern.

Question

How would you solve it and why? Is there a better idea?

Related

• Optimistic locking in a RESTful application
• Managing concurrency in a distributed RESTful environment with Spring Boot and Angular 2 (this is basically the "explicit version check" from above implemented with HTTP headers)

Answer 1

The server loads the item with the EntityManager which returns Item(id = 1, version = 1, name = "a"), it changes the name and persist Item(id = 1, version = 1, name = "b"). Hibernate increments the version to 2.

That's a misuse of the JPA API, and the root cause of your bug.

If you use entityManager.merge(itemFromClient) instead, the optimistic locking version would be checked automatically, and "updates from the past" rejected.

One caveat is that entityManager.merge will merge the entire state of the entity. If you only want to update certain fields, things are a bit messy with plain JPA. Specifically, because you may not assign the version property, you must check the version yourself. However, that code is easy to reuse:

<E extends BaseEntity> E find(E clientEntity) {
    E entity = entityManager.find(clientEntity.getClass(), clientEntity.getId());
    if (entity.getVersion() != clientEntity.getVersion()) {
        throw new ObjectOptimisticLockingFailureException(...);
    }
    return entity;
}

and then you can simply do:

public Item updateItem(Item itemFromClient) {
    Item item = find(itemFromClient);
    item.setName(itemFromClient.getName());
    return item;
}

depending on the nature of the unmodifiable fields, you may also be able to do:

public Item updateItem(Item itemFromClient) {
    Item item = entityManager.merge(itemFromClient);
    item.setLastUpdated(now());
}

As for doing this in a DDD way, the version checking is an implementation detail of the persistence technology, and should therefore occur in the repository implementation.

To pass the version through the various layers of the app, I find it convenient to make the version part of the domain entity or value object. That way, other layers do not have to explicitly interact with the version field.

Answer 2

When you load the record from DB to process the update request , you have to configure that loaded instance to have the same version supplied by the client. But unfortunately when an entity is managed , its version cannot be changed manually as required by the JPA spec.

I try to trace the Hibernate source codes and do not notice there are any Hibernate specific feature that can by-passed this limitation. Thankfully, the version checking logic is straightforward such that we can check it by ourself. The entity returned is still managed which means unit of work pattern can still be applied to it :

// the version in the input parameter is the version supplied from the client
public Item findById(Integer itemId, Integer version){
    Item item = entityManager.find(Item.class, itemId);

    if(!item.getVersoin().equals(version)){
      throws  new OptimisticLockException();
    }
    return item;
}

---

For the concern about API will be polluted by the version parameter, I would model entityId and version as a domain concept which is represented by a value object called EntityIdentifier :

public class EntityIdentifier {
    private Integer id;
    private Integer version;
}

Then have a BaseRepository to load an entity by EntityIdentifier. If the version in EntityIdentifier is NULL, it will be treated as the latest version. All repositories of other entities will extend it in order to reuse this method :

public abstract class BaseRepository<T extends Entity> {

    private EntityManager entityManager;

    public T findById(EntityIdentifier identifier){

         T t = entityManager.find(getEntityClass(), identifier.getId());    

        if(identifier.getVersion() != null && !t.getVersion().equals(identifier.getVersion())){
            throws new OptimisticLockException();
        }
        return t;
 } 

^{Note: This method does not mean loading the state of the entity at an exact version since we are not doing event sourcing here and will not store the entity state at every version. The state of the loaded entity will always be the latest version , the version in EntityIdentifier is just for handling the optimistic locking.}

To make it more generic and easily to use , I will also define an EntityBackable interface such that the BaseRepository can load the backed entity of anything (e.g. DTO) once they implement it.

public interface EntityBackable{
    public EntityIdentifier getBackedEntityIdentifier();
}

And add the following method to BaseRepository :

 public T findById(EntityBackable eb){
     return findById(eb.getBackedEntityIdentifier());
 }

So at the end, ItemDto and updateItem() application service looks like:

public class ItemDto implements EntityBackable {

    private Integer id;
    private Integer version;

    @Override
    public EntityIdentifier getBackedEntityIdentifier(){
         return new EntityIdentifier(id ,version);
    }
}

@Transactional
public void changeName(ItemDto dto){
    Item item = itemRepository.findById(dto);
    item.changeName(dto.getName());
}

To summarise , this solution can :

• Unit of work pattern still valid
• Repository API will not populated with version parameter
• All technical details about controlling the version are encapsulated inside BaseRepository , so no technical details are leaks into the domain.

---

Note:

• setVersion() is still need to be exposed from the domain entity.But I am okay with it as the entity get from the repository is managed which means there are no effect on the entity even developers calls setVersion(). If you really don't want developers to call setVersion(). You can simply to add an ArchUnit test to verify that it can only be called from the BaseRepository.

Answer 3

All explanations and suggestions made here were very helpful, but since the final solutions differs a bit, I think it is worth sharing it.

Manipulating the version directly didn't work properly and conflicts with the JPA spec, so it was no option.

The final solution is the explicit version check + automatic version checking by JPA Hibernate. The explicit version check is performed at the application layer:

@Transactional
fun changeName(dto: ItemDto) {
    val item = itemRepository.findById(dto.id)
    rejectConcurrentModification(dto, item)
    item.changeName(dto.name)
}

To reduce repetition, the actual check happens in a separate method:

fun rejectConcurrentModification(dto: Versioned, entity: Versioned) {
    if (dto.version != entity.version) {
        throw ConcurrentModificationException(
            "Client providing version ${dto.version} tried to change " + 
            "entity with version ${entity.version}.")
    }
}

Entities and DTOs both implement the Versioned interface:

interface Versioned {
    val version: Int
}

@Entity
class Item : Versioned {
    @Version
    override val version: Int = 0
}

data class ItemDto(override val version: Int) : Versioned

But pulling version from both and pass it to rejectConcurrentModification would work equally well:

rejectConcurrentModification(dto.version, item.verion)

The obvious downside of the explicit check at the application layer is that it could be forgotten. But since the repository must provide a way to load an entity without a version anyway, adding the version to the find method of the repository wouldn't be safe either.

The upside of the explicit version check at the application layer is that it doesn't pollute the domain layer except the version needs to be readable from the outside (by implementing the Versioned interface). Entity or repository methods, which are both part of the domain, are not polluted with version parameters.

That the explicit version check is not performed at the latest possible point in time doesn't matter. If between this check and the final update on the database another user would modify the same entity, then the automatic version check by Hibernate would become effective, since the version loaded at the beginning of the update request is still in memory (on the stack of the changeName method in my example). So, the first explicit check would prevent a concurrent modification happend between the begin of the edit on the client and the explicit version check. And the automatic version check would prevent a concurrent modification between the explicit check and the final update on the database.

Answer 4

To prevent concurrent modifications, we have to keep track of which version of item is being modified, somewhere.

If the application was stateful, we would have an option to keep this info on serverside, possibly in session, though this may not be best choice.

In stateless application, this info will have to go all the way to client and come back with every mutating request.

So, IMO, if preventing concurrent modifications is a functional requirement, then having item version info in mutating API calls does not pollute the API, it makes it complete.