How to configure SOAP web services with Apache Camel

This article demonstrates how to configure Simple Object Access Protocol (SOAP) web services with the Red Hat build of Apache Camel, Quarkus version. In Apache Camel version 3, the support for the SOAP protocol is still provided by the CXF framework. Therefore, on Quarkus, we will be relying on the camel-quarkus-cxf-soap extension.

A common REST to SOAP transformation use case

With the CXF runtime, there is a distinction to make between a SOAP service and the client of a SOAP service.

Let's use a very common use case to demonstrate those two parts distinctively. Let's imagine a legacy SOAP web service backend that we want to expose behind a REST endpoint (Figure 1).

You can find the source code of the two applications developed for that purpose on this GitHub page.

The SOAP web service backend is represented by a mock implementation of a publicly available definition, sourced from herongyang.com. The web service at play is Registration SOAP 1.1.

For both the CXF client and server development, the first step is to generate the Java objects corresponding to the WSDL elements. This can be done with the cxf-codegen-plugin Maven plugin, whose wsdl2java task generates Java representations of the soap request and response payloads, as well as the service interface and its implementation (PortType).

$ tree target/generated-sources/cxf
target/generated-sources/cxf
└── https
    └── www_herongyang_com
        └── service
            ├── ObjectFactory.java
            ├── package-info.java
            ├── RegistrationPortType.java
            ├── RegistrationRequest.java
            ├── RegistrationResponse.java
            └── RegistrationService.java

Configuring a Camel CXF SOAP server

Let's now dig into the core part of the configuration.

On the server side, there is a Camel route that starts with the following line:

from("cxf:registration?serviceClass=https.www_herongyang_com.service.RegistrationPortType")

The second element of the endpoint URI is the name of a CxfEndpoint Java bean that contains the configuration of the CXF endpoint such as the service name, endpoint name, and exposed URL.

@Named("registration")
@ApplicationScoped
public class SoapServiceBean extends CxfEndpoint {

    public SoapServiceBean() {
        super();

        try {
            this.configure();
        } catch (ClassNotFoundException e) {
            e.printStackTrace();
        }

    }

    private void configure() throws ClassNotFoundException {

       QName serviceQname = new QName("https://www.herongyang.com/Service/", "registrationService");    // From WSDL :: <wsdl:service name="registrationService">
       this.setServiceNameAsQName(serviceQname);

       QName endpointQname = new QName("https://www.herongyang.com/Service/", "registrationPort");    // From WSDL :: <wsdl:port name="registrationPort">
       this.setEndpointNameAsQName(endpointQname);

       this.setAddress("http://localhost:8055/soap/registration");                    // Exposed address with the /soap root context defined in application.properties

    }
}

That's it!

With that configuration, the web service should be available at http://localhost:8085/soap/registration. We can test it with SOAPUI using the following request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="https://www.herongyang.com/Service/">  
<<soap:Header/>>  
   <<soap:Body>>  
      <ser:RegistrationRequest date="now" event="123">
         <Guest>John</Guest>
      </ser:RegistrationRequest>
   </soap:Body>  
</soap:Envelope>

Configuring a Camel CXF SOAP client

In the case of a client, the CxfEndpoint bean is not required. The URI can directly embed the target address as follows:

 .to("cxf:http://localhost:8055/soap/registration?serviceClass=https.www_herongyang_com.service.RegistrationPortType")

You can attempt an end-to-end test with the following command:

curl -H "Content-Type: application/json" -XPOST http://localhost:8050/api/registration -d '{"event":"123","guest":"john"}'

Applying WS-Security or other SOAP features

The CXF framework still builds on the concept of interceptors and interceptors chain. On Quarkus, interceptors are injected into the CXF runtime in Java.  The hook to the CXF runtime is the cxfConfigurer option of the URI endpoint.

For the server, the endpoint URI becomes:

from("cxf:registration?serviceClass=https.www_herongyang_com.service.RegistrationPortType&cxfConfigurer=#mywssecurity")

On the other hand, for the client, it becomes:

to("cxf:http://localhost:8055/soap/registration?serviceClass=https.www_herongyang_com.service.RegistrationPortType&cxfConfigurer=#mywssecurity")

On both lines, the mywssecurity element is a reference to a Java bean that implements the CxfConfigurer interface. This interface has methods to configure either the CXF server, client, or both. Thus, in our case, on the client side, we have:

@Named("mywssecurity")
@ApplicationScoped
public class WSServiceBean implements CxfConfigurer {

    @Inject
    @ConfigProperty (name = "app.webservice.soap.wssecurity.user")        // custom property defined in application.properties
    private String user;

    @Inject
    @ConfigProperty (name = "app.webservice.soap.wssecurity.mustunderstand")    // custom property defined in application.properties
    private String mustunderstand;

    public WSServiceBean() {
        super();
    }


    @Override
    public void configure(AbstractWSDLBasedEndpointFactory factoryBean) {
        // TODO Auto-generated method stub
        //throw new UnsupportedOperationException("Unimplemented method 'configure'");
    }

    @Override
    public void configureClient(Client client) {

        Map<String,Object> wsproperties = new HashMap<String, Object>();
        wsproperties.put(ConfigurationConstants.ACTION, ConfigurationConstants.USERNAME_TOKEN_NO_PASSWORD);
        wsproperties.put(ConfigurationConstants.ALLOW_USERNAMETOKEN_NOPASSWORD, "true");
        wsproperties.put(ConfigurationConstants.USER, user);
        wsproperties.put(ConfigurationConstants.MUST_UNDERSTAND, mustunderstand);
        WSS4JOutInterceptor wssecurity = new WSS4JOutInterceptor(wsproperties);

        client.getOutInterceptors().add(wssecurity);

        //throw new UnsupportedOperationException("Unimplemented method 'configureClient'");
    }

    @Override
    public void configureServer(Server server) {
        // TODO Auto-generated method stub
        //throw new UnsupportedOperationException("Unimplemented method 'configureServer'");
    }
}

While on the server side, we have the following:

@Named("mywssecurity")
@ApplicationScoped
public class WSServiceBean implements CxfConfigurer {

    @Inject
    @ConfigProperty (name = "app.webservice.soap.wssecurity.user")        // custom property defined in application.properties
    private String user;

    public WSServiceBean() {
        super();
    }


    @Override
    public void configure(AbstractWSDLBasedEndpointFactory factoryBean) {
        // TODO Auto-generated method stub
        //throw new UnsupportedOperationException("Unimplemented method 'configure'");
    }

    @Override
    public void configureClient(Client client) {
        // TODO Auto-generated method stub
        //throw new UnsupportedOperationException("Unimplemented method 'configureClient'");
    }

    @Override
    public void configureServer(Server server) {

        Map<String,Object> wsproperties = new HashMap<String, Object>();
        wsproperties.put(ConfigurationConstants.ACTION, ConfigurationConstants.USERNAME_TOKEN_NO_PASSWORD);
        wsproperties.put(ConfigurationConstants.ALLOW_USERNAMETOKEN_NOPASSWORD, "true");
        wsproperties.put(ConfigurationConstants.USER, user);
        WSS4JInInterceptor wssecurity = new WSS4JInInterceptor(wsproperties);

        server.getEndpoint().getInInterceptors().add(wssecurity);

        //throw new UnsupportedOperationException("Unimplemented method 'configureClient'");
    }
}

Summary

This article demonstrates how to configure SOAP web services with the Red Hat build of Apache Camel, Quarkus version. If you have questions, feel free to comment below. We welcome your feedback!