Common Pitfalls of Declarative Transaction Management in Spring

Spring supports two types of transaction management, namely, programmatic and declarative transaction management. Despite the fact that programmatic management is more flexible, declarative management is still preferred since it is less invasive to application code. In this post, I'm going to summarize several pitfalls you may encounter while using declarative transaction management. Certainly, if you read the official document thoroughly, you should know how to avoid them on your own, but if you think of it is all about annotating your method with the @Transactional annotation as I did, you may never figure them out until the day your customer reports his balance is incorrect.

Prerequisites

Our samples are written in Kotlin language. In addition, I assume that you are already familiar with the following frameworks.

• Spring
• JPA(Hibernate implementation)
• Spring Data JPA

Examples in this post are based on the following class:

1
2
3
4
5
6
7
8

// entity
@Entity
class DemoEntity(
        val name: String
) : AbstractPersistable<Int>()

// repository
interface DemoRepo : CrudRepository<DemoEntity, Int>

Pitfall 1: @Transactional annotation may have no effect at all

It's a common circumstance that we put some code in a private method so it can be reused. If the code involves a transaction, we may end up with writing code like this.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

@Service
class DemoService(
        private val demoRepo: DemoRepo
) {
    fun persistAndDoSomething(demo: DemoEntity) {
        persist(demo)
        // do something
    }

    fun persistAndDoOtherthings(demo: DemoEntity) {
        persist(demo)
        // do other things
    }

    @Transactional
    private fun persist(demo: DemoEntity) {
        // you may think this action will be rolled back if exception occurs
        demoRepo.save(demo)
        unpredictableMethod()
    }

    // simulate a method which may or may not throw an exception
    fun unpredictableMethod() {
        if (ThreadLocalRandom.current().nextBoolean())
            throw Exception("Oops!")
    }
}

When using proxies, you should apply the @Transactional annotation only to methods with public visibility. If you do annotate protected, private or package-visible methods with the @Transactional annotation, no error is raised, but the annotated method does not exhibit the configured transactional settings. Consider the use of AspectJ if you need to annotate non-public methods.

Now the reason is pretty clear, to fix the problem, we can either switch the advice mode from "PROXY"(default option) to "ASPECTJ", or remove the private modifier from the persist method. Let's say we choose to remove the modifier, you can find that the persist is still invoked without any transaction, because we just fall into the next pitfall.

Pitfall 2: @Transactional annotation may not affect a method invocation

Following the previous section, after applying the second solution from the previous section, our DemoService now looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

@Service
class DemoService(
        private val demoRepo: DemoRepo
) {
    fun persistAndDoSomething(demo: DemoEntity) {
        persist(demo)
        // do something
    }

    fun persistAndDoOtherthings(demo: DemoEntity) {
        persist(demo)
        // do other things
    }

    @Transactional
    fun persist(demo: DemoEntity) {
        // you may think this action will be rolled back if exception occurs
        demoRepo.save(demo)
        unpredictableMethod()
    }

    // simulate a method which may or may not throw an exception
    fun unpredictableMethod() {
        if (ThreadLocalRandom.current().nextBoolean())
            throw Exception("Oops!")
    }
}

In proxy mode, only external method calls coming in through the proxy are intercepted. This means that self-invocation, in effect, a method within the target object calling another method of the target object, will not lead to an actual transaction at runtime even if the invoked method is marked with @Transactional. Also, the proxy must be fully initialized to provide the expected behavior so you should not rely on this feature in your initialization code, i.e. @PostConstruct.

There's a tricky solution against this problem, inject itself to an instance field, then invoke methods from the instance. The code looks like

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

@Service
class DemoService(
        private val demoRepo: DemoRepo
) {

    // Unlike demoRepo, it cannot be a constructor parameter
    // otherwise Spring won't be able to initialize the proxy due to a circular dependency.
    @Autowired
    private lazyinit var self: DemoService

    fun persistAndDoSomething(demo: DemoEntity) {
        self.persist(demo)
        // do something
    }

    fun persistAndDoOtherthings(demo: DemoEntity) {
        self.persist(demo)
        // do other things
    }

    @Transactional
    fun persist(demo: DemoEntity) {
        // you may think this action will be rolled back if exception occurs
        demoRepo.save(demo)
        unpredictableMethod()
    }

    // simulate a method which may or may not throw an exception
    fun unpredictableMethod() {
        if (ThreadLocalRandom.current().nextBoolean())
            throw Exception("Oops!")
    }
}

