quarkiverse · ppalaga · Feb 6, 2025 · Feb 6, 2025 · Feb 6, 2025
@@ -8,7 +8,7 @@ asciidoc:
   attributes:
 
     # Versions
-    quarkus-version: 3.18.1 # replace ${quarkus.version}
+    quarkus-version: 3.18.2 # replace ${quarkus.version}
     quarkus-cxf-version: 3.18.1 # replace ${release.current-version}
 
     # Toggle whether some page elements are rendered

@@ -22,6 +22,7 @@
 *** xref:user-guide/advanced-client-topics/client-endpoint-url-defaults.adoc[`client-endpoint-url` defaults]
 *** xref:user-guide/advanced-client-topics/configure-multiple-clients.adoc[Configure multiple clients]
 *** xref:user-guide/advanced-client-topics/cdi-scope-of-cxfclient.adoc[CDI scope of clients injected via `@CXFClient`]
+*** xref:user-guide/advanced-client-topics/synchronous-vs-asynchronous-client.adoc[Synchronous vs. Asynchronous client]
 *** xref:user-guide/advanced-client-topics/programmatic-client-configuration-at-startup.adoc[Configure clients programmatically at application startup]
 *** xref:user-guide/advanced-client-topics/dynamic-client-configuration.adoc[Dynamic client configuration]
 *** xref:user-guide/advanced-client-topics/pure-client-applications.adoc[Pure client applications]

@@ -6,13 +6,19 @@
 :cq-artifact-id: quarkus-cxf-rt-transports-http-hc5
 :cq-group-id: io.quarkiverse.cxf
 :cq-status: Stable
-:cq-deprecated: false
+:cq-deprecated: true
 :cq-since: 1.1.0
 
 ifeval::[{doc-show-badges} == true]
-Stable • Since 1.1.0
+Stable • Since 1.1.0 • ⚠️Deprecated
 endif::[]
 
+[IMPORTANT]
+====
+This extension is deprecated since {quarkus-cxf-project-name} 3.19.0 and is scheduled for removal in 3.21.0.
+Use the xref:user-guide/advanced-client-topics/synchronous-vs-asynchronous-client.adoc[asynchronous mode of `VertxHttpClientHTTPConduit`] instead.
+====
+
 Implement async SOAP Clients using Apache HttpComponents HttpClient 5.
 
 
@@ -44,49 +50,6 @@ endif::[]
 Once the `quarkus-cxf-rt-transports-http-hc5` dependency is available in the classpath,
 CXF will use `HttpAsyncClient` for asynchronous calls and will continue using `HttpURLConnection` for synchronous calls.
 
-
-[[wsdl2java]]
-[id="extensions-quarkus-cxf-rt-transports-http-hc5-usage-generate-async-methods"]
-=== Generate async methods
-
-Asynchronous client invocations require some additional methods in the service endpoint interface.
-That code is not generated by default.
-
-To enable it, you need to create a JAX-WS binding file with `enableAsyncMapping` set to `true`:
-
-[TIP]
-====
-The sample code snippets used in this section come from the
-https://github.com/quarkiverse/quarkus-cxf/tree/main/integration-tests/hc5[HC5 integration test]
-in the source tree of {quarkus-cxf-project-name}
-====
-
-.src/main/resources/wsdl/async-binding.xml
-[source,xml]
-----
-include::example$hc5/async-binding.xml[]
-----
-
-This file should then be passed to xref:user-guide/contract-first-code-first/generate-java-from-wsdl.adoc[wsdl2java]
-through its xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus-cxf-codegen-wsdl2java-additional-params[additional-params] property:
-
-.application.properties
-[source,properties]
-----
-include::example$hc5/application.properties[tag=quarkus-cxf-rt-transports-http-hc5.usage.wsdl2java]
-----
-
-[[async-uni]]
-[id="extensions-quarkus-cxf-rt-transports-http-hc5-usage-asynchronous-clients-and-mutiny"]
-=== Asynchronous Clients and Mutiny
-
-Once the asynchronous stubs are available, it is possible to wrap a client call in `io.smallrye.mutiny.Uni` as shown below:
-
-[source,java]
-----
-include::example$hc5/Hc5Resource.java[tag=quarkus-cxf-rt-transports-http-hc5.usage.mutiny]
-----
-
 [id="extensions-quarkus-cxf-rt-transports-http-hc5-usage-thread-pool"]
 === Thread pool
 
