WS-ReliableMessaging configuration options and documentation

docs/antora.yml

@@ -8,7 +8,7 @@ asciidoc:
   attributes:
 
     # Versions
-    quarkus-version: 3.6.3 # replace ${quarkus.version}
+    quarkus-version: 3.6.4 # replace ${quarkus.version}
     quarkus-cxf-version: 2.6.1 # replace ${release.current-version}
 
     # Toggle whether some page elements are rendered

docs/modules/ROOT/pages/includes/quarkus-cxf-rt-ws-rm.adoc

@@ -0,0 +1,180 @@
+
+:summaryTableId: quarkus-cxf-rt-ws-rm
+[.configuration-legend]
+icon:lock[title=Fixed at build time] Configuration property fixed at build time - All other configuration properties are overridable at runtime
+[.configuration-reference.searchable, cols="80,.^10,.^10"]
+|===
+
+h|[[quarkus-cxf-rt-ws-rm_configuration]]link:#quarkus-cxf-rt-ws-rm_configuration[Configuration property]
+
+h|Type
+h|Default
+
+a| [[quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.namespace]]`link:#quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.namespace[quarkus.cxf.rm.namespace]`
+
+
+[.description]
+--
+WS-RM version namespace: `http://schemas.xmlsoap.org/ws/2005/02/rm/` or `http://docs.oasis-open.org/ws-rx/wsrm/200702`
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_RM_NAMESPACE+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_RM_NAMESPACE+++`
+endif::add-copy-button-to-env-var[]
+--|string 
+|`http://schemas.xmlsoap.org/ws/2005/02/rm`
+
+
+a| [[quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.wsa-namespace]]`link:#quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.wsa-namespace[quarkus.cxf.rm.wsa-namespace]`
+
+
+[.description]
+--
+WS-Addressing version namespace: `http://schemas.xmlsoap.org/ws/2004/08/addressing` or `http://www.w3.org/2005/08/addressing`. Note that this property is ignored unless you are using the `http://schemas.xmlsoap.org/ws/2005/02/rm/` RM namespace.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_RM_WSA_NAMESPACE+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_RM_WSA_NAMESPACE+++`
+endif::add-copy-button-to-env-var[]
+--|string 
+|`http://schemas.xmlsoap.org/ws/2004/08/addressing`
+
+
+a| [[quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.inactivity-timeout]]`link:#quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.inactivity-timeout[quarkus.cxf.rm.inactivity-timeout]`
+
+
+[.description]
+--
+A time duration in milliseconds after which the associated sequence will be closed if no messages (including acknowledgments and other control messages) were exchanged between the sender and receiver during that period of time. If not set, the associated sequence will never be closed due to inactivity.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_RM_INACTIVITY_TIMEOUT+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_RM_INACTIVITY_TIMEOUT+++`
+endif::add-copy-button-to-env-var[]
+--|long 
+|
+
+
+a| [[quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.retransmission-interval]]`link:#quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.retransmission-interval[quarkus.cxf.rm.retransmission-interval]`
+
+
+[.description]
+--
+A time duration in milliseconds between successive attempts to resend a message that has not been acknowledged by the receiver.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_RM_RETRANSMISSION_INTERVAL+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_RM_RETRANSMISSION_INTERVAL+++`
+endif::add-copy-button-to-env-var[]
+--|long 
+|`3000`
+
+
+a| [[quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.exponential-backoff]]`link:#quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.exponential-backoff[quarkus.cxf.rm.exponential-backoff]`
+
+
+[.description]
+--
+If `true` the retransmission interval will be doubled on every transmission attempt; otherwise the retransmission interval stays equal to `quarkus.cxf.rm.retransmission-interval` for every retransmission attempt.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_RM_EXPONENTIAL_BACKOFF+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_RM_EXPONENTIAL_BACKOFF+++`
+endif::add-copy-button-to-env-var[]
+--|boolean 
+|`false`
+
+
+a| [[quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.acknowledgement-interval]]`link:#quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.acknowledgement-interval[quarkus.cxf.rm.acknowledgement-interval]`
+
+
+[.description]
+--
+A time duration in milliseconds within which an acknowledgement for a received message is expected to be sent by a RM destination. If not specified, the acknowledgements will be sent immediately.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_RM_ACKNOWLEDGEMENT_INTERVAL+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_RM_ACKNOWLEDGEMENT_INTERVAL+++`
+endif::add-copy-button-to-env-var[]
+--|long 
+|
+
+
+a| [[quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.store]]`link:#quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.store[quarkus.cxf.rm.store]`
+
+
+[.description]
+--
+A link:../../user-guide/configuration.html#beanRefs[reference] to a `org.apache.cxf.ws.rm.persistence.RMStore` bean used to store source and destination sequences and message references.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_RM_STORE+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_RM_STORE+++`
+endif::add-copy-button-to-env-var[]
+--|string 
+|
+
+
+a| [[quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.feature-ref]]`link:#quarkus-cxf-rt-ws-rm_quarkus.cxf.rm.feature-ref[quarkus.cxf.rm.feature-ref]`
+
+
+[.description]
+--
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_RM_FEATURE_REF+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_RM_FEATURE_REF+++`
+endif::add-copy-button-to-env-var[]
+--|string 
+|`#defaultRmFeature`
+
+
+a| [[quarkus-cxf-rt-ws-rm_quarkus.cxf.client.-clients-.rm.enabled]]`link:#quarkus-cxf-rt-ws-rm_quarkus.cxf.client.-clients-.rm.enabled[quarkus.cxf.client."clients".rm.enabled]`
+
+
+[.description]
+--
+If `true` then the WS-ReliableMessaging link:https://cxf.apache.org/docs/ws-reliablemessaging.html[interceptors] will be added to this client or service endpoint.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_CLIENT__CLIENTS__RM_ENABLED+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_CLIENT__CLIENTS__RM_ENABLED+++`
+endif::add-copy-button-to-env-var[]
+--|boolean 
+|`true`
+
+
+a| [[quarkus-cxf-rt-ws-rm_quarkus.cxf.endpoint.-endpoints-.rm.enabled]]`link:#quarkus-cxf-rt-ws-rm_quarkus.cxf.endpoint.-endpoints-.rm.enabled[quarkus.cxf.endpoint."endpoints".rm.enabled]`
+
+
+[.description]
+--
+If `true` then the WS-ReliableMessaging link:https://cxf.apache.org/docs/ws-reliablemessaging.html[interceptors] will be added to this client or service endpoint.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_ENDPOINT__ENDPOINTS__RM_ENABLED+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_ENDPOINT__ENDPOINTS__RM_ENABLED+++`
+endif::add-copy-button-to-env-var[]
+--|boolean 
+|`true`
+
+|===

