Document semantics for combining `@Retryable` with other proxy-based features

[sbrannen]

Since we introduced @Retryable, we have received questions regarding how @Retryable works when combined with other proxy-based features.

We should therefore document (and test) the semantics for the combination of such features.

Candidate features to document/test:

• @Retryable
• @Async
• @Transactional
• @Cacheable

[polyglot-k]

Would it be alright if I try this? @sbrannen

[sbrannen]

Hi @polyglot-k,

I'm not sure how experienced you are with Spring AOP and the features in question, but if you feel confident about that, feel free to try this.

Before we introduce documentation, we need to first verify that the status quo works as expected. For that, we will need dedicated integration tests that combine the features and verify the expected order in which each AOP advice is applied.

In addition, it would probably be best to test various scenarios using Spring Boot 4.0 snapshots (and its auto-configuration) as well.

If things don't work as expected, we will need to address any issues (i.e., fix bugs and/or tweak settings).

If you encounter bugs, etc., it might be best to report those as you find them, so that we can address them in separate issues.

Once things work as expected, we can document the behavior.

Do you feel comfortable with those tasks?

[polyglot-k]

Thank you for your response, @sbrannen
I have explored the internal workings of annotations like @Retryable, @Async, @Transactional, and @Cacheable in depth, so I am confident in my ability to handle writing integration tests and verifying the advice order based on that knowledge. I will also report any issues promptly to ensure they are addressed efficiently.

[polyglot-k]

So, the idea is to document the behavior of these annotations in combination by using tests, right?
Is my understanding correct?

[sbrannen]

So, the idea is to document the behavior of these annotations in combination by using tests, right? Is my understanding correct?

The tests are for us and will serve 2-3 purposes.

1. Verify the expected behavior.
2. Serve as regression tests for the combinations of these features.
3. Potentially to be reused in documentation in the reference manual (i.e., copied in a scaled-down form).

The documentation is naturally for end users.

1. Minimal documentation in at least the Javadoc for @Retryable.
2. More in-depth documentation with examples in the reference manual, or perhaps just a single example in a section which explains the topic in general as well as the expected advice application order when using the features in question.

I suppose the documentation in the reference manual could reside in the new "Resilience" chapter, and other sections (like those for @Async and @Transactional) could cross-reference this new section.

[polyglot-k]

@sbrannen Okay, I’ll get started right away.