SOAP Web Services with Quarkus made easy

In this step-by-step guide we will learn how to code, run and test SOAP web services using the Quarkus CXF Extensions. We will first learn how to deploy a simple SOAP Web services and then we will consume it with different Clients such as SOAP UI, Java Client or a Camel CXF Consumer.

Prerequisites

Before we begin, make sure you have the following installed:

  • Java Development Kit (JDK) 11 or later
  • Apache Maven
  • Quarkus CLI or Quarkus Initializer

Step 1: Create a new Quarkus project

Open your terminal and navigate to the directory where you want to create the project. Run the following command to create a new Quarkus project:

quarkus create

This command will create a new Quarkus project. Next, we will be adding the following dependencies in our project:

<dependency>
      <groupId>io.quarkiverse.cxf</groupId>
      <artifactId>quarkus-cxf</artifactId>
</dependency>
<dependency>
        <groupId>io.quarkiverse.cxf</groupId>
        <artifactId>quarkus-cxf-test-util</artifactId>
        <version>2.1.0</version>
        <scope>test</scope>
</dependency>

The first dependency is the main quarkus-cxf extension. Then, we can optionally use the quarkus-cxf-test-util which simplifies testing CXF Web Service.

Step 2: Define the CXF web service

Navigate to the project directory and add the following Interface to define the Web Service Contract:

@WebService(name = "HelloService", serviceName = "HelloService")
public interface HelloService {

    @WebMethod
    String sayHello(String text);

}

The above Web services defines a minimal contract for the “HelloService” Web service which exposes one @Webmethod “sayHello” that takes as input a String and also returns a String.

Next, let’s add the WebService implementation of the HelloService:

@WebService(serviceName = "HelloService")
public class HelloServiceImpl implements HelloService {

    @WebMethod
    @Override
    public String sayHello(String text) {
        return "Hello " + text + "!";
    }

}

In this code, we have defined a simple web service with a single method sayHello that takes a name as input and returns a greeting message.

Step 3: Configure the CXF web service

Open the src/main/resources/application.properties file and add the following configuration:

quarkus.cxf.path=/services

This configuration sets the base path for our CXF web services to /services. The default base path for CXF Web Services is already set to “/services” therefore we include it only as reference for this property

Step 4: Build and run the Quarkus application

Save all the changes you made so far. Open your terminal and run the following command to build and run the Quarkus application:

mvn install quarkus:dev

This command will start the Quarkus development mode and deploy the application.

Step 5: Test the CXF web service

Since the Service name is “HelloServices“, you will be able to access the WSDL Contract of your Web service at the following address: http://localhost:8080/services/HelloService?wsdl

Verify that the Web Service WSDL is available by opening the browser or curling it from the command line:

curl http://localhost:8080/services/HelloService?wsdl

Finally, using any SOAP Client, you can test the sayHello method passing any text argument. For example, using SOAP UI:

quarkus soap web service integration

Step 5: Adding a Java Test Client

To test our Web Service we can use the io.quarkiverse.cxf.test.QuarkusCxfClientTestUtil Class which simplifies getting the Web Service interface and invoking methods:

@QuarkusTest
public class HelloServiceTest {

    @Test
    public void hello() {
        final HelloService client = QuarkusCxfClientTestUtil.getClient(HelloService.class, "/services/HelloService");
        Assertions.assertEquals("Hello World!", client.sayHello("World"));
    }

}

You can run your @QuarkusTest by running the test Maven goal or simply by running an install goal:

mvn clean install

Consuming the Web Service from Camel

Quarkus Camel Extensions also include a specific extension to use CXF Web Services from a Camel Route. Firstly, we need to add to your project the camel-quarkus-cxf extension and the camel-quarkus-core extension. Additionally, include any other Camel component you will need in your Route such as the Timer Component:

<dependency>
   <groupId>org.apache.camel.quarkus</groupId>
   <artifactId>camel-quarkus-cxf-soap</artifactId>
</dependency>

<dependency>
   <groupId>org.apache.camel.quarkus</groupId>
   <artifactId>camel-quarkus-core</artifactId>
</dependency>

<dependency>
   <groupId>org.apache.camel.quarkus</groupId>
   <artifactId>camel-quarkus-timer</artifactId>
</dependency>

Then, let’s code a minimal Camel Route to access the SOAP Web Service:

@ApplicationScoped
public class HelloServiceConsumerRoute extends RouteBuilder {

    @Override
    public void configure() throws Exception {
        from("timer://foo?repeatCount=1")
        .setBody(simple("Frank")) // Set the request payload
            .to("cxf:http://localhost:8080/services/HelloService?serviceClass=com.sample.HelloService")
            .log("Response: ${body}");
    }
}

Within this Route, we are triggering a single Timer execution and set the MessageExchange body with a String. The Message goes into the CXF Component through the “/services/HelloService” URI of the ServiceClass com.sample.HelloService.

Rebuild your application and check on the Console logs that the SOAP Response is printed:

2023-06-02 18:25:27,455 INFO  [route14] (default-workqueue-1) Response: Hello Frank!

Conclusion

In this tutorial, we have learned how to integrate CXF web services with Quarkus. We created a simple web service using CXF, configured it in our Quarkus application, and tested it using the web service WSDL page. With the power of CXF and the efficiency of Quarkus, you can now build robust and scalable web services in Java.

Source code for this tutorial: https://github.com/fmarchioni/mastertheboss/tree/master/quarkus/cxf

Found the article helpful? if so please follow us on Socials