docs/modules/ROOT/pages/includes/quarkus-cxf.adoc

@@ -10,25 +10,6 @@ h|[[quarkus-cxf_configuration]]link:#quarkus-cxf_configuration[Configuration pro
 h|Type
 h|Default
 
-a|icon:lock[title=Fixed at build time] [[quarkus-cxf_quarkus.cxf.path]]`link:#quarkus-cxf_quarkus.cxf.path[quarkus.cxf.path]`
-
-
-[.description]
---
-The default path for CXF resources.
-
-⚠️ Note that the default value before Quarkus CXF version 2.0.0 was `/`.
-
-ifdef::add-copy-button-to-env-var[]
-Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_PATH+++[]
-endif::add-copy-button-to-env-var[]
-ifndef::add-copy-button-to-env-var[]
-Environment variable: `+++QUARKUS_CXF_PATH+++`
-endif::add-copy-button-to-env-var[]
---|string 
-|`/services`
-
-
 a|icon:lock[title=Fixed at build time] [[quarkus-cxf_quarkus.cxf.codegen.wsdl2java.enabled]]`link:#quarkus-cxf_quarkus.cxf.codegen.wsdl2java.enabled[quarkus.cxf.codegen.wsdl2java.enabled]`
 
 
@@ -517,6 +498,25 @@ endif::add-copy-button-to-env-var[]
 |
 
 
