[JBEAP-28311][JBWS-4430]:Add doc for the interceptors that access CDI…

… beans in WFLY
jbossws · Nov 13, 2024 · 5d278d4 · 5d278d4
1 parent 059a833
commit 5d278d4
Show file tree

Hide file tree

Showing 2 changed files with 106 additions and 0 deletions.
diff --git a/docbook/src/main/doc/adoc/content/chapter-5-Advanced_User_Guide.adoc b/docbook/src/main/doc/adoc/content/chapter-5-Advanced_User_Guide.adoc
@@ -1470,6 +1470,57 @@ A new instance of each specified interceptor class will be added to the
 client or endpoint the configuration is assigned to. The interceptor
 classes must have a no-argument constructor.
 
+When using CXF interceptors that access CDI beans in the WildFly environment, you need to ensure that
+the Thread Context ClassLoader (TCCL) is correctly set to make sure the CDI beans are loaded/read properly.
+To do this, CXF interceptors with CDI access should extend `org.jboss.wsf.stack.cxf.interceptor.AbstractTCCLPhaseInterceptor`
+and override the method `handleMessageWithTCCL(Message message)` to ensure the proper classloader is set before execution
+:
+```
+public class CDIOutInterceptor extends AbstractTCCLPhaseInterceptor<Message> {
+public CDIOutInterceptor() {
+super(Phase.PRE_STREAM);
+}
+   @Override
+   public void handleMessageWithTCCL(Message message) throws Fault {
+      if (!MessageUtils.isRequestor(message)) {
+         DelegateBean bean = new DelegateBean();
+      }
+   }
+}
+```
+```
+import jakarta.enterprise.context.Dependent;
+import jakarta.enterprise.inject.spi.CDI;
+@Dependent
+public class DelegateBean {
+    EmptyBean logic = CDI.current().select(EmptyBean.class).get();
+}
+```
+```
+@Dependent
+public class EmptyBean {
+}
+```
+The `AbstractTCCLPhaseInterceptor` can set the deployment classloader to thread context classloader before the
+handleMessage() method is called, and it restores the previous classloader afterward.
+Since AbstractTCCLPhaseInterceptor was created to set the thread context classloader and is included in
+'org.jboss.ws.cxf.jbossws-cxf-server' WildFly module dependency, you must add this necessary dependency to the MANIFEST.MF file of your deployment artifact.
+Additionally, don't forget to include the `org.apache.cxf` dependency for importing the cxf interceptor apis. Here is the package example code with Arquillian to
+add these two dependencies to the user's deployment artifact. Please use the same dependency adding format when
+including these dependencies to the MANIFEST.MF file:
+```
+    public static WebArchive createDeployment() {
+        WebArchive archive = ShrinkWrap.create(WebArchive.class, DEP + ".war");
+        archive.setManifest(new StringAsset("Manifest-Version: 1.0\n"
+                        + "Dependencies: org.apache.cxf,org.jboss.ws.cxf.jbossws-cxf-server\n"))
+                .addClasses(HelloBean.class, DelegateBean.class, EmptyBean.class, CDIOutInterceptor.class, LoggingHandler.class)
+                .addAsWebInfResource(new File(JBossWSTestHelper.getTestResourcesDir() + "/jaxws/cxf/jbws4430/WEB-INF/wsdl/HelloWorld.wsdl"), "wsdl/HelloWorld.wsdl")
+                .add(new FileAsset(new File(JBossWSTestHelper.getTestResourcesDir() + "/jaxws/cxf/jbws4430/handlers.xml")), "WEB-INF/classes/handlers.xml")
+                .setWebXML(new File(JBossWSTestHelper.getTestResourcesDir() + "/jaxws/cxf/jbws4430/WEB-INF/web.xml"));
+        return archive;
+    }
+```
+
 
 ==== Apache CXF features
 

diff --git a/docbook/src/main/doc/chapter-5-Advanced_User_Guide.xml b/docbook/src/main/doc/chapter-5-Advanced_User_Guide.xml
@@ -1696,6 +1696,61 @@ public static void setThreadDefaultBus(Bus bus)
 &lt;/jaxws-config&gt;</programlisting>
         </informalexample>
         <para>A new instance of each specified interceptor class will be added to the client or endpoint the configuration is assigned to. The interceptor classes must have a no-argument constructor.</para>
+        <para>When using CXF interceptors that access CDI beans in the WildFly environment, you need to ensure that
+        the Thread Context ClassLoader (TCCL) is correctly set to make sure the CDI beans are loaded/read properly.
+        To do this, CXF interceptors with CDI access should extend `org.jboss.wsf.stack.cxf.interceptor.AbstractTCCLPhaseInterceptor`
+        and override the method `handleMessageWithTCCL(Message message)` to ensure the proper classloader is set before execution
+        :</para>
+        <informalexample>
+         <programlisting>
+           public class CDIOutInterceptor extends AbstractTCCLPhaseInterceptor<Message> {
+             public CDIOutInterceptor() {
+               super(Phase.PRE_STREAM);
+             }
+             @Override
+             public void handleMessageWithTCCL(Message message) throws Fault {
+                if (!MessageUtils.isRequestor(message)) {
+                  DelegateBean bean = new DelegateBean();
+                }
+             }
+           }
+           ...
+
+           import jakarta.enterprise.context.Dependent;
+           import jakarta.enterprise.inject.spi.CDI;
+           @Dependent
+           public class DelegateBean {
+              EmptyBean logic = CDI.current().select(EmptyBean.class).get();
+           }
+
+           ...
+
+           @Dependent
+           public class EmptyBean {
+           }
+         </programlisting>
+        </informalexample>
+      <para>The `AbstractTCCLPhaseInterceptor` can set the deployment classloader to thread context classloader before the
+        handleMessage() method is called, and it restores the previous classloader afterward.
+        Since AbstractTCCLPhaseInterceptor was created to set the thread context classloader and is included in
+        'org.jboss.ws.cxf.jbossws-cxf-server' WildFly module dependency, you must add this necessary dependency to the MANIFEST.MF file of your deployment artifact.
+        Additionally, don't forget to include the `org.apache.cxf` dependency for importing the cxf interceptor apis. Here is the package example code with Arquillian to
+        add these two dependencies to the user's deployment artifact. Please use the same dependency adding format when
+        including these dependencies to the MANIFEST.MF file:</para>
+      <informalexample>
+        <programlisting>
+          public static WebArchive createDeployment() {
+             WebArchive archive = ShrinkWrap.create(WebArchive.class, DEP + ".war");
+             archive.setManifest(new StringAsset("Manifest-Version: 1.0\n"
+                                                 + "Dependencies: org.apache.cxf,org.jboss.ws.cxf.jbossws-cxf-server\n"))
+              .addClasses(HelloBean.class, DelegateBean.class, EmptyBean.class, CDIOutInterceptor.class, LoggingHandler.class)
+              .addAsWebInfResource(new File(JBossWSTestHelper.getTestResourcesDir() + "/jaxws/cxf/jbws4430/WEB-INF/wsdl/HelloWorld.wsdl"), "wsdl/HelloWorld.wsdl")
+              .add(new FileAsset(new File(JBossWSTestHelper.getTestResourcesDir() + "/jaxws/cxf/jbws4430/handlers.xml")), "WEB-INF/classes/handlers.xml")
+              .setWebXML(new File(JBossWSTestHelper.getTestResourcesDir() + "/jaxws/cxf/jbws4430/WEB-INF/web.xml"));
+             return archive;
+          }
+        </programlisting>
+      </informalexample>
       </section>
       <section id="sid-3866786_ApacheCXFintegration-ApacheCXFfeatures">