From 7e40363fe84a371fc54d0cc06b7ab66b506d7bfa Mon Sep 17 00:00:00 2001
From: Matej Novotny <manovotn@redhat.com>
Date: Fri, 28 Jun 2024 14:26:23 +0200
Subject: [PATCH] Arc - document intercepted self-invocation as a non-standard
 feature

---
 docs/src/main/asciidoc/cdi-reference.adoc | 29 +++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/src/main/asciidoc/cdi-reference.adoc b/docs/src/main/asciidoc/cdi-reference.adoc
index 29f1938ead089..e0057958e21e4 100644
--- a/docs/src/main/asciidoc/cdi-reference.adoc
+++ b/docs/src/main/asciidoc/cdi-reference.adoc
@@ -1069,6 +1069,35 @@ public class NoopAsyncObserverExceptionHandler implements AsyncObserverException
 }
 ----
 
+=== Intercepted self-invocation
+
+Quarkus supports what is known as intercepted self-invocation or just self-interception - a scenario where CDI bean invokes its own intercepted method from within another method while triggering any associated interceptors.
+This is a non-standard feature as CDI specification doesn't define whether self-interception should work or not.
+
+Suppose we have a CDI bean with two methods, one of which has the `@Transactional` interceptor binding associated with it:
+
+[source, java]
+----
+@ApplicationScoped
+public class MyService {
+
+  @Transactional <1>
+  void doSomething() {
+    // some application logic
+  }
+
+  void doSomethingElse() {
+    doSomething();<2>
+  }
+
+}
+----
+<1> One or more interceptor bindings; `@Transactional` is just an example.
+<2> Non-intercepted method invoking another method from the same bean that has associated binding(s); this will trigger interception.
+
+In the above example, any code calling the `doSomething()` method triggers interception - in this case, the method becomes transactional.
+This is regardless of whether the invocation originated directly from the `MyService` bean (such as `MyService#doSomethingElse`) or from some other bean.
+
 [[reactive_pitfalls]]
 == Pitfalls with Reactive Programming