+a|icon:lock[title=Fixed at build time] [[quarkus-cxf_quarkus.cxf.path]]`link:#quarkus-cxf_quarkus.cxf.path[quarkus.cxf.path]`
+
+
+[.description]
+--
+The default path for CXF resources.
+
+⚠️ Note that the default value before Quarkus CXF version 2.0.0 was `/`.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_PATH+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_PATH+++`
+endif::add-copy-button-to-env-var[]
+--|string 
+|`/services`
+
+
 a|icon:lock[title=Fixed at build time] [[quarkus-cxf_quarkus.cxf.min-chunk-size]]`link:#quarkus-cxf_quarkus.cxf.min-chunk-size[quarkus.cxf.min-chunk-size]`
 
 
@@ -2388,7 +2388,7 @@ a| [[quarkus-cxf_quarkus.cxf.client.-clients-.decoupled-endpoint]]`link:#quarkus
 
 [.description]
 --
-Specifies the URL of a decoupled endpoint for the receipt of responses over a separate provider->consumer connection.
+An URI path (starting with `/`) or a full URI for the receipt of responses over a separate provider -> consumer connection. If the value starts with `/`, then it is prefixed with the base URI configured via `quarkus.cxf.client.myClient.decoupled-endpoint-base` before being used as a value for the WS-Addressing `ReplyTo` message header.
 
 ifdef::add-copy-button-to-env-var[]
 Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_CLIENT__CLIENTS__DECOUPLED_ENDPOINT+++[]
@@ -2400,6 +2400,70 @@ endif::add-copy-button-to-env-var[]
 |
 
 
+a| [[quarkus-cxf_quarkus.cxf.client.-clients-.decoupled-endpoint-base]]`link:#quarkus-cxf_quarkus.cxf.client.-clients-.decoupled-endpoint-base[quarkus.cxf.client."clients".decoupled-endpoint-base]`
+
+
+[.description]
+--
+An URI base to use as a prefix of `quarkus.cxf.client.myClient.decoupled-endpoint`. You will typically want to set this to something like the following:
+
+```
+quarkus.cxf.client.myClient.decoupled-endpoint-base = https://api.example.com:${quarkus.http.ssl-port}${quarkus.cxf.path}
+# or for plain HTTP
+quarkus.cxf.client.myClient.decoupled-endpoint-base = http://api.example.com:${quarkus.http.port}${quarkus.cxf.path}
+```
+
+If you invoke your WS client from within a HTTP handler, you can leave this option unspecified and rather set it dynamically on the request context of your WS client using the `org.apache.cxf.ws.addressing.decoupled.endpoint.base` key. Here is an example how to do that from a RESTeasy handler method:
+
+```
+import java.util.Map;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.Context;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.UriInfo;
+import jakarta.xml.ws.BindingProvider;
+import io.quarkiverse.cxf.annotation.CXFClient;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+@Path("/my-rest")
+public class MyRestEasyResource {
+
+    @Inject
+    @CXFClient("hello")
+    HelloService helloService;
+
+    @ConfigProperty(name = "quarkus.cxf.path")
+    String quarkusCxfPath;
+
+    @POST
+    @Path("/hello")
+    @Produces(MediaType.TEXT_PLAIN)
+    public String hello(String body, @Context UriInfo uriInfo) throws IOException {
+
+        // You may consider doing this only once if you are sure that your service is accessed
+        // through a single hostname
+        String decoupledEndpointBase = uriInfo.getBaseUriBuilder().path(quarkusCxfPath);
+        Map>String, Object< requestContext = ((BindingProvider) helloService).getRequestContext();
+        requestContext.put("org.apache.cxf.ws.addressing.decoupled.endpoint.base", decoupledEndpointBase);
+
+        return wsrmHelloService.hello(body);
+    }
+}
+```
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_CLIENT__CLIENTS__DECOUPLED_ENDPOINT_BASE+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_CLIENT__CLIENTS__DECOUPLED_ENDPOINT_BASE+++`
+endif::add-copy-button-to-env-var[]
+--|string 
+|
+
+
 a| [[quarkus-cxf_quarkus.cxf.client.-clients-.proxy-server]]`link:#quarkus-cxf_quarkus.cxf.client.-clients-.proxy-server[quarkus.cxf.client."clients".proxy-server]`
 
 

