High level design

Transaction support works through wrapping the Store that backs the Cache and storing a specific datastructure, a SoftLock, wrapping the cache values themselves.

Note
No cache interactions are allowed outside of a transaction context.

Operations under a transaction

In the context of a transaction, cache operations are translated to Commands and stored in a transaction specific context.

These commands cause Store mutations at specific stages in the lifecycle of the transaction.

Prepare

During the prepare phase, all commands have their values, new and old if available, transformed into SoftLock instances. These are saved in the Store. A SoftLock from the prepare phase will carry the following information:

  • Transaction information allowing to identify which transaction created it,

  • The new mapping value to install - can be null to indicate removal,

  • The old mapping value when relevant. Such SoftLock are considered in doubt.

Commit

During the commit phase, in doubt SoftLock will be retrieved from the Store. That will be the case for all keys that were touched by the transaction. As long as the retrieved SoftLock is linked to this transaction context, they will be replaced in the underlying Store with a SoftLock instance:

  • Holding the value for the mapping, identified as the old value,

  • disconnected from any transaction context.

Commit in 1 phase

In that case, we go directly from the command to the disconnected SoftLock but the principle remains the same.

Rollback

In case of rollback, in doubt SoftLock will be retrieved from the Store. That will be the case for all keys that were touched by the transaction. As long as the retrieved SoftLock is linked to this transaction context, they will be replaced in the underlying Store with a SoftLock instance:

  • Holding the old value,

  • disconnected from any transaction context.

Rollback before prepare

Commands are simply dropped from the transaction context.

Interactions with other Ehcache features

Eviction advisor

By default the XAStore uses the EvictionAdvisor mechanism to protect all in doubt SoftLock.

Integration with user provided EvictionAdvisor is limited to SoftLock that are not in doubt and which by definition only contain an old value, which will be the value passed to the adviseAgainstEviction(K key, V value) method.