@@ -100,3 +63,8 @@ As a consequence of this, the executor and thread pool related attributes of `or
 You can see more details about the CXF asynchronous client and how to tune it further in https://cxf.apache.org/docs/asynchronous-client-http-transport.html[CXF documentation].
 ====
 
+[id="extensions-quarkus-cxf-rt-transports-http-hc5-usage-see-also"]
+=== See also
+
+* xref:user-guide/advanced-client-topics/synchronous-vs-asynchronous-client.adoc[Synchronous vs. Asynchronous client]
+
@@ -60,6 +60,7 @@ There are several chapters in the xref:user-guide/index.adoc[User guide] coverin
 * xref:user-guide/ssl-tls-https.adoc[SSL]
 * xref:user-guide/authentication-authorization.adoc[Authentication and authorization]
 * xref:user-guide/advanced-soap-client-topics.adoc[Advanced SOAP client topics]
+* xref:user-guide/advanced-client-topics/synchronous-vs-asynchronous-client.adoc[Synchronous vs. Asynchronous client]
 * xref:user-guide/advanced-service-topics/running-behind-a-reverse-proxy.adoc[Running behind a reverse proxy]
 * xref:user-guide/contract-first-code-first/generate-java-from-wsdl.adoc[Generate Java from WSDL]
 * xref:user-guide/contract-first-code-first/generate-wsdl-from-java.adoc[Generate WSDL from Java]

@@ -7,7 +7,7 @@
 The following table shows the {quarkus-cxf-project-name} extensions.
 Click the extension names to learn more about how to configure and use them, and about any known limitations.
 
-[cols="4,1,1,4"]
+[cols="40,25,10,40"]
 |===
 | Quarkus CXF extension | Support level | Since | Supported standards
 // standards: START
@@ -51,6 +51,7 @@ Click the extension names to learn more about how to configure and use them, and
 | xref:reference/extensions/quarkus-cxf-rt-transports-http-hc5.adoc[Quarkus CXF HTTP Async Transport] +
 `quarkus-cxf-rt-transports-http-hc5`
 |Stable
+⚠️Deprecated
 |1.1.0
 |
 
@@ -94,10 +95,9 @@ Out of https://cxf.apache.org/docs/databindings.html[CXF Data Bindings] only the
 Out of https://cxf.apache.org/docs/transports.html[CXF Transports] only the following ones are supported:
 
 * `quarkus-cxf` implements its own custom transport based on Quarkus and Vert.x for serving SOAP endpoints
-* HTTP client via `xref:reference/extensions/quarkus-cxf.adoc[quarkus-cxf]`, including
+* SOAP client via `xref:reference/extensions/quarkus-cxf.adoc[io.quarkiverse.cxf:quarkus-cxf]` extension, including
+** Synchronous and xref:user-guide/advanced-client-topics/synchronous-vs-asynchronous-client.adoc[asynchronous] mode
 ** xref:user-guide/authentication-authorization.adoc[Basic Authentication]
-* https://cxf.apache.org/docs/asynchronous-client-http-transport.html[Asynchronous Client HTTP Transport]
-  via `xref:reference/extensions/quarkus-cxf-rt-transports-http-hc5.adoc[quarkus-cxf-rt-transports-http-hc5]`
 
 [[tools]]
 === Tools

@@ -42,7 +42,7 @@ This works much like with the existing `xref:reference/extensions/quarkus-cxf-rt
 The main difference is that you do not need to add the `io.quarkiverse.cxf:quarkus-cxf-rt-transports-http-hc5` dependency to your application anymore.
 
 You still need to
-xref:reference/extensions/quarkus-cxf-rt-transports-http-hc5.adoc#extensions-quarkus-cxf-rt-transports-http-hc5-usage-generate-async-methods[generate the async methods]
+xref:user-guide/advanced-client-topics/synchronous-vs-asynchronous-client.adoc#extensions-quarkus-cxf-rt-transports-http-hc5-usage-generate-async-methods[generate the async methods]
 using the embedded `wsdl2java` tool.
 
 We plan to https://github.com/quarkiverse/quarkus-cxf/issues/1619[add a new documentation page] dedicated to this topic.