docs/modules/ROOT/pages/reference/extensions/quarkus-cxf-rt-ws-rm.adoc

@@ -5,15 +5,18 @@
 :linkattrs:
 :cq-artifact-id: quarkus-cxf-rt-ws-rm
 :cq-group-id: io.quarkiverse.cxf
-:cq-status: Experimental
+:cq-status: Stable
 :cq-deprecated: false
 :cq-since: 1.5.3
 
 ifeval::[{doc-show-badges} == true]
-🧪Experimental • Since 1.5.3
+Stable • Since 1.5.3
 endif::[]
 
-IMPORTANT: This extension is https://github.com/quarkiverse/quarkus-cxf/issues/627[known not to work]. Contributions are welcome!
+WS-ReliableMessaging (WS-RM) is a protocol ensuring a reliable delivery of messages in a distributed environment even in presence of software, system, or network failures.
+
+This extension provides CXF framework's https://cxf.apache.org/docs/ws-reliablemessaging.html[WS-ReliableMessaging] implementation.
+
 
 
 [id="quarkus-cxf-rt-ws-rm-maven-coordinates"]
@@ -40,3 +43,52 @@ endif::[]
 
 * https://cxf.apache.org/docs/ws-reliablemessaging.html[WS-ReliableMessaging]
 
+
+[id="quarkus-cxf-rt-ws-rm-usage"]
+== Usage
+
+Once your application depends on `quarkus-cxf-rt-ws-rm`, WS-RM is enabled for all clients and service endpoints defined in `application.properties`.
+This is due to the fact that the `quarkus.cxf.client.myClient.rm.enabled` and `quarkus.cxf.endpoint."/my-endpoint".rm.enabled`
+properties are `true` by default.
+
+Enabling WS-RM for a client or service endpoints means that https://cxf.apache.org/docs/ws-reliablemessaging.html[WS-RM interceptors] will be added to the given client or endpoint.
+
+In addition to that you may want to set some of the options documented xref:#quarkus-cxf-rt-ws-rm-configuration[below] and/or the following WS-Addressing options:
+
+* xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus.cxf.client.-clients-.decoupled-endpoint[quarkus.cxf.client.myClient.decoupled-endpoint]
+* xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus.cxf.client.-clients-.decoupled-endpoint-base[quarkus.cxf.client.myClient.decoupled-endpoint-base]
+
+[id="extensions-quarkus-cxf-rt-ws-rm-usage-runnable-example"]
+=== Runnable example
+
+There is an integration test covering WS-RM with a decoupled endpoint in the {quarkus-cxf-project-name} source tree.
+
+It is split into two separate applications that communicate with each other:
+
+* https://github.com/quarkiverse/quarkus-cxf/tree/main/test-util-parent/test-ws-rm-server[Server]
+* https://github.com/quarkiverse/quarkus-cxf/tree/main/integration-tests/ws-rm-client[Client]
+
+To run it, you need to install the server into your local Maven repository first
+
+[source,java]
+----
+$ cd test-util-parent/test-ws-rm-server
+$ mvn clean install
+----
+
+And then you can run the
+https://github.com/quarkiverse/quarkus-cxf/blob/main/integration-tests/ws-rm-client/src/test/java/io/quarkiverse/cxf/it/ws/rm/client/WsReliableMessagingTest.java#L28[test scenario]
+implemented in the client module:
+
+[source,java]
+----
+$ cd ../../integration-tests/ws-rm-client
+$ mvn clean test
+----
+
+You should see the exchange of SOAP messages between the client, the server and the decoupled endpoint in the console.
+
+
+[id="quarkus-cxf-rt-ws-rm-configuration"]
+== Configuration
+include::../../includes/quarkus-cxf-rt-ws-rm.adoc[]