Pitfall 3: Transaction may not rollback when an exception occurs

Before further explaining, let's focus on the buggy code segment.

1
2
3
4
5
6
7
8
9
10
11
12

@Transactional
fun persist(demo: DemoEntity) {
    // you may think this action will be rolled back if exception occurs
    demoRepo.save(demo)
    unpredictableMethod()
}

// simulate a method which may or may not throw an exception
fun unpredictableMethod() {
    if (ThreadLocalRandom.current().nextBoolean())
        throw Exception("Oops!")
}

In its default configuration, the Spring Framework’s transaction infrastructure code only marks a transaction for rollback in the case of runtime, unchecked exceptions; that is, when the thrown exception is an instance or subclass of RuntimeException. ( Errors will also - by default - result in a rollback). Checked exceptions that are thrown from a transactional method do not result in rollback in the default configuration.

Admittedly, the hidden bug would be much more obvious if I wrote the code segment in Java language, because there isn't any difference between checked exception and runtime exception in Kotlin. In Java language, on the contrary, the exception must be handled or throw to the method caller explicitly, that could make this problem easier to identify. Nevertheless, I've made this kind of mistake while I was using Java, That's why I think it's worth to mention.
Now let's turn to the solution. According to the official document, we can just configure the @Transactional annotation to rollback for any exception. Or, we can catch the exception at the first place.

1
2
3
4
5
6
7
8
9
10

@Transactional
fun persist(demo: DemoEntity) {
    demoRepo.save(demo)

    try {
        unpredictableMethod()
    } catch (e: Exception) {
        // handle the exception
    }
}

Pitfall 4: Transaction may not be able to commit after an exception is being caught

After hours of tinkering, we finally get the piece of code work, But requirements are changing, let's say somehow we need to ensure the unpredictableMethod run with a transaction. After going through previous lessons, this time we want to do it extremely carefully.
Firstly, we put a @Transactional on the method and configure it to rollback for all exceptions, so that we won't fall into pitfall 3.

1
2
3
4
5
6
7
8
9

@Transactional(rollbackFor=[Exception::class])
fun unpredictableMethod() {
    /*
        some business code must be executed with a transaction
        ...
    */
    if (ThreadLocalRandom.current().nextBoolean())
        throw Exception("Oops!")
}

1
2
3
4
5
6
7
8
9
10

@Transactional
fun persist(demo: DemoEntity) {
    demoRepo.save(demo)

    try {
        self.unpredictableMethod()
    } catch (e: Exception) {
        // handle the exception
    }
}

When the propagation setting is PROPAGATION_REQUIRED, a logical transaction scope is created for each method upon which the setting is applied. Each such logical transaction scope can determine rollback-only status individually, with an outer transaction scope being logically independent from the inner transaction scope. Of course, in case of standard PROPAGATION_REQUIRED behavior, all these scopes will be mapped to the same physical transaction. So a rollback-only marker set in the inner transaction scope does affect the outer transaction’s chance to actually commit (as you would expect it to).
However, in the case where an inner transaction scope sets the rollback-only marker, the outer transaction has not decided on the rollback itself, and so the rollback (silently triggered by the inner transaction scope) is unexpected. A corresponding UnexpectedRollbackException is thrown at that point. This is expected behavior so that the caller of a transaction can never be misled to assume that a commit was performed when it really was not. So if an inner transaction (of which the outer caller is not aware) silently marks a transaction as rollback-only, the outer caller still calls commit. The outer caller needs to receive an UnexpectedRollbackException to indicate clearly that a rollback was performed instead.

The solution depends on what you want, you can change the propagation property of the second @Transactional, or change the rollbackFor and noRollbackFor property of the first @Transactional to filter a specific exception class. In this case, you can even fix the problem by falling into the pitfall 2 deliberately, although it is not recommended because your colleague may not be able to understand it.

Conclusion

Spring declarative transaction management does hide the complexity of writing transaction handling code, but handle transaction correctly is far more complex than just put an @Transactional annotation on your method. Considering transaction is usually the most critical part in an application, you'd better test every branch of your code.