Create a SOAP Web Service: A Step-by-Step Tutorial

SOAP (Simple Object Access Protocol) web services provide a standardized way for applications to communicate over the web. In this tutorial, we’ll walk through the process of creating a SOAP web service in IntelliJ IDEA using Jakarta EE and deploying it on the Apache Tomcat server. Our example will be a simple calculator service that adds two numbers.

Step 1: Set Up Your IntelliJ Project

Let’s create a project to write our first SOAP application.

Step 2: Add Dependencies

Add the following dependencies to your pom.xml file to ensure your project has the necessary libraries.

• Purpose: This dependency provides the Jakarta API for Java API for XML Web Services (JAX-WS).
• Explanation: JAX-WS is a set of APIs for creating web services in Java. The jakarta.jws-api dependency includes annotations and interfaces used in JAX-WS, such as @WebService and @WebMethod. These annotations are essential for defining web services and their operations.

<dependency>
      <groupId>jakarta.jws</groupId>
      <artifactId>jakarta.jws-api</artifactId>
      <version>3.0.0</version>
    </dependency>

• Purpose: This dependency includes the JAX-WS Reference Implementation (RI) from Oracle.
• Explanation: JAX-WS is a specification, and the Reference Implementation provides the actual implementation of the specification. It includes runtime libraries and tools necessary for deploying and running JAX-WS web services. In this case, it’s used to support the runtime behavior of your web service.

<dependency>
      <groupId>com.sun.xml.ws</groupId>
      <artifactId>jaxws-ri</artifactId>
      <version>4.0.0</version>
</dependency>

• Purpose: This dependency includes the JAX-WS runtime libraries.
• Explanation: Similar to jaxws-ri, jaxws-rt provides runtime libraries for JAX-WS. It includes classes and resources required during the execution of JAX-WS web services. Including this dependency ensures that your application has access to the necessary runtime components.

<dependency>
      <groupId>com.sun.xml.ws</groupId>
      <artifactId>jaxws-rt</artifactId>
      <version>4.0.0</version>
</dependency>

Step 3: Write the CalculatorWebService Class

First create CalculatorWebService interface. The interface (CalculatorWebService) serves as an abstraction, defining a contract for what the service should do without specifying how it achieves those functionalities.

By having an interface, you separate the definition of the service’s behavior from its implementation. This separation allows you to change the underlying implementation without affecting the code that uses the service.

import jakarta.jws.WebMethod;
import jakarta.jws.WebService;

@WebService
public interface CalculatorWebService{
    @WebMethod
    int add(int num1, int num2);
}

Now let’s implement this interface.

• @WebService: This annotation marks this class as a web service endpoint. It is part of the Jakarta API for XML Web Services (JAX-WS). By annotating the interface with @WebService, you are indicating that this interface defines a service contract for a web service.
• @WebMethod: This annotation is used to mark a method as a web service operation. In this case, the add method is annotated with @WebMethod, signifying that it is an operation exposed by the web service.

import jakarta.jws.WebMethod;
import jakarta.jws.WebService;

@WebService
public class CalculatorWebServiceImpl implements CalculatorWebService {
    @WebMethod
    public int add(int num1, int num2) {
        return num1 + num2;
    }
}

Step 4: Configure web.xml

web.xml file, is a deployment descriptor used in Jakarta EE applications to define the structure and configuration of the web application. In this step, we are configuring the web.xml file to define the necessary servlets and mappings for our SOAP web service.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
         version="5.0">

    <display-name>SOAPWithJaxWS</display-name>
    <listener>
        <listener-class>
            com.sun.xml.ws.transport.http.servlet.WSServletContextListener
        </listener-class>
    </listener>
    <servlet>
        <servlet-name>CalculatorWebService</servlet-name>
        <servlet-class>
            com.sun.xml.ws.transport.http.servlet.WSServlet
        </servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>CalculatorWebService</servlet-name>
        <url-pattern>/calculatorWebService</url-pattern>
    </servlet-mapping>
</web-app>

<web-app> Element: Declares the root element of the web.xml file and specifies the Jakarta EE version.

<display-name> Element: Provides a display name for the web application.

<listener> Element: Registers a context listener, WSServletContextListener, which is required for JAX-WS (Java API for XML Web Services) support. This listener initializes the JAX-WS runtime.

<servlet> Element: Configures a servlet named CalculatorWebService. Specifies the servlet class as com.sun.xml.ws.transport.http.servlet.WSServlet. This servlet is part of JAX-WS and is responsible for handling web service requests.

<load-on-startup> is set to 1, indicating that the servlet should be loaded when the application starts.

<servlet-mapping> Element: Maps the CalculatorWebService servlet to a URL pattern /calculatorWebService. This URL is where clients can access the web service.

Step 5: Create sun-jaxws.xml

sun-jaxws.xml file is used to configure the endpoint for your SOAP web service. This file specifies details about the web service endpoint, such as the implementation class and the URL pattern. Here's a breakdown of the contents and purpose of sun-jaxws.xml:

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime" version="2.0">
    <endpoint
            implementation="com.uok.webservice.CalculatorWebServiceImpl"
            name="CalculatorWebService"
            url-pattern="/calculatorWebService" />
</endpoints>

• implementation: Class path of the implementation class
• url-pattern: what you defined in the web.xml

Step 6: Configure your web server

For this tutorial, we’re using the Apache Tomcat Server. Make sure to configure your web server to deploy and run your SOAP web service.

Web server configurations

Now run the project.

Step 7: Access the WSDL File

In a web browser, navigate to the following URL to access the WSDL file of your deployed SOAP web service:

http://localhost:<port>/<your_project_name>/calculatorWebService?wsdl

wsdl file

Understanding WSDL

WSDL, or Web Services Description Language, is an XML-based language that provides a standardized way to describe the functionalities offered by a web service. It acts as a contract between the service provider and the service consumer, defining how the communication between them should occur.

Purpose of WSDL

Service Interface Definition: WSDL defines the methods (operations) exposed by the web service, along with the input and output parameters for each operation.

Communication Protocol and Binding: It specifies how the service can be accessed over the network, including details about the protocol (e.g., HTTP) and data format (e.g., XML) used for communication.

Location of the Service: WSDL includes information about where the service is located (its endpoint address).

Machine-Readable Contract: WSDL provides a machine-readable contract that clients can use to understand how to interact with the web service.

Importance of WSDL

• Interoperability: WSDL promotes interoperability by providing a standard way for different platforms and technologies to understand and communicate with web services.
• Tool Support: WSDL is used by various tools to generate client-side code, enabling developers to easily integrate and consume web services.
• Contract-First Development: WSDL supports a contract-first approach, where the service contract is defined before the actual implementation, ensuring a clear separation between service definition and implementation.
• Documentation: WSDL serves as documentation for the web service, allowing developers and clients to understand its capabilities and how to interact with it.

Step 8: Testing the web service

Testing a SOAP web service from applications like Postman or SoapUI sending SOAP requests to the service endpoint. However, Postman is typically used for RESTful APIs, and it may not have built-in support for SOAP. Nevertheless, you can use Postman to send HTTP requests with the required SOAP envelope.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservice.uok.com/">
    <soapenv:Header/>
    <soapenv:Body>
        <web:add>
            <num1>2</num1>
            <num2>3</num2>
        </web:add>
    </soapenv:Body>
</soapenv:Envelope>

Reference: https://github.com/DharshithaSrimal/UOK-Web-Practicals/tree/main/Web%20Services/WebService