@@ -0,0 +1,88 @@
+[[synchronous-vs-asynchronous-client]]
+= Synchronous vs. asynchronous SOAP client
+
+When calling a SOAP client synchronously, the service method does not return before the response from the remote service is completely received and parsed:
+
+[source,java]
+----
+@CXFClient("hello")
+HelloService hello;
+
+void callHello() {
+    // Synchronous CXF client call
+    String result = hello.hello("Joe");
+    Log.info(result);
+}
+----
+
+When calling the client asynchronously, the service method may terminate before the response from the remote service was received.
+The result is an instance of `jakarta.xml.ws.Response` extending `java.util.concurrent.Future`.
+It represents the result of an asynchronous computation,
+which may have completed already or will be completed in the future.
+
+`java.util.concurrent.Future` can be transformed to https://smallrye.io/smallrye-mutiny/latest/[SmallRye Mutiny] `Uni` type
+and further used as a return value of a https://quarkus.io/guides/rest#asyncreactive-support[reactive REST endpoint]:
+
+[source,java]
+----
+import io.smallrye.mutiny.Uni;
+import jakarta.xml.ws.Response;
+
+@CXFClient("hello")
+HelloService hello;
+
+Uni<String> callHelloAsync() {
+    // Asynchronous CXF client call returning jakarta.xml.ws.Response
+    Response<HelloResponse> helloResponseFuture = hello.helloAsync("Joe");
+    return Uni.createFrom()
+            .future(helloResponseFuture)
+            .map(HelloResponse::getReturn);
+}
+----
+
+[NOTE]
+====
+The `java.util.concurrent.Future` interface has limited capabilities for reactive styles of programming.
+Internally, the above `future(helloResponseFuture)` call polls on `Future.isDone()` on a worker thread to void blocking Vert.x Event Loop.
+Therefore, the performance expectations should not be too high.
+====
+
+[[wsdl2java]]
+[id="extensions-quarkus-cxf-rt-transports-http-hc5-usage-generate-async-methods"]
+== Generate async methods
+
+Asynchronous client invocations require some additional methods in the service endpoint interface.
+That code is not generated by default.
+
+To enable it, you need to create a JAX-WS binding file with `enableAsyncMapping` set to `true`:
+
+[TIP]
+====
+The sample code snippets used in this section come from the
+https://github.com/quarkiverse/quarkus-cxf/tree/main/integration-tests/hc5[HC5 integration test]
+in the source tree of {quarkus-cxf-project-name}
+====
+
+.src/main/resources/wsdl/async-binding.xml
+[source,xml]
+----
+include::example$hc5/async-binding.xml[]
+----
+
+This file should then be passed to xref:user-guide/contract-first-code-first/generate-java-from-wsdl.adoc[wsdl2java]
+through its xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus-cxf-codegen-wsdl2java-additional-params[additional-params] property:
+
+.application.properties
+[source,properties]
+----
+include::example$hc5/application.properties[tag=quarkus-cxf-rt-transports-http-hc5.usage.wsdl2java]
+----
+
+== Historical note
+
+Since {quarkus-cxf-project-name} 3.17.0, the asynchronous mode is supported by `VertxHttpClientHTTPConduit` provided via the
+`xref:reference/extensions/quarkus-cxf.adoc[io.quarkiverse.cxf:quarkus-cxf]` extension.
+
+Before {quarkus-cxf-project-name} 3.17.0, the asynchronous use case was only supported via
+`xref:reference/extensions/quarkus-cxf-rt-transports-http-hc5.adoc[io.quarkiverse.cxf:quarkus-cxf-rt-transports-http-hc5]`
+which is now deprecated and scheduled for removal in {quarkus-cxf-project-name} 3.21.0.
@@ -8,6 +8,7 @@ There are several chapters in the xref:user-guide/index.adoc[User guide] coverin
 * xref:user-guide/ssl-tls-https.adoc[SSL]
 * xref:user-guide/authentication-authorization.adoc[Authentication and authorization]
 * xref:user-guide/advanced-soap-client-topics.adoc[Advanced SOAP client topics]
