You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by pp...@apache.org on 2023/05/15 15:09:05 UTC
[camel-quarkus] 03/06: Document CXF SOAP usage, configuration and limitations
This is an automated email from the ASF dual-hosted git repository.
ppalaga pushed a commit to branch 2.13.x
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
commit f4f6c435dfd10fc0ac091265c1258cc8beb58152
Author: Peter Palaga <pp...@redhat.com>
AuthorDate: Thu Apr 20 21:49:30 2023 +0200
Document CXF SOAP usage, configuration and limitations
---
docs/antora.yml | 6 +
.../ROOT/pages/reference/extensions/cxf-soap.adoc | 250 +++++++++++++++++++++
.../cxf-soap/runtime/src/main/doc/usage.adoc | 239 ++++++++++++++++++++
3 files changed, 495 insertions(+)
diff --git a/docs/antora.yml b/docs/antora.yml
index 262230aec0..eb9aff1211 100644
--- a/docs/antora.yml
+++ b/docs/antora.yml
@@ -45,7 +45,13 @@ asciidoc:
doc-show-extra-content: false # Whether additional content hosted in external AsciiDoc files should be loaded via an include:: directive
# External URLs
+ link-camel-quarkus-source: https://github.com/apache/camel-quarkus/tree/2.13.x
link-quarkus-code-generator: code.quarkus.io
+ link-quarkus-cxf-doc: https://quarkiverse.github.io/quarkiverse-docs/quarkus-cxf/1.5
+ link-quarkus-cxf-source: https://github.com/quarkiverse/quarkus-cxf/tree/1.5
+
+ # Misc
+ javaxOrJakartaPackagePrefix: javax # this can be switched to javax in older branches
# Project name
project-name: "Camel Quarkus"
diff --git a/docs/modules/ROOT/pages/reference/extensions/cxf-soap.adoc b/docs/modules/ROOT/pages/reference/extensions/cxf-soap.adoc
index b8481bf68f..91bc1a798f 100644
--- a/docs/modules/ROOT/pages/reference/extensions/cxf-soap.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/cxf-soap.adoc
@@ -43,3 +43,253 @@ Or add the coordinates to your existing project:
ifeval::[{doc-show-user-guide-link} == true]
Check the xref:user-guide/index.adoc[User guide] for more information about writing Camel Quarkus applications.
endif::[]
+
+[id="extensions-cxf-soap-usage"]
+== Usage
+[id="extensions-cxf-soap-usage-general"]
+=== General
+
+`camel-quarkus-cxf-soap` uses extensions from the {link-quarkus-cxf-doc}[CXF Extensions for Quarkus] project - `quarkus-cxf`.
+This means the set of supported use cases and WS specifications is largely given by `quarkus-cxf`.
+
+IMPORTANT: To learn about supported use cases and WS specifications, see the Quarkus CXF {link-quarkus-cxf-doc}/reference/index.html[Reference].
+
+[id="extensions-cxf-soap-usage-dependency-management"]
+=== Dependency management
+
+The CXF and `quarkus-cxf` versions are xref:user-guide/dependency-management.adoc[managed] by {project-name}. You do not need select compatible versions for those projects.
+
+[id="extensions-cxf-soap-usage-client"]
+=== Client
+
+With `camel-quarkus-cxf-soap` (no additional dependencies required), you can use CXF clients as producers in Camel routes:
+
+[source,java]
+----
+import org.apache.camel.builder.RouteBuilder;
+import {javaxOrJakartaPackagePrefix}.enterprise.context.ApplicationScoped;
+import {javaxOrJakartaPackagePrefix}.enterprise.context.SessionScoped;
+import {javaxOrJakartaPackagePrefix}.enterprise.inject.Produces;
+import {javaxOrJakartaPackagePrefix}.inject.Named;
+
+@ApplicationScoped
+public class CxfSoapClientRoutes extends RouteBuilder {
+
+ @Override
+ public void configure() {
+
+ /* You can either configure the client inline */
+ from("direct:cxfUriParamsClient")
+ .to("cxf://http://localhost:8082/calculator-ws?wsdlURL=wsdl/CalculatorService.wsdl&dataFormat=POJO&serviceClass=org.foo.CalculatorService");
+
+ /* Or you can use a named bean produced below by beanClient() method */
+ from("direct:cxfBeanClient")
+ .to("cxf:bean:beanClient?dataFormat=POJO");
+
+ }
+
+ @Produces
+ @SessionScoped
+ @Named
+ CxfEndpoint beanClient() {
+ final CxfEndpoint result = new CxfEndpoint();
+ result.setServiceClass(CalculatorService.class);
+ result.setAddress("http://localhost:8082/calculator-ws");
+ result.setWsdlURL("wsdl/CalculatorService.wsdl"); // a resource in the class path
+ return result;
+ }
+}
+----
+
+The `CalculatorService` may look like the following:
+
+[source,java]
+----
+import {javaxOrJakartaPackagePrefix}.jws.WebMethod;
+import {javaxOrJakartaPackagePrefix}.jws.WebService;
+
+@WebService(targetNamespace = CalculatorService.TARGET_NS) // <1>
+public interface CalculatorService {
+
+ public static final String TARGET_NS = "http://acme.org/wscalculator/Calculator";
+
+ @WebMethod // <1>
+ public int add(int intA, int intB);
+
+ @WebMethod // <1>
+ public int subtract(int intA, int intB);
+
+ @WebMethod // <1>
+ public int divide(int intA, int intB);
+
+ @WebMethod // <1>
+ public int multiply(int intA, int intB);
+}
+----
+
+<1> NOTE: JAX-WS annotations are required. The Simple CXF Frontend is not supported. Complex parameter types require JAXB annotations to work in properly in native mode.
+
+[TIP]
+You can test this client application against the https://quay.io/repository/l2x6/calculator-ws[quay.io/l2x6/calculator-ws:1.2] container that implements this service endpoint interface:
++
+[source,shell]
+----
+$ docker run -p 8082:8080 quay.io/l2x6/calculator-ws:1.2
+----
+
+NOTE: `quarkus-cxf` supports {link-quarkus-cxf-doc}/user-guide/first-soap-client.html[injecting SOAP clients]
+ using `@io.quarkiverse.cxf.annotation.CXFClient` annotation.
+ Refer to the {link-quarkus-cxf-doc}/user-guide/first-soap-client.html[SOAP Clients] chapter of `quarkus-cxf` user guide for more details.
+
+[id="extensions-cxf-soap-usage-server"]
+=== Server
+
+With `camel-quarkus-cxf-soap`, you can expose SOAP endpoints as consumers in Camel routes.
+No additional dependencies are required for this use case.
+
+[source,java]
+----
+import org.apache.camel.builder.RouteBuilder;
+import {javaxOrJakartaPackagePrefix}.enterprise.context.ApplicationScoped;
+import {javaxOrJakartaPackagePrefix}.enterprise.inject.Produces;
+import {javaxOrJakartaPackagePrefix}.inject.Named;
+
+@ApplicationScoped
+public class CxfSoapRoutes extends RouteBuilder {
+
+ @Override
+ public void configure() {
+ /* A CXF Service configured through a CDI bean */
+ from("cxf:bean:helloBeanEndpoint")
+ .setBody().simple("Hello ${body} from CXF service");
+
+ /* A CXF Service configured through Camel URI parameters */
+ from("cxf:///hello-inline?wsdlURL=wsdl/HelloService.wsdl&serviceClass=org.foo.HelloService")
+ .setBody().simple("Hello ${body} from CXF service");
+ }
+
+ @Produces
+ @ApplicationScoped
+ @Named
+ CxfEndpoint helloBeanEndpoint() {
+ final CxfEndpoint result = new CxfEndpoint();
+ result.setServiceClass(HelloService.class);
+ result.setAddress("/hello-bean");
+ result.setWsdlURL("wsdl/HelloService.wsdl");
+ return result;
+ }
+}
+----
+
+The path under which these two services will be served depends on the value of `quarkus.cxf.path`
+{link-quarkus-cxf-doc}/reference/extensions/quarkus-cxf.html#quarkus-cxf_quarkus.cxf.path[configuration property]
+which can for example be set in `application.properties`:
+
+.application.properties
+[source,properties]
+----
+quarkus.cxf.path = /soap-services
+----
+
+With this configuration in place, our two services can be reached under `http://localhost:8080/soap-services/hello-bean`
+and `http://localhost:8080/soap-services/hello-inline` respectively.
+
+The WSDL can be accessed by adding `?wsdl` to the above URLs.
+
+IMPORTANT: Do not use `quarkus.cxf.path = /` in your application unless you are 100% sure that no other extension will want to expose HTTP endpoints.
++
+Before `quarkus-cxf` 2.0.0 (i.e. before {project-name} 3.0.0), the default value of `quarkus.cxf.path` was `/`. The default was changed because it prevented other Quarkus extensions from exposing any further HTTP endpoints.
+Among others, RESTEasy, Vert.x, SmallRye Health (no health endpoints exposed!) were impacted by this.
+
+NOTE: `quarkus-cxf` supports alternative ways of exposing SOAP endpoints.
+ Refer to the {link-quarkus-cxf-doc}/user-guide/first-soap-web-service.html[SOAP Services] chapter of `quarkus-cxf` user guide for more details.
+
+[id="extensions-cxf-soap-usage-logging-of-requests-and-responses"]
+=== Logging of requests and responses
+
+You can enable verbose logging of SOAP messages for both clients and servers with `org.apache.cxf.ext.logging.LoggingFeature`:
+
+[source,java]
+----
+import org.apache.camel.builder.RouteBuilder;
+import org.apache.cxf.ext.logging.LoggingFeature;
+import {javaxOrJakartaPackagePrefix}.enterprise.context.ApplicationScoped;
+import {javaxOrJakartaPackagePrefix}.enterprise.context.SessionScoped;
+import {javaxOrJakartaPackagePrefix}.enterprise.inject.Produces;
+import {javaxOrJakartaPackagePrefix}.inject.Named;
+
+@ApplicationScoped
+public class MyBeans {
+
+ @Produces
+ @ApplicationScoped
+ @Named("prettyLoggingFeature")
+ public LoggingFeature prettyLoggingFeature() {
+ final LoggingFeature result = new LoggingFeature();
+ result.setPrettyLogging(true);
+ return result;
+ }
+
+ @Inject
+ @Named("prettyLoggingFeature")
+ LoggingFeature prettyLoggingFeature;
+
+ @Produces
+ @SessionScoped
+ @Named
+ CxfEndpoint cxfBeanClient() {
+ final CxfEndpoint result = new CxfEndpoint();
+ result.setServiceClass(CalculatorService.class);
+ result.setAddress("https://acme.org/calculator");
+ result.setWsdlURL("wsdl/CalculatorService.wsdl");
+ result.getFeatures().add(prettyLoggingFeature);
+ return result;
+ }
+
+ @Produces
+ @ApplicationScoped
+ @Named
+ CxfEndpoint helloBeanEndpoint() {
+ final CxfEndpoint result = new CxfEndpoint();
+ result.setServiceClass(HelloService.class);
+ result.setAddress("/hello-bean");
+ result.setWsdlURL("wsdl/HelloService.wsdl");
+ result.getFeatures().add(prettyLoggingFeature);
+ return result;
+ }
+}
+----
+
+NOTE: The support for `org.apache.cxf.ext.logging.LoggingFeature` is provided by `io.quarkiverse.cxf:quarkus-cxf-rt-features-logging` as a `camel-quarkus-cxf-soap` dependency. You do not need to add it explicitly to your application.
+
+[id="extensions-cxf-soap-usage-ws-specifications"]
+=== WS Specifications
+
+The extent of supported WS specifications is given by the Quarkus CXF project.
+
+`camel-quarkus-cxf-soap` covers the following specifications via the `{link-quarkus-cxf-doc}/reference/extensions/quarkus-cxf.html[io.quarkiverse.cxf:quarkus-cxf]` extension:
+
+* JAX-WS
+* JAXB
+* WS-Addressing
+* WS-Policy
+* MTOM
+
+If your application requires some other WS specification, you must add an additional Quarkus CXF dependency covering it.
+Refer to Quarkus CXF {link-quarkus-cxf-doc}/reference/index.html[Reference] page to see which WS specifications are covered by which Quarkus CXF extensions.
+
+TIP: Both {project-name} and Quarkus CXF contain a number of
+ {link-camel-quarkus-source}/integration-test-groups/cxf-soap[integration]
+ {link-quarkus-cxf-source}/integration-tests[tests] which can serve as executable examples
+ of applications that implement various WS specifications.
+
+[id="extensions-cxf-soap-usage-tooling"]
+=== Tooling
+
+`quarkus-cxf` wraps the following two CXF tools:
+
+* `wsdl2Java` - for {link-quarkus-cxf-doc}/user-guide/first-soap-client.html#wsdl2java[generating service classes from WSDL]
+* `java2ws` - for {link-quarkus-cxf-doc}/user-guide/generate-wsdl-from-java.html[generating WSDL from Java classes]
+
+IMPORTANT: For `wsdl2Java` to work properly, your application will have to directly depend on `io.quarkiverse.cxf:quarkus-cxf`.
+
diff --git a/extensions/cxf-soap/runtime/src/main/doc/usage.adoc b/extensions/cxf-soap/runtime/src/main/doc/usage.adoc
new file mode 100644
index 0000000000..73da8af485
--- /dev/null
+++ b/extensions/cxf-soap/runtime/src/main/doc/usage.adoc
@@ -0,0 +1,239 @@
+=== General
+
+`camel-quarkus-cxf-soap` uses extensions from the {link-quarkus-cxf-doc}[CXF Extensions for Quarkus] project - `quarkus-cxf`.
+This means the set of supported use cases and WS specifications is largely given by `quarkus-cxf`.
+
+IMPORTANT: To learn about supported use cases and WS specifications, see the Quarkus CXF {link-quarkus-cxf-doc}/reference/index.html[Reference].
+
+=== Dependency management
+
+The CXF and `quarkus-cxf` versions are xref:user-guide/dependency-management.adoc[managed] by {project-name}. You do not need select compatible versions for those projects.
+
+=== Client
+
+With `camel-quarkus-cxf-soap` (no additional dependencies required), you can use CXF clients as producers in Camel routes:
+
+[source,java]
+----
+import org.apache.camel.builder.RouteBuilder;
+import {javaxOrJakartaPackagePrefix}.enterprise.context.ApplicationScoped;
+import {javaxOrJakartaPackagePrefix}.enterprise.context.SessionScoped;
+import {javaxOrJakartaPackagePrefix}.enterprise.inject.Produces;
+import {javaxOrJakartaPackagePrefix}.inject.Named;
+
+@ApplicationScoped
+public class CxfSoapClientRoutes extends RouteBuilder {
+
+ @Override
+ public void configure() {
+
+ /* You can either configure the client inline */
+ from("direct:cxfUriParamsClient")
+ .to("cxf://http://localhost:8082/calculator-ws?wsdlURL=wsdl/CalculatorService.wsdl&dataFormat=POJO&serviceClass=org.foo.CalculatorService");
+
+ /* Or you can use a named bean produced below by beanClient() method */
+ from("direct:cxfBeanClient")
+ .to("cxf:bean:beanClient?dataFormat=POJO");
+
+ }
+
+ @Produces
+ @SessionScoped
+ @Named
+ CxfEndpoint beanClient() {
+ final CxfEndpoint result = new CxfEndpoint();
+ result.setServiceClass(CalculatorService.class);
+ result.setAddress("http://localhost:8082/calculator-ws");
+ result.setWsdlURL("wsdl/CalculatorService.wsdl"); // a resource in the class path
+ return result;
+ }
+}
+----
+
+The `CalculatorService` may look like the following:
+
+[source,java]
+----
+import {javaxOrJakartaPackagePrefix}.jws.WebMethod;
+import {javaxOrJakartaPackagePrefix}.jws.WebService;
+
+@WebService(targetNamespace = CalculatorService.TARGET_NS) // <1>
+public interface CalculatorService {
+
+ public static final String TARGET_NS = "http://acme.org/wscalculator/Calculator";
+
+ @WebMethod // <1>
+ public int add(int intA, int intB);
+
+ @WebMethod // <1>
+ public int subtract(int intA, int intB);
+
+ @WebMethod // <1>
+ public int divide(int intA, int intB);
+
+ @WebMethod // <1>
+ public int multiply(int intA, int intB);
+}
+----
+
+<1> NOTE: JAX-WS annotations are required. The Simple CXF Frontend is not supported. Complex parameter types require JAXB annotations to work in properly in native mode.
+
+[TIP]
+You can test this client application against the https://quay.io/repository/l2x6/calculator-ws[quay.io/l2x6/calculator-ws:1.2] container that implements this service endpoint interface:
++
+[source,shell]
+----
+$ docker run -p 8082:8080 quay.io/l2x6/calculator-ws:1.2
+----
+
+NOTE: `quarkus-cxf` supports {link-quarkus-cxf-doc}/user-guide/first-soap-client.html[injecting SOAP clients]
+ using `@io.quarkiverse.cxf.annotation.CXFClient` annotation.
+ Refer to the {link-quarkus-cxf-doc}/user-guide/first-soap-client.html[SOAP Clients] chapter of `quarkus-cxf` user guide for more details.
+
+=== Server
+
+With `camel-quarkus-cxf-soap`, you can expose SOAP endpoints as consumers in Camel routes.
+No additional dependencies are required for this use case.
+
+[source,java]
+----
+import org.apache.camel.builder.RouteBuilder;
+import {javaxOrJakartaPackagePrefix}.enterprise.context.ApplicationScoped;
+import {javaxOrJakartaPackagePrefix}.enterprise.inject.Produces;
+import {javaxOrJakartaPackagePrefix}.inject.Named;
+
+@ApplicationScoped
+public class CxfSoapRoutes extends RouteBuilder {
+
+ @Override
+ public void configure() {
+ /* A CXF Service configured through a CDI bean */
+ from("cxf:bean:helloBeanEndpoint")
+ .setBody().simple("Hello ${body} from CXF service");
+
+ /* A CXF Service configured through Camel URI parameters */
+ from("cxf:///hello-inline?wsdlURL=wsdl/HelloService.wsdl&serviceClass=org.foo.HelloService")
+ .setBody().simple("Hello ${body} from CXF service");
+ }
+
+ @Produces
+ @ApplicationScoped
+ @Named
+ CxfEndpoint helloBeanEndpoint() {
+ final CxfEndpoint result = new CxfEndpoint();
+ result.setServiceClass(HelloService.class);
+ result.setAddress("/hello-bean");
+ result.setWsdlURL("wsdl/HelloService.wsdl");
+ return result;
+ }
+}
+----
+
+The path under which these two services will be served depends on the value of `quarkus.cxf.path`
+{link-quarkus-cxf-doc}/reference/extensions/quarkus-cxf.html#quarkus-cxf_quarkus.cxf.path[configuration property]
+which can for example be set in `application.properties`:
+
+.application.properties
+[source,properties]
+----
+quarkus.cxf.path = /soap-services
+----
+
+With this configuration in place, our two services can be reached under `http://localhost:8080/soap-services/hello-bean`
+and `http://localhost:8080/soap-services/hello-inline` respectively.
+
+The WSDL can be accessed by adding `?wsdl` to the above URLs.
+
+IMPORTANT: Do not use `quarkus.cxf.path = /` in your application unless you are 100% sure that no other extension will want to expose HTTP endpoints.
++
+Before `quarkus-cxf` 2.0.0 (i.e. before {project-name} 3.0.0), the default value of `quarkus.cxf.path` was `/`. The default was changed because it prevented other Quarkus extensions from exposing any further HTTP endpoints.
+Among others, RESTEasy, Vert.x, SmallRye Health (no health endpoints exposed!) were impacted by this.
+
+NOTE: `quarkus-cxf` supports alternative ways of exposing SOAP endpoints.
+ Refer to the {link-quarkus-cxf-doc}/user-guide/first-soap-web-service.html[SOAP Services] chapter of `quarkus-cxf` user guide for more details.
+
+=== Logging of requests and responses
+
+You can enable verbose logging of SOAP messages for both clients and servers with `org.apache.cxf.ext.logging.LoggingFeature`:
+
+[source,java]
+----
+import org.apache.camel.builder.RouteBuilder;
+import org.apache.cxf.ext.logging.LoggingFeature;
+import {javaxOrJakartaPackagePrefix}.enterprise.context.ApplicationScoped;
+import {javaxOrJakartaPackagePrefix}.enterprise.context.SessionScoped;
+import {javaxOrJakartaPackagePrefix}.enterprise.inject.Produces;
+import {javaxOrJakartaPackagePrefix}.inject.Named;
+
+@ApplicationScoped
+public class MyBeans {
+
+ @Produces
+ @ApplicationScoped
+ @Named("prettyLoggingFeature")
+ public LoggingFeature prettyLoggingFeature() {
+ final LoggingFeature result = new LoggingFeature();
+ result.setPrettyLogging(true);
+ return result;
+ }
+
+ @Inject
+ @Named("prettyLoggingFeature")
+ LoggingFeature prettyLoggingFeature;
+
+ @Produces
+ @SessionScoped
+ @Named
+ CxfEndpoint cxfBeanClient() {
+ final CxfEndpoint result = new CxfEndpoint();
+ result.setServiceClass(CalculatorService.class);
+ result.setAddress("https://acme.org/calculator");
+ result.setWsdlURL("wsdl/CalculatorService.wsdl");
+ result.getFeatures().add(prettyLoggingFeature);
+ return result;
+ }
+
+ @Produces
+ @ApplicationScoped
+ @Named
+ CxfEndpoint helloBeanEndpoint() {
+ final CxfEndpoint result = new CxfEndpoint();
+ result.setServiceClass(HelloService.class);
+ result.setAddress("/hello-bean");
+ result.setWsdlURL("wsdl/HelloService.wsdl");
+ result.getFeatures().add(prettyLoggingFeature);
+ return result;
+ }
+}
+----
+
+NOTE: The support for `org.apache.cxf.ext.logging.LoggingFeature` is provided by `io.quarkiverse.cxf:quarkus-cxf-rt-features-logging` as a `camel-quarkus-cxf-soap` dependency. You do not need to add it explicitly to your application.
+
+=== WS Specifications
+
+The extent of supported WS specifications is given by the Quarkus CXF project.
+
+`camel-quarkus-cxf-soap` covers the following specifications via the `{link-quarkus-cxf-doc}/reference/extensions/quarkus-cxf.html[io.quarkiverse.cxf:quarkus-cxf]` extension:
+
+* JAX-WS
+* JAXB
+* WS-Addressing
+* WS-Policy
+* MTOM
+
+If your application requires some other WS specification, you must add an additional Quarkus CXF dependency covering it.
+Refer to Quarkus CXF {link-quarkus-cxf-doc}/reference/index.html[Reference] page to see which WS specifications are covered by which Quarkus CXF extensions.
+
+TIP: Both {project-name} and Quarkus CXF contain a number of
+ {link-camel-quarkus-source}/integration-test-groups/cxf-soap[integration]
+ {link-quarkus-cxf-source}/integration-tests[tests] which can serve as executable examples
+ of applications that implement various WS specifications.
+
+=== Tooling
+
+`quarkus-cxf` wraps the following two CXF tools:
+
+* `wsdl2Java` - for {link-quarkus-cxf-doc}/user-guide/first-soap-client.html#wsdl2java[generating service classes from WSDL]
+* `java2ws` - for {link-quarkus-cxf-doc}/user-guide/generate-wsdl-from-java.html[generating WSDL from Java classes]
+
+IMPORTANT: For `wsdl2Java` to work properly, your application will have to directly depend on `io.quarkiverse.cxf:quarkus-cxf`.