+* xref:user-guide/advanced-client-topics/synchronous-vs-asynchronous-client.adoc[Synchronous vs. Asynchronous client]
 * xref:user-guide/advanced-service-topics/running-behind-a-reverse-proxy.adoc[Running behind a reverse proxy]
 * xref:user-guide/contract-first-code-first/generate-java-from-wsdl.adoc[Generate Java from WSDL]
 * xref:user-guide/contract-first-code-first/generate-wsdl-from-java.adoc[Generate WSDL from Java]

@@ -14,6 +14,7 @@
 
     <properties>
         <cq.since>1.1.0</cq.since>
+        <quarkus.metadata.deprecated>true</quarkus.metadata.deprecated>
     </properties>
 
     <dependencies>

@@ -1 +1,7 @@
-Implement async SOAP Clients using Apache HttpComponents HttpClient 5.
+[IMPORTANT]
+====
+This extension is deprecated since {quarkus-cxf-project-name} 3.19.0 and is scheduled for removal in 3.21.0.
+Use the xref:user-guide/advanced-client-topics/synchronous-vs-asynchronous-client.adoc[asynchronous mode of `VertxHttpClientHTTPConduit`] instead.
+====
+
+Implement async SOAP Clients using Apache HttpComponents HttpClient 5.
@@ -1,47 +1,6 @@
 Once the `quarkus-cxf-rt-transports-http-hc5` dependency is available in the classpath,
 CXF will use `HttpAsyncClient` for asynchronous calls and will continue using `HttpURLConnection` for synchronous calls.
 
-
-[[wsdl2java]]
-=== Generate async methods
-
-Asynchronous client invocations require some additional methods in the service endpoint interface.
-That code is not generated by default.
-
-To enable it, you need to create a JAX-WS binding file with `enableAsyncMapping` set to `true`:
-
-[TIP]
-====
-The sample code snippets used in this section come from the
-https://github.com/quarkiverse/quarkus-cxf/tree/main/integration-tests/hc5[HC5 integration test]
-in the source tree of {quarkus-cxf-project-name}
-====
-
-.src/main/resources/wsdl/async-binding.xml
-[source,xml]
-----
-include::example$hc5/async-binding.xml[]
-----
-
-This file should then be passed to xref:user-guide/contract-first-code-first/generate-java-from-wsdl.adoc[wsdl2java]
-through its xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus-cxf-codegen-wsdl2java-additional-params[additional-params] property:
-
-.application.properties
-[source,properties]
-----
-include::example$hc5/application.properties[tag=quarkus-cxf-rt-transports-http-hc5.usage.wsdl2java]
-----
-
-[[async-uni]]
-=== Asynchronous Clients and Mutiny
-
-Once the asynchronous stubs are available, it is possible to wrap a client call in `io.smallrye.mutiny.Uni` as shown below:
-
-[source,java]
-----
-include::example$hc5/Hc5Resource.java[tag=quarkus-cxf-rt-transports-http-hc5.usage.mutiny]
-----
-
 === Thread pool
 
 Asynchronous clients delivered by this extension leverage `ManagedExecutor` with a thread pool provided by Quarkus.
@@ -53,3 +12,7 @@ As a consequence of this, the executor and thread pool related attributes of `or
 ====
 You can see more details about the CXF asynchronous client and how to tune it further in https://cxf.apache.org/docs/asynchronous-client-http-transport.html[CXF documentation].
 ====
+
+=== See also
+
+* xref:user-guide/advanced-client-topics/synchronous-vs-asynchronous-client.adoc[Synchronous vs. Asynchronous client]
@@ -9,3 +9,5 @@ metadata:
   categories:
     - "integration"
   guide: "https://quarkiverse.github.io/quarkiverse-docs/quarkus-cxf/dev/reference/extensions/quarkus-cxf-rt-transports-http-hc5.html"
+  status: "deprecated"
+  unlisted: true
@@ -76,7 +76,7 @@
 
         <supported-maven.versions>[3.6.2,)</supported-maven.versions>
 
-        <cq-maven-plugin.version>4.16.1</cq-maven-plugin.version>
+        <cq-maven-plugin.version>4.16.2</cq-maven-plugin.version>
         <exec-maven-plugin.version>3.5.0</exec-maven-plugin.version>
         <groovy-maven-plugin.version>2.1.1</groovy-maven-plugin.version>
         <groovy.version>3.0.23</